@authereum/contracts v1.0.1

Authereum Contracts

Ethereum smart contracts for Authereum

Check out the Authereum contracts bug bounty program here!

Contract Design

The Authereum contracts are necessary pieces of the Authereum ecosystem. Users of the Authereum accounts own a proxy contract that points to an upgradeable logic contract. The contracts are organized in the following directories:

• account - The Authereum Account logic contract. All users on the Authereum platform will own a proxy contract that points to these contracts. This is upgradeable. Each users' state will live in their proxy contract but will interact with this contract.
• upgradeability - Upgradeability logic for Authereum accounts. Each user that joins Authereum creates a proxy (AuthereumProxy) through the Authereum proxy factory (AuthereumProxyFactory).
• admin - Administrative contracts to be used by Authereum creators.
• base - Base contracts used throughout the system.
• ens - Custom ENS contracts. Used to give Authereum users their own *.auth.eth subdomains. The Authereum ENS Resolver is upgradeable.
• firewall - Contracts that can be used as a firewall to protect user's accounts.
• modules - Independent contracts that are added as Auth Keys to Authereum accounts for extended functionality.
• interfaces - Interfaces used throughout the system.
• libs - Libraries used throughout the system.
• test - Contracts used during tests. None of these contracts are ever deployed as part of the system.
• utils - Utils used throughout the system.

Top Level Design Decisions

When a user signs up for an account on authereum.com, a proxy contract (upgradeability/AuthereumProxy.sol) is created for them through the Authereum proxy factory (upgradeability/AuthereumProxyFactory.sol). The creation of the proxy simply points the proxy to the latest Authereum account logic (implementation) address, initializes the proxy for that logic address, and gives the proxy and ENS subdomain (*.auth.eth).

Each proxy is fully owned by the user who created it, and Authereum has no custody or control over it at all.

The proxies are upgradeable with the proxy-delegate pattern, which simply means they can point to a new logic address and initialize themselves at that address. The user controls the upgrade and they are the only ones that can perform the upgrade.

The system is designed to be transacted with by meta transactions. Authereum users will sign messages that are sent to relayers who will broadcast the transactions.

There are two types of keys that interact with the contracts: auth keys and login keys. Auth keys have the most power and can perform administrative actions such as adding/removing auth keys and upgrading the account. Login keys are more restricted and can only send transactions.

A core component of the system is the signing of keys. Auth keys and login keys sign messages off-chain, and these messages and their signatures are passed into the contracts so that the signer can recovered and verified on-chain. There are two types of signatures checked:

• For an auth key transaction, the transaction message data is signed by the auth key, and the signed data and the signature are passed into the contract transaction. These two items are used to verify that the auth key signed the message.
• For a login key transaction, two signatures are required. One signature is identical to the one mentioned above, except it is signed by the login key instead of the auth key. The second piece of the login key transaction is a signature of the login key (and some data) signed by the auth key. This can be thought of as authKey.sign(loginKey, data). Both pieces of data and both signatures are sent to the transaction. The login key and auth key are recovered on-chain, and the contract verifies that these addresses are correct.

More information can be found here.

account

The account directory contains the logic contract for an Authereum Account. It is a single contract with AuthereumAccount.sol being the bottom-most contract on an inheritance tree. A user's proxy will point to this deployed contract and will use it for its logic.

This contract is upgradeable. Because of this, it is designed in such a way as to avoid overwriting any state variables. accounts/state/, accounts/initializer/, and accounts/event/ have been separated out into subdirectories that each have the contract's state, initializers, and events, respectively. Any upgrades to the contract will create a new version (e.g. AccountStateV2.sol) that gets inherited, in order, as to completely avoid overwriting any state. The initializer functions are meant to be called when upgrading a contract and are protected from being called multiple times with the lastInitializedVersion state variable. Technically the contract events are able to be upgraded/overwritten without causing problems, but we put them in their own directory and will treat them similar to state upgrades. This is for cleanliness of code and so that the initializers can emit events.

In normal circumstances, transactions are meant to be sent by a relayer to one of two functions: executeMultipleAuthKeyMetaTransactions() and executeMultipleLoginKeyMetaTransactions(). See Top Level Design Decisions for more information about the different keys. These transactions perform the following functions:

• perform an atomic transaction with itself
• verify that the signers of the data are the expected addresses (login key and auth key)
• execute each of the batched transactions sent in the transactions
• refund the relayer with ETH or tokens (if necessary - certain auth key transactions are not required to do this)

The following section will break down each point above.

Atomic Transactions - The Authereum contracts perform atomic transactions within their own transaction. In the context of an Authereum transaction, this means that transactions sent to an Authereum contract perform a call back to itself. The reason for this is to be able to revert within a transaction without reverting the entire transaction. This allows for the unwinding of state if a transaction fails while still allowing a relayer to be refunded.

Verify Signatures - See Top Level Design Decisions for more information about the signing. In short, signatures are created off-chain that are verified on-chain. This was done for efficiency and to minimize the number of on-chain transactions.

Execute Transactions - Authereum users can send batched transactions. These are multiple transactions that are all batched into one, single on-chain transaction. See here for more information. The Authereum contracts loop through each passed-in transaction and executes them with a call.

Refunds - Most Authereum transactions should be sent by a relayer. Because of this, Authereum transactions refund the relayer who broadcasts the transaction at the conclusion of their transaction based on the amount of gas that was used. Refunds can be paid in ETH or tokens. It is expected that the relayer will not broadcast transactions that will be detrimental to themselves. The feeTokenRate is passed in by the user and is used to calculate the number of tokens that are paid to the relayer in a refund. It is expected that a relayer will not send a transaction with a token rate that they do not agree with.

There is a gasOverhead parameter that is passed into these functions as well. The value of this parameter is meant to be calculated off-chain and passed into the transaction. It represents the gas overhead that is not taken into account when calculating a refund. This may include the gas cost of the calldata, as well as any additional logic that is not captured by the gas calculations.

Upgradeability logic lives within this contract as well. In order to perform an upgrade, a user must send a transaction to executeMultipleAuthKeyMetaTransactions() that, in turn, calls its own upgradeToAndCall() function.

Finally, 721 and 1125 hooks are used in order to receive those types of tokens in the Authereum contracts.

upgradeability

Authereum's contracts are upgradeable. Each Authereum user owns a proxy (AuthereumProxy.sol) that points to their desired logic contract. This contract's sole function is to provide a fallback function that delegates calls to the proxy's logic contract. All Authereum user transactions go through this fallback.

Each proxy is created by the Authereum proxy factory (AuthereumProxyFactory.sol). The Authereum proxy factory creates an account when createProxy() is called. This function creates a proxy with create2, initializes it, and registers a subdomain for the proxy. When a user creates an account on a later version of the Authereum contracts, they will have to iterate through each previous version's initializer. Because of this, the createProxy() function loops through each piece of the initialize data.

The AuthereumEnsResolverProxy.sol is nearly identical to the AuthereumProxy.sol contract and is used for upgrading the Authereum ENS Resolver Proxy.

modules

The Authereum contracts support "module" contracts that can be used to introduce additional functionality to an Authereum account. A module contract is added to an Authereum account by adding its address as an Auth Key. Because modules may contain critical functionality (e.g. the RecoveryModule), Login Keys should not be able to interact with modules. To prevent this, a check in LoginKeyMetaTxAccount.sol will revert the transaction if a Login Key's transaction's destination is an Auth Key, which may be a module. In addition, when designing modules, care should be taken to ensure Login Key's cannot interact with a module before it's added to an account as an Auth Key. Both the RecoverModule and DelegateKeyModule prevent this with the onlyWhenRegisteredModule modifier.

Additional Notes

Known Issues

• A user can break their upgradeability on the Authereum system by upgrading their account to a logic address outside of the Authereum ecosystem.
• It is expected that a relayer will not broadcast a transaction that contains any data that would be detrimental to themselves. This includes:
  • Transactions that will revert (because of gas, bad data, or improperly signed data)
  • Transactions that contain a feeTokenRate that the relayer does not accept as a true rate
• The DelegateKeyModule does not enforce that the length of _lockedParameters and _lockedParameterValues are equal to the actual number of parameters taken by the function being registered. In addition, dynamically-sized parameters cannot be locked but this is not enforced on-chain. When registering a Delegate Key, care should be taken to ensure that _lockedParameters and _lockedParameterValues equal the number of parameters in the function being registered and that none of the parameters being locked are dynamically-sized.

Invariants

• An attacker cannot spend the account contract's funds, freeze the funds, or participate in account management.
• Transactions from the account contract can only be authorized by an Auth Key or Login Key either directly or through a meta transaction.
• Login Keys cannot participate in account management including adding and removing auth keys and upgrading the account. Anything marked as onlySelf or onlyAuthKeySenderOrSelf should not be accessible by a Login Key.
• Login Keys should not be able to interact with the RecoveryModule or the DelegateKeyModule in a meaningful way. Modules should prevent certain interactions when the module is not registered to the account contract and the account contract should not let Login Keys invoke functionality on Auth Keys which includes any modules registered to the account contract.
• Login Keys should only be able to interact with Auth Keys and with self in a limited capacity. Transactions from Login Keys to either an Auth Key or to self should be bounded by both data and gas values.
• Login Keys can bypass restrictions by setting the validationContract to address(0). It is expected that relayers who process transactions validate these restrictions off-chain, if desired.

Config

Environment variables:

NETWORK_NAME=kovan
ETH_HTTP_PROVIDER_URI='https://kovan.rpc.authereum.com'
SENDER_ADDRESS=0x...
SENDER_PRIVATE_KEY=0x...
LOGIC_ADDRESS=0x...

You may also set the config by invoking the setConfig(config) static method.

Versioning

All the versioning in the Authereum system will use Unix timestamps. A dictionary will be kept that maps version numbers to human-readable names.

Advantage of Unix Timestamp:

• Consistent versioning
• Easy file/variable naming
• Infinitely scalable

Design Decisions:

• Semantic versioning is hard to do on file names and variables
• Sequential may cause issues down the road (ie renaming files/contracts to have more left padding)

Addresses

Mainnet

Kovan

Goerli

Rinkeby

Ropsten

Test

Note: this requires a ganache-cli version with the muirGlacier compiler. Please use ganache-cli@6.9.0 or greater.

# In terminal 1
npm run ganache

# In terminal 2
npm run test

Changelog

Authereum Account

2020070100

This update introduces a number of new features and cleans up existing code. It was audited by G0 Group.

General

• Update contract to Solidity 0.5.17
• Normalize loginKeyRestrictionData to loginKeyRestrictionsData
• Fix spelling issues
• Remove 0 fee payments (don't transfer 0 tokens/ETH)
• Remove refund check (now done by relayer)
• Change all instances of authereum.eth to auth.eth
• Update to Truffle istanbul compiler
• Remove unnecessary return of the message hash from _atomicExecuteMultipleMetaTransactions
• Add ERC777 support
• Allow for limited sending of transactions from a login key to an auth key or self
• Disallow auth keys from being self
• Remove unused onlyAuthKeySender modifier
• Add pre- and post-hooks to login key transactions
• Add name variable to contracts
• Convert authereumVersion to version
• Add implementation()
• Add implementation() and upgradeToAndCall() to IAuthereumAccount.sol
• Add executeMultipleTransactions() function and scope it to auth keys
• Update executeMultipleMetaTransactions() function scope to self
• Update ERC1271 logic to reflect newly finalized specification

• Add initialization v2 contract that registers the contract with the 1820 registry

  Tests

• Add tests

2020060100

This update adds the ability to pay for contract deployments:

General

• Add logic to allow users to pay for deployments of their contracts

2020021700

This update is in response to samczsun's disclosure:

Bugfixes

• Validate both auth key and login key tx prior to execution

2020020200

This update is in response to our Quantstamp audit.

General

• Require that initialization data has a length of > 0. Prior to this version, it simply did nothing if the length was 0.

• Fix typos

  Bugfixes

• Return the appropriate data from executeMultipleMetaTransactions()

2020010900

Bugfixes

• Fee token rate calculation

2019122000

General

• Major refactor
• Introduce fee toke

2019111500

General

• Architecture upgrade

• Introduce _feeTokenAddress and _feeTokenRate

  Bugfixes

• General bug fixes

2019102500

General

• Original contract

Authereum Proxy Factory

2020070100

General

• Update contract to Solidity 0.5.17
• Add name
• Add version
• Pass initCode directly into the constructor
• Hash initData in the create2 salt to validate auth key
• Update salt naming convention to be more explicit
• Pass _implementation into the createProxy() function
• Add _implementation to the salt hash

2019111500

General

• Add initCode setter and change event
• Add authereumEnsManager setter and change event

2019102500

General

• Original contract

Authereum ENS Manager

2020070100

General

• Update contract to Solidity 0.5.17
• Add name
• Add version
• Update internal variable from name to _name

2019111500

General

• Add ability to change rootnode text
• Add ability to change rootnode contenthash

2019102500

General

• Original contract

Authereum ENS Resolver

2020070100

General

• Update contract to Solidity 0.5.17
• Add version

2019111500

General

• Update contract to Solidity 0.5.12
• Add text and contenthash to interface
• Add text and contenthash as setter and getter

2019102500

General

• Original contract

Authereum Delegate Key Module

2020070100

General

• Original contract

Authereum Recovery Module

2020070100

General

• Original contract

Authereum Login Key Validator

2020070100

General

• Original contract

FAQ

• Why am I getting the following when I run a test?

  connection not open on send()
  connection not open

  • Try restarting ganache and running npm run truffle-reset
  • Try running ganache-cli on a different port (either 8545 or 9545)

  Update: 11/19/19 - This error is related to using WebSockets. If this error persists, try using https instead, if possible.

• Why is my test failing on a simple test? It seemingly reverts even when it shouldn't.

  • It is because you are running out of gas. There is an issue with zos (<2.4.0) and ganache (>= 6.4.0) where gas estimation does not work. You must manually set the gasLimit in the transaction, for now. See here for the proposed fix in 2.4.0rc2.

• Why are my tests not running with Returned values aren't valid, did it run Out of Gas?

  • You are trying to deploy on a different network. Try changing the .env file to reflect the network you are trying to deploy on.

  • Delete the build folder and run truffle compile && truffle migrate --reset

• Why am I getting the following error when running tests?

Error: EnsRegistry error: contract binary not set. Can't deploy new instance.
This contract may be abstract, not implement an abstract parent's methods completely
or not invoke an inherited contract's constructor correctly

• Delete the build folder and run truffle compile && truffle migrate --reset

• Why are my tests not running at all (and the output says 0 passing)

  • This happens because there are no actual tests (i.e. there is no it(){}). It is likely that you only have describe(){} and/or context(){}.

• What are the event topics for each of the events in AuthereumAccount.sol?

  • event Upgraded(address indexed implementation);: 0xbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b
  • event CallFailed(string reason);: 0xb5e1dc2ddc0e1a0221e00b3c0446f36b707001d3ac7cfb494259863fdef7ccd7
  • event AuthKeyAdded(address indexed authKey): 0xb020719d16d3c4de45a91f9c329aa61d5bad3f44f760840c8d5d82d4cd3bcc33
  • event AuthKeyRemoved(address indexed authKey): 0xbe55f9add9abe657e689a4a84a31854310f260c7e2610bcd22440e3ec3a836a4

• What is the best way to verify my contract on Etherscan?

  • Run the following command: truffle run verify xxx@yyy --network zzz
    • xxx = contract name (per the ABI)
    • yyy = contract address
    • zzz = network name
      • truffle run verify AuthereumAccount@0x2e1723d1DFa2947f0d08D5c5D214b71deF4f951F --network mainnet

• How can I retroactively verify my contract on Etherscan if it has been a while since I deployed it.

  • The best way to do this is to find the commit where the contract was deployed using git blame. Once the commit is found, do the following:
    • git checkout <commit>
    • Update truffle.js to include the truffle-plugin-verify plugin
    • npm run ganache
    • rm -rf build && truffle compile && truffle migrate
    • truffle run verify xxx@yyy --network zzz

• Why does my deployed address not match my calculated address?

  • It is probably the bytecode
    • One thing to look at is src/constants. If you updated the compiler, this will need changed, along with the code that uses that data elsewhere.

• Why do I keep getting "Error: Returned error: the tx doesn't have the correct nonce. account has nonce of: 1 tx has nonce of: 0" when I run tests

  • This is due to a snapshot issue we have. Because we must deploy the 1820 contract with a specific nonce, this error may occur if things get out of order (transactions fail un-gracefully, stopping tests between snapshots, etc.)
    • To resolve this, simply restart ganache.

License

MIT