Plain Transactions and Fallback Functions

Just sending ETH is the simplest operation for a user (Figure 7-1). The recipient address listed can be either an externally owned account or a smart contract that performs some simple processing upon every transfer.

Remember that every time a contract receives a vanilla transfer of funds, the fallback function is executed, meaning that you can actually react to a transfer via a certain action. In particular, you can rely on the precise amount of ETH sent. However, some exchanges will only send the transfer with a minimal amount of gas, so it may not be possible to perform complex actions as a response to an ETH transfer.

Forwarding Contracts

A neat trick to allow the user to send additional information along with their contribution is to set up several contracts that act as forwarding proxies and execute certain functions in a main contract as their fallback function. Though this does not allow for arbitrary data to be sent, it allows for a predefined set of functions to be run.

However, asking the user to include an arbitrary hexadecimal string along with their transfer can be an issue, since most exchanges do not support including data along with their withdrawals. And, for regular wallets, including data is often presented as an advanced feature (Figure 7-2).

How to Use a Single-use Address

Note that if the transaction from the single-use address fails for any reason (whether it is a failed require in a contract or lack of gas), there is no way to issue a second transaction with the necessary fixes. This means that any funds that the user sent in step 3 will be effectively locked forever. As such, make sure to avoid using single-use addresses when a transaction could fail due to state changes.

As an example, the Donations contract from as in the previous section would be a poor choice, since the time while the donations are accepted is limited. A user may set up their single-use address while donations are open, but if they seed it after they close, then their funds will end up locked.

Another pitfall of single-use addresses is that they must be funded with the exact amount of ETH required for their execution. Any extra funds sent to the address are irretrievably lost. Make sure to clearly communicate this to your users!

Creating a Single-use Address

How are single-use addresses created? It is worth noting that they are not a special Ethereum construct, but the result of a clever hack. Also, creating them requires no initial gas at all.

Recall from previous chapters that all Ethereum transactions need to be signed with the sender’s private key in order to be valid. The sender’s address can then be derived from the transaction’s signature, so the from is actually never included in the transaction’s data – it’s calculated from the signature when needed.

The trick for generating single-use addresses relies in sending a random signature with the transaction. Instead of actually signing the transaction in step 2, we just include a random set of bytes as a signature in step 3. This way, there is no private key associated with the process.

When processing the transaction, this results in a random sender address derived from the signature. And given that the private key associated with this address is unknown, it is not possible to generate any other transaction for the same address. This effectively yields a single-use address that can only broadcast one specific transaction. Then, as soon as the address is funded with ETH, the gas fees can be covered, and the transaction can be broadcasted to the network.

Sample Code

Most parameters in the preceding snippet should be familiar by now: the recipient address, the amount of ETH being sent, the gas allowance and price, and the transaction data. Since this transaction will be sent from a new address that has sent no other transactions, the nonce must be zero.

The new parameters we see here are v, r, and s, which correspond to the transaction’s signature. The first of them must be derived from the chain id,³ while the two others are normally calculated from the user’s private key – we will replace them by an arbitrary bytes sequence here.

However, since we have not yet funded the sender address, we will get a “sender doesn't have enough funds to send tx” error. Remember that the derived sender is a new account, so it will never have any previous funds.

The DELEGATECALL Instruction

A regular CALL from one contract to another in the EVM works as a call from an actor or process to another: a new context is created, where the state (storage and balance) of the callee is loaded, the caller is set to msg.sender, and the code of the callee is executed. On the other hand, a DELEGATECALL works by executing the code of the callee but maintaining the original context of the caller. In other words, storage, balance, and even msg.sender are not changed by a DELEGATECALL – only the code being executed is.

This low-level instruction allows us to jump into an arbitrary contract and execute its code, where that code actually modifies the state of the current contract. The called contract then acts as a library,¹⁰ being used only as a repository of shared code, but not using its state.

Delegating Proxies

The DELEGATECALL instruction allows us to build a contract that simply delegates all calls to another contract which holds the actual logic to be executed. These contracts are usually called delegating proxies , since they delegate all calls to another contract, or transparent proxies, as any client interacting with them is oblivious to their existence. The contract being called by the proxy that holds the code being actually executed is usually called logic contract, implementation contract, or master copy.

The key concept here is that the address of the logic contract does not need to be hard-coded into the proxy – it can actually be kept in storage. When this address is changed, this effectively updates the code being executed by the proxy while keeping its state and address. We can now add this feature to our identity contracts.

Upgradeable Identities

Armed with this new building block, we can deploy a single identity contract to act as a logic contract and deploy one proxy for each of our users. Remember that since all state is kept in the proxy, there is no need for more than one copy of the logic contract, and a single one can be shared (like a library) among multiple proxies.

Keep in mind that any state variables defined on this contract will not be actually stored on this contract’s storage, but in the proxy’s – thanks to the magic of delegate calls. For instance, the initialized flag is not actually set on the single UpgradeableIdentity contract deployed as a shared implementation, but is set on each of the proxies that are backed by it.

Because of this, the first variable declared on this contract must be the implementation address, as in the proxy. Also, the contract cannot extend from any base contract that defines additional contract variables. This ensures that the implementation address is stored in the same position in storage as where the proxy will look for it.¹¹

Implementing this pattern in smart accounts allows us to iteratively develop our application by gradually adding support for new features or fixing bugs and allows our users to adopt them when they want.

A good example of a feature we may want to add to our identity contracts is meta transaction support, which we will see in the next section.

Building on Our Smart Accounts

Meta transactions require a contract that can process them, validate them, check that the signer is authorized to perform the action requested, and carry it out on their behalf. Fortunately, we already have a contract that can hold funds and carry actions on behalf of different accounts held by a user: the identity contract.

We will modify the identity contract we have been building to handle meta transactions. Our forwarding function will now receive a meta transaction pre-signed by one of the user accounts instead of a direct call from one of them.

The address of the validator is included to prevent a meta transaction sent to another validator to be reused in this one, while the nonce prevents replay attacks (i.e., relaying the same transaction multiple times). The resulting hash gets the magic prefix "x19Ethereum Signed Message: " prepended, so it is distinguishable from a regular Ethereum transaction, and is then hashed again.

Next is the validation of the sender. Note that the contract no longer checks that msg.sender is a registered account – it now checks that the signer of the transaction is. The msg.sender becomes irrelevant, since who relayed the transaction does not matter at this stage.

Finally, and before executing the transaction, the nonce is increased. This prevents the same transaction to be sent to the contract multiple times by a malicious relayer.

Sending Meta Transactions

We are deliberately omitting from this example how the user communicates with the relayer or how the relayer decides whether to pay for the user’s transaction. This will vary from application to application. For instance, an application could provide a centralized relayer at a well-known URL, which pays for every transaction to a contract in their system. It may also force users to go through a CAPTCHA to prevent spamming.

There are also efforts toward building fully decentralized relayer networks, in which the logic on whether paying for a user transaction is actually part of the application’s smart contracts. These efforts also include approaches where the relayers are paid back for their execution, as we will see in the next section.¹⁴

Relayer Reward

The easiest way to implement a payback to the relayer is to include a reward along with each request for execution. The relayer can then decide whether to relay the transaction or not, depending on the estimated execution cost for it.

The user can even request a specific gas price and gas allowance for its transaction and verify that these are satisfied within the identity contract. This prevents relayers from sending transactions with very low gas prices, paying lower fees at the expense of a user’s time.

An important change in the preceding snippet is that the function no longer requires the forwarded call to be successful (require(success)). The rationale for this is that if the forwarded call failed and reverted the entire transaction, then the relayer would not receive any reward, but would still lose the gas fees from the execution of the reverted transaction. To avoid punishing a relayer for a failed transaction that was correctly relayed, we drop that requirement. And to allow for determining whether forwarded call reverted, we add an event that reports the success in each transaction.

Also, note that the gas price validation is performed at the beginning of the method, since gas price is relative to the entire transaction, and cannot be changed in-between contract calls. Gas limit, on the other hand, can be enforced on each call within the transaction, so we can revert if there is not enough gas left. In this case, it is the relayer’s responsibility to include additional gas on the request to account for the meta transaction processing (which is about 60K in this implementation).

Estimating Profits

The code for generating the signed transaction in this scenario is analogous to the previous one, with the only difference that the user now needs to include values for the gas price, the gas limit, and the reward. The first two can be estimated as seen in Chapter 5 by using a price oracle like the ethgasstation API or the gasPrice JSON-RPC method for the gas price and running an estimateGas on the transaction to be sent for the gas limit. The value for the reward may depend on other factors, but must be greater than the total execution cost for the relayer, to have an incentive to relay the transaction.

In this scenario, the relayer needs not only to relay the requested transaction but also to evaluate whether it should – by calculating the profit. Transactions with an estimated profit below a certain threshold should be dropped, and if multiple transactions (from different identities) are enqueued, the profit can be used to prioritize which to execute first.

Note that this difference may actually cause the transaction to cost more than the relayer expected in case the estimation and the actual usage differ, as the relayer could be setting a higher gas allowance.

Payment in Kind

Gas fees from transaction execution are paid in ETH, since it is the native currency of the Ethereum network. However, nothing forces us to pay the rewards to relayers in the same currency, as there are plenty of other media of exchange on Ethereum: every fungible token (ERC20) is a potential currency.

This opens the door to allowing our users to transact exclusively using a token, since ETH is no longer needed to pay for gas fees. This is especially interesting if our application is built on top of a token-based protocol: it allows us to send tokens to our users as they engage in our network, which are in turn used to pay for relayer rewards. Our users never need to hold or purchase any ETH; they only work with our application’s token.

Keep in mind that while this mechanism is particularly useful when your application spins up relayers that trade tokens for executions, it imposes additional difficulties for decentralized relayers. A random relayer performing desktop mining now needs to check for the market value of the reward token against the execution cost to determine the profit. Not only that, but it also needs to ensure there is enough liquidity in the market to trade such token for ETH when they want to cash out their profits – and that is without considering the fees for that exchange.

In other words, paying relayer rewards in a protocol-specific ERC20 is useful if the relayer infrastructure you are using is specific to your application, but ETH or a widespread ERC20¹⁵ may be a better option for working with decentralized relayers.

Rewards in Native Meta Transactions

While moving the meta transaction logic to the application contract directly reduces complexity for the user, it introduces an additional difficulty: how to handle rewards to relayers. Identity contracts did not face this problem since they already held all of the user’s assets, so they could directly transfer them to relayers as payment.

However, this solution does not allow any rewards in any currency that is not that same token – for instance, ETH rewards are not possible under this scheme. It also does not translate well to other assets. What would be the reward for transferring an ERC721 non-fungible token? A digital collectible cannot have a piece removed and given to a relayer as a reward.

A way around this problem is to rely on ERC20 approvals. Recall from Chapter 3 that ERC20 tokens allow holders to appoint other addresses to manage their funds. This way, a user could grant an approval on their tokens to the application contract processing the relayer rewards, which then sends the tokens to the relayer as payment. This approach, however, still requires the user to have ETH to pay gas fees in the initial approve transaction – unless the reward token contract itself has native meta transaction support for approvals.

Another option is to simply subsidize the user’s transactions and have the application itself pay out to the relayers. This requires careful logic in the application contract to determine when to accept a meta transaction – otherwise, a malicious relayer could spam the application with fake transactions and drain the entire reward pool. Such logic will depend entirely on your use case, but keep in mind that you have much flexibility: your contracts may require the meta transaction to have an additional signature by an application key, so you can perform validations off-chain to approve a transaction for execution.

The CREATE2 Instruction

Ethereum has, since its first versions, provided a CREATE instruction for creating a new contract from another. The address of the newly created contract, as we saw earlier, is a function of the sender address and its nonce. While this allows for deterministic deployments, it also means that reserving an address is tricky, since the sender must not send any other transactions besides the deployment one to prevent changing its nonce.

A user can now choose a contract, along with its constructor arguments, generate a random salt, and know the address where the resulting contract will be deployed. Not only that, but anyone who knows these parameters can now perform the deployment.

This means that the user can simply share the creation parameters and salt, plus the address of the factory contract to be used, and have any relayer execute the transaction, without even needing to sign the transaction – and certainly not paying any gas. Should a relayer attempt to modify the code or creation parameters, the contract would end up deployed at a different address. Let’s use this approach to deploy our identity contracts, providing rewards to the relayers.

Deployment Rewards

Before going into the code, we need to define how the payments to the relayer will be managed and which addresses will be initially funded by the user.

Recall from the previous approach that one of the downsides of single-use addresses is that the user needs to fund from an exchange one address, but then his or her identity is spawned at a different one. Even worse, any additional funds sent to the single-use address are lost. Then, it is desirable if we can have the user fund the address of the identity contract directly.

This approach allows the user to simply specify the owner account and the reward to be paid and broadcast those parameters along with the salt chosen, since these values alone are enough to determine the deployment address. Any relayer can then pick up this transaction, validate that there are enough funds on the deployment address to pay for the reward, and send the transaction to the factory contract. As a bonus, any surplus funds sent to the deployment address will still be there after the contract is created, ready to be used by their owner.

Identity Contract Factory

Note that there is no need to validate the owner’s signature, since any change on the creation parameters would yield a different deployment address – one with no funds to pay back the reward to the relayer. Relayers should validate that the deployment address indeed has enough funds to pay back.

Using this strategy, you can precalculate the address where a user’s identity will be created given a salt and share the address with him or her. The user acknowledges that address as their own and seeds it with funds from an exchange. This in turn triggers a relayer to create an identity contract at that address once it is funded.