Chapter 2: Working With Contract Wallets

Contract Accounts and Contract Wallets
How Are Contract Wallets Different From Accounts?
Types of Contract Wallets: Simple Wallets & Multisig Wallets

Simple Wallet
 Sending Ether from a Simple Wallet
Multisig Wallet
 Sending Ether from a Multisig Wallet
Issues Relating to Using Accounts Versus Contract Wallets
 I Just Want to Store My Ether Safely
 Sending Ether
 Receiving Ether
 Receiving Mining Rewards
Transactions That Run out of Gas
Creating “Watch-Only” Wallets
Where Is Your Wallet Data Stored?
 Retrieving an Individual Contract Wallet
Backups of Simple Wallets and Multisig Wallets


Contract Accounts and Contract Wallets

From Chapter 1 we know that Ethereum has two types of accounts: One type, which we have been referring to simply as an Account, we already are quite familiar with having created them and stored ether in them. The other type of account is the Contract Account.

While an Account has a password-protected private key and an address, a Contract Account has no private key but has an address, code, and storage. Contract Wallets (or contract-based wallets) are built with Contract Accounts, utilizing the ability of Contract Accounts to hold and run code with associated persistent storage. Of course, Contract Accounts can be used to do a lot more than just create Contract Wallets. Utilizing Contract Accounts, developers are hard at work creating all kinds of fascinating Decentralized Applications (DApps) right now.


How Are Contract Wallets Different From Accounts?

Accounts can be used as bare stores for ether, though they can also be used to do things other than just hold ether. When they are used to hold ether, Accounts can be thought of simply as private key/address pairs.

The sole function of a Contract Wallet is to manage ether, that is, receive, store and spend ether. Unlike Accounts, Contract Wallets are controlled by code, which means that it is possible to customize their behavior. And, you won’t have to do any coding yourself; the Contract Wallets come with a user interface that makes it easy to simply select the type of security/convenience enhancing customization you require.

Contract Wallets are controlled by code but ultimately that code also has a master, and that master is an Account with its password-protected private key. So Accounts serve two roles; as bare stores of ether in their own right, and as owners (or controllers) of feature-rich Contract Wallets. Exactly how Accounts play their role as owners of Contract Wallets will become apparent as we start creating and using Contract Wallets later.

Advantages of Contract Wallets over Accounts:

  • Contract Wallets can list incoming transactions; something Accounts cannot do.
  • Contract Wallets can be setup as Multisig Wallets.
  • A Multisig Wallet can be structured such that it has a daily limit which you specify, and only if this daily limit is exceeded will multiple signatures be required.
  • Contract Wallets can be setup as “Watch-Only” Wallets.

Downside to Contract Wallets over Accounts:

Creating Accounts does not cost any gas; but creating Contract Wallets does. In fact, Contract Wallets incur a cost whenever you use them. You pay to create and use Contract Wallets because they utilize the valuable computational and storage resources of the network. Paying for the use of these resources is part of the gas economics model of the Ethereum protocol.

So, since you require gas (which is paid for with ether) to create and use a Contract Wallet, ensure that you have at least one Account with some ether in it before proceeding. Just 1 ether will be more than enough to try out Contract Wallets. A list of gas costs for various wallet operations can be found here and the prevailing gas price is always displayed in the Network Stats page.

Types of Contract Wallets: Simple Wallets & Multisig Wallets

Simple Wallets and Multisig Wallets are both examples of Contract Wallets. They are created and owned by Accounts. With a Simple Wallet, only one Account both creates and owns the wallet. A Multisig Wallet has several owner Accounts one of which will also be the creator Account.

An Account playing the role of a Contract Wallet creator, will execute this function only once, as one would expect. Once a Contract Wallet has been created, the role of managing or controlling the wallet will be the responsibility of the owner or owners of the Contract Wallet. The authority of an Account, both when acting as creator and owner of a Contract Wallet, lies in the private key of that Account which is required to sign the necessary transactions. Hence whoever controls that private key is ultimately in charge.

Simple Wallets

A Simple Wallet seems a lot like an Account since only one private key is required to control the wallet, but we now know that under the hood, they are quite different.

To create a Simple Wallet:

  2. Under WALLET CONTRACT TYPE ensure that SINGLE OWNER ACCOUNT is selected, then enter a name for your wallet.
  3. From the drop-down list, select the Account that will be both the creator and owner Account for your new Simple Wallet.
    Ensure that there is some ether in the Account to cover gas costs. About 0.2 ether should be more than enough.

  4. Click on CREATE. Then enter the password of the Account you selected in Step 3.
    Note that the Create Contract window also displays the gas requirements for this transaction.

Sending Ether from a Simple Wallet

The procedure for sending ether from a Simple Wallet is no different from that for sending ether from an Account. The gas cost will be higher though.

Contract Wallets have one minor but nice advantage over Accounts: You can easily sweep (or send ALL of) your balance. This is possible because a Contract Wallet does not pay for gas from its own balance. Rather gas costs are borne by the owner account/s. So you are less likely to see Contract Wallets littered about with small amounts of wei.

Multisig Wallets

These are M-of-N type wallets, where more than one private key is required to have full access to the funds held. In a typical scenario, there may be three owner Accounts with only two required to authorize unlimited spends, making it a 2-of-3 Multisig Wallet. 2-of-2 Multisig Wallets are also common.

Multisig Wallets have the additional functionality of allowing the user to define a daily limit. As long as this daily limit is not exceeded, any one owner Account can authorize a spend transaction.

In practice, Multisig Wallets have two typical use cases:
Use case one: You own some ether and want to store it securely but are concerned that just relying on a single private key may not be safe. So you create a Multisig Wallet, perhaps a 2-of-3 wallet, but all the owner Accounts are under your control, that is, you control all the private keys.
Use case two: You set up a Multisig Account jointly owned by say two people, you and Alice. So you have one private key and Alice the other. Neither of you has access to the other person’s private key of course.

To create a Multisig Wallet:

  1. Ensure that the addresses of the owner Accounts are readily available. For example, have them in a text document so you can easily copy and paste when required.
    The default settings for Multisig Wallets is displayed. In this example, we are going with the default 2-of-3 setting, but we have reduced the daily limit to 10 ether.
  4. Under SELECT OWNER choose the Account that will both serve as the creator of this Multisig Wallet and also be one of the owner Accounts.
    Note that this Account then appears as the first listed Wallet owner.
    Ensure that there is about 0.2 ether in the Account.
  5. Copy and paste the addresses of the other two owner Accounts.
    IMPORTANT: Do not add a Contract Wallet as the owner of a Multisig Wallet. Only Accounts can be owners.

  6. Enter a name for your wallet then select the CREATE button.
  7. Enter the password of the creator Account you selected in Step 4.

Click on your brand new Multisig Wallet in the Accounts Overview screen and you will see its details, including all owner Accounts.

Sending Ether from a Multisig Wallet

When you spend from a Multisig Wallet, all the signing (owner) Accounts must have enough ether in them to pay for gas costs. If not, you will have to revoke the transaction, which will itself incur a revocation cost, adding insult to injury :).

Scenario 1: Your Wallet App has access to all the signing (owner) Account private keys.

To spend from a Multisig Wallet in Scenario 1:

  1. Start by following the usual procedure to spend from any wallet. (See “Sending Ether to Another Account” in Chapter 1 for details if necessary.)
  2. Things get a little different when you enter the AMOUNT. You will see a message below the AMOUNT field informing you whether you are within or have exceeded the daily limit. In this example, we will assume you exceed the set daily limit so requiring the full quota (2-of-3) of Accounts/signatures to authorize the spend.
  3. When you click the SEND button, you will see the Execute Contract window asking for the password to one of the owner Accounts.39ExecuteContractLab

  4. Once you enter the password and press Enter, you will see the following screen asking you to APPROVE or REVOKE the transaction.

  5. On selecting APPROVE you will be asked to select the second signing Account and then enter its password.

Scenario 2: Signing (owner) Account private keys are in different computers.
This is where it gets really interesting, and actually, quite brilliant.

The first step is to ensure that all Wallet Apps participating in the approval/signing of the multisig transaction have already imported the Multisig Wallet. Say you created a Multisig Wallet in your Wallet App using one of your Accounts and an Account from Alice as the owner Accounts. You won’t have the private key to Alice’s Account of course; that will be on her computer. However the Wallet App in her computer won’t have the Multisig Wallet until she imports it. All she needs to import the Multisig Wallet is the wallet’s address.

To import a Multisig Wallet into the Wallet App:

  1. To import a Multisig Wallet into an instance of the Wallet App, click on ADD WALLET CONTRACT, then select IMPORT WALLET and paste the address of the Multisig Wallet in the Wallet Address field. Enter the name of the wallet.
    If the importing Wallet App has an owner Account of this Multisig Wallet, you will see a corresponding message. You should see something like this:

  2. Select CREATE to complete importing the Multisig Wallet.
    This Wallet App is now able to sign multisignature transactions involving the imported Multisig Wallet.

To spend from a Multisig Wallet in Scenario 2:

In this example, we are going to spend an amount in excess of the daily limit from a 2-of-2  Multisig Wallet with owner Accounts on different computers.

  1. Follow the initial steps from the Scenario 1 example above until you see the following in the Wallet App that initiated the transaction:39Scenario2aaLab

    Simultaneously, the other Wallet App (on a different computer) with the second owner Account will display a screen like this:

  2. Select APPROVE in the confirming Wallet App and enter the required password.
    LATEST TRANSACTIONS in both Wallet Apps will show the transaction being confirmed.

Issues Relating to Using Accounts Versus Contract Wallets

I Just Want to Store My Ether Safely

I store my ether in an Account but only because I don’t want the hassle of backing up and keeping secure more than one private key and password. Maybe a more reasonable compromise would be a 2-of-3 Multisig Wallet, with a daily limit and the same password for all three private keys? Some feel that the single most likely point of failure for most people is actually forgetting one’s password.

Bottom line: It’s really a matter of personal choice. See this thread and the comments in this StackExchange answer.

Sending Ether

Firstly, you already know that sending from a Contract Wallet costs a little more than sending from an Account. Most ordinary users who only occasionally send, may be willing to accept the slightly higher gas cost. However, exchanges or other parties that do a lot of sending may not. For them, sending from an Account would be more economical.

Secondly, several receivers especially exchanges may not be setup to receive from Contract Wallets. So, if you send ether to Shapeshift for example, their system will not detect your transfer to them. This is because ether transfers initiated by Contract Wallets (in essence code) still do not appear in some Block Explorers. This situation is improving all the time, for instance Block Explorer is now able to register ether transfers coming from Contract Wallets as easily as from Accounts.

To be safe, for now, use Accounts to send to exchanges and the like.

Thirdly, Ethereum currently works on the principle that the sender always pays, not the owner of the contract that is triggered. So, if you are sending ether and the receiving address is a customized, gas guzzling Contract Wallet with some fancy code behind it, then you as the sender will end up paying more in gas costs. This is an issue whether you are sending from an Account or Contract Wallet. The solution for now is to always play it safe and allocate ample gas, say 100,000, so that your transaction does not run out of gas and get cancelled. This is the approach taken by the Mist Wallet by default. This issue is expected to be addressed when Serenity arrives, and apparently workarounds are possible even now.

Receiving Ether

Intuitively, it seems like receiving ether using an Account address or a Contract Wallet address should be no different. The truth is there are differences:

Firstly, you already know that incoming transactions will be listed only when you use a Contract Wallet address.

Secondly, and less obvious is the issue related to gas cost. If you use a Contract Wallet as your receiving address, the sender must have specified enough gas for the transaction to complete. If the sender has specified only the default minimum of 21,000 gas for instance, the ether transfer will be cancelled due to an out-of-gas error and you will not receive anything. 21,000 gas would have worked if you were using an Account to receive. So, to be safe, use Accounts to receive from exchanges and the like.

It seems clear, that if Contract Wallets are to be more widely and frequently used, there is some re-educating that needs to be done involving both senders and receivers.

Receiving Mining Rewards

If solo mining, you can use either Account or Contract Wallet as your Etherbase account to receive mining rewards. Apparently the protocol “pays no gas”!

When mining through a pool, it is once again safer to use an Account to receive your reward as the pool operator may not specify enough gas to cover sending to a Contract Wallet.

Transactions That Run out of Gas

As explained above, when you both send or receive ether, you can become involved in a transaction that runs out of gas. Because the transaction did not specify enough gas, the receiving Contract Wallet’s code execution is reverted and so no ether transfer takes place. The insufficient gas specified will still be consumed, however. Importantly, a transaction that runs out of gas is still a valid transaction and so will be included in the blockchain and be picked up by all block explorers, adding to the confusion.

Blockchain explorer Ether.Camp is currently the best explorer for identifying an out-of-gas error. Enter the transaction hash into the explorer and it will indicate that the transaction was cancelled. If you examine the “VM Trace” view you will see that it ran out of gas.


Creating Watch-Only Wallets

If you import a Contract Wallet (either Simple Wallet or Multisig Wallet), following the procedure described above, and your Wallet App does NOT have access to the keyfile/s of the owner Account/s, then you will create a Watch-Only Wallet.

An eye-like icon next to the wallet name denotes a Watch-Only Wallet. Watch-Only Wallets update immediately as the linked wallet’s balance changes.

Where Is Your Wallet Data Stored?

In Chapter 1, we learned where the Wallet App’s Geth node stores its data. Data not directly related to the Geth node but created within the Wallet App, such as data relating to Contract Wallets, transaction history, names, etc. is stored in the following locations:

Windows: C:\Users\username\%appdata%\Roaming\Mist
Mac: ~/Library/Application Support/Mist
Linux: ~/.config/Mist
(Note: Different location from Beta 5 for Linux.)

To backup the Mist directory (Wallet App data):

  • Select the Backup menu in the Menu bar, then select the Backup App Data option.
    Copy the entire Mist folder.MenuBackupApp

Retrieving an Individual Contract Wallet

If you delete a Contract Wallet from your Wallet App by clicking on the Trash icon, you can retrieve it by importing it. (To see the Trash icon select the wallet then hover the cursor over the name.) You will need the address of the Contract Wallet. If you haven’t copied the address somewhere (as you should), you can still get the Contract Wallet address by using a Block Explorer and looking for the transactions sent from the owner Account of that Contract Wallet.

Backups of Simple Wallets and Multisig Wallets

By now, it should be abundantly clear to the reader that contract-based wallets, namely Simple Wallets and Multisig Wallets, are owned and controlled by Accounts. So any backup of a Contract Wallet must also include a backup of its owner Account/s. Accounts are backed up by copying their keyfiles or by copying the entire keystore folder as already described in Chapter 1.

To fully backup a Contract Wallet, you also need to keep a copy of the Mist folder which can be easily backed up as described above.

Restoring a backup is accomplished by simply copying the keyfiles and the Mist folder back to their original locations.