0x is an open protocol that facilitates trustless, low friction exchange of Ethereum-based assets. A full description of the protocol may be found in our whitepaper. This repository contains the system of Ethereum smart contracts comprising 0x protocol's shared on-chain settlement layer, native token (ZRX) and decentralized governance structure. Truffle is used for deployment. Mocha is used for unit tests.
The Bug Bounty is now live! Details regarding compensation for reported bugs can be found here. Submissions should be based off of commit ebf8ccfb012e2533094f00d6e813e6a086548619. Please e-mail all submissions to [email protected] with the subject "BUG BOUNTY". Note that submissions already reported in our security audits or GitHub issues will not be eligible.
The following contracts are within the scope of the bug bounty:
- Exchange.sol
- TokenTransferProxy.sol
- TokenRegistry.sol
- ZRXToken.sol
- MultiSigWalletWithTimeLockExceptRemoveAuthorizedAddress.sol
- TokenSale.sol
- MultiSigWallet.sol (There is an additional growing bug bounty for this contract here)
- MultiSigWalletWithTimeLock.sol
- VestingWallet.sol (This is in a different repo, found here)
0x uses a modular system of Ethereum smart contracts, allowing each component of the system to be upgraded without effecting the other components or causing active markets to be disrupted. The business logic that is responsible for executing trades is separated from governance logic and trading balance access controls. Not only can the trade execution module be swapped out, so can the governance module.
Exchange contains all business logic associated with executing trades and cancelling orders. Exchange accepts orders that conform to 0x message format, allowing for off-chain order relay with on-chain settlement. Exchange is designed to be replaced as protocol improvements are adopted over time. It follows that Exchange does not have direct access to ERC20 token allowances; instead, all transfers are carried out by TokenTransferProxy on behalf of Exchange.
TokenTransferProxy is analogous to a valve that may be opened or shut by MultiSigWalletWithTimeLock, either allowing or preventing Exchange from executing trades. TokenTransferProxy plays a key role in 0x protocol's update mechanism: old versions of the Exchange contract may be deprecated, preventing them from executing further trades. New and improved versions of the Exchange contract are given permission to execute trades through decentralized governance implemented within a DAO (for now we use MultiSigWallet as a placeholder for DAO).
MultiSigWalletWithTimeLockExceptRemoveAuthorizedAddress is a temporary placeholder contract that will be replaced by a thoroughly researched, tested and audited DAO. MultiSigWalletWithTimeLock is based upon the MultiSigWallet contract developed by the Gnosis team, but with an added mandatory time delay between when a proposal is approved and when that proposal may be executed. This speed bump ensures that the multi sig owners cannot conspire to push through a change to 0x protocol without end users having sufficient time to react. An exception to the speed bump is made for revoking access to trading balances in the unexpected case of a bug being found within Exchange. MultiSigWalletWithTimeLock is the only entity with permission to grant or revoke access to the TokenTransferProxy and, by extension, ERC20 token allowances. MultiSigWalletWithTimeLock is assigned as the owner
of TokenTransferProxy and, once a suitable DAO is developed, MultiSigWalletWithTimeLock will call TokenTransferProxy.transferOwnership(DAO)
to transfer permissions to the DAO.
TokenRegistry stores metadata associated with ERC20 tokens. TokenRegistry entries may only be created/modified/removed by MultiSigWallet (until it is replaced by a suitable DAO), meaning that information contained in the registry will generally be trustworthy. 0x message format is not human-readable making it difficult to visually verify order parameters (token addresses and exchange rates); the TokenRegistry can be used to quickly verify order parameters against audited metadata.
- Exchange.sol: 0x90fe2af704b34e0224bf2299c838e04d4dcf1364
- TokenTransferProxy.sol: 0x087Eed4Bc1ee3DE49BeFbd66C662B434B15d49d4
- ZRXToken.sol: 0x6ff6c0ff1d68b964901f986d4c9fa3ac68346570
- EtherToken.sol: 0x05d090b51c40b020eab3bfcb6a2dff130df22e9c
- MultiSigWalletWithTimeLockExceptRemoveAuthorizedAddress.sol: 0x9301A2B0dCA791Ba27B1A074Aba3Bf47bcd80Cb9
- TokenRegistry.sol: 0xf18e504561f4347bea557f3d4558f559dddbae7f
- Exchange.sol: 0x12459C951127e0c374FF9105DdA097662A027093
- TokenTransferProxy.sol: 0x8da0D80f5007ef1e431DD2127178d224E32C2eF4
- ZRXToken.sol: 0xE41d2489571d322189246DaFA5ebDe1F4699F498
- EtherToken.sol: 0x2956356cd2a2bf3202f771f50d3d14a367b48070
- MultiSigWalletWithTimeLockExceptRemoveAuthorizedAddress.sol: 0x01d9F4D104668CDc0b6d13C45DFf5E15D58d8f28
- TokenRegistry.sol: 0x926a74c5C36adf004C87399e65f75628b0f98D2C
The diagrams provided below demonstrate the interactions that occur between the various 0x smart contracts when executing trades or when upgrading exchange or governance logic. Arrows represent external function calls between Ethereum accounts (circles) or smart contracts (rectangles): arrows are directed from the caller to the callee.
Transaction #1
Exchange.fillOrder(order, value)
TokenTransferProxy.transferViaTokenTransferProxy(token, from, to, value)
Token(token).transferFrom(from, to, value)
- Token: (bool response)
- TokenTransferProxy: (bool response)
TokenTransferProxy.transferViaTokenTransferProxy(token, from, to, value)
Token(token).transferFrom(from, to, value)
- Token: (bool response)
- TokenTransferProxy: (bool response)
- Exchange: (bool response)
Transaction #1
TokenTransferProxy.transferFrom(token, from, to, value)
๐ซ
Transaction #2
DAO.submitTransaction(destination, bytes)
Transaction #3 (one tx per stakeholder)
DAO.confirmTransaction(transactionId)
Transaction #4
DAO.executeTransaction(transactionId)
TokenTransferProxy.addAuthorizedAddress(Exchangev2)
Transaction #5
TokenTransferProxy.transferFrom(token, from, to, value)
โ
Transaction #1
TokenTransferProxy.doSomething(...)
๐ซ
Transaction #2
DAOv1.submitTransaction(destination, bytes)
Transaction #3 (one tx per stakeholder)
DAOv1.confirmTransaction(transactionId)
Transaction #4
DAOv1.executeTransaction(transactionId)
TokenTransferProxy.transferOwnership(DAOv2)
Transaction #5
TokenTransferProxy.doSomething(...)
โ
Each order is a data packet containing order parameters and an associated signature. Order parameters are concatenated and hashed to 32 bytes via the Keccak SHA3 function. The order originator signs the order hash with their private key to produce an ECDSA signature.
Name | Data Type | Description |
---|---|---|
exchangeContractAddress | address |
Address of the Exchange contract. This address will change each time the protocol is updated. |
maker | address |
Address originating the order. |
taker | address |
Address permitted to fill the order (optional). |
makerToken | address |
Address of an ERC20 Token contract. |
takerToken | address |
Address of an ERC20 Token contract. |
makerTokenAmount | uint256 |
Total units of makerToken offered by maker. |
takerTokenAmount | uint256 |
Total units of takerToken requested by maker. |
expirationTimestampInSec | uint256 |
Time at which the order expires (seconds since unix epoch). |
salt | uint256 |
Arbitrary number that allows for uniqueness of the order's Keccak SHA3 hash. |
feeRecipient | address |
Address that recieves transaction fees (optional). |
makerFee | uint256 |
Total units of ZRX paid to feeRecipient by maker. |
takerFee | uint256 |
Total units of ZRX paid to feeRecipient by taker. |
v | uint8 |
ECDSA signature of the above arguments. |
r | bytes32 |
ECDSA signature of the above arguments. |
s | bytes32 |
ECDSA signature of the above arguments. |
Install Node v6.9.1
Install project dependencies:
npm install
Start Testrpc
npm run testrpc
Compile contracts
npm run compile
Run tests
npm run test
0x protocol is intended to serve as an open technical standard for EVM blockchains and we strongly encourage our community members to help us make improvements and to determine the future direction of the protocol. To report bugs within the 0x smart contracts or unit tests, please create an issue in this repository.
Significant changes to 0x protocol's smart contracts, architecture, message format or functionality should be proposed in the 0x Improvement Proposals (ZEIPs) repository. Follow the contribution guidelines provided therein.
We use a custom set of TSLint rules to enforce our coding conventions.
In order to see style violation errors, install a tslinter for your text editor. e.g Atom's atom-typescript.