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
feeTokenRatethat the relayer does not accept as a true rate
- The DelegateKeyModule does not enforce that the length of
_lockedParametersand_lockedParameterValuesare 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_lockedParametersand_lockedParameterValuesequal 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
onlySelforonlyAuthKeySenderOrSelfshould 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
validationContracttoaddress(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 testChangelog
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
loginKeyRestrictionDatatologinKeyRestrictionsData - 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.ethtoauth.eth - Update to Truffle
istanbulcompiler - 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
onlyAuthKeySendermodifier - Add pre- and post-hooks to login key transactions
- Add
namevariable to contracts - Convert
authereumVersiontoversion - Add
implementation() - Add
implementation()andupgradeToAndCall()toIAuthereumAccount.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
_feeTokenAddressand_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
initCodedirectly into the constructor - Hash
initDatain thecreate2salt to validate auth key - Update
saltnaming convention to be more explicit - Pass
_implementationinto thecreateProxy()function - Add
_implementationto the salt hash
2019111500
General
- Add
initCodesetter and change event - Add
authereumEnsManagersetter 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
nameto_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
textandcontenthashto interface - Add
textandcontenthashas 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
8545or9545)
Update: 11/19/19 - This error is related to using WebSockets. If this error persists, try using https instead, if possible.
- Try restarting ganache and running
-
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
.envfile to reflect the network you are trying to deploy on. -
Delete the
buildfolder and runtruffle 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
buildfolder and runtruffle 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 havedescribe(){}and/orcontext(){}.
- This happens because there are no actual tests (i.e. there is no
-
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
- Run the following command:
-
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-verifyplugin npm run ganacherm -rf build && truffle compile && truffle migratetruffle run verify xxx@yyy --network zzz
- The best way to do this is to find the commit where the contract was deployed using
-
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.
- One thing to look at is
- It is probably the bytecode
-
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.
- 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.)