Cleaned up core concept illustrations
This commit is contained in:
Chris Kalani
@@ -1,6 +1,6 @@
|
||||
# Introduction
|
||||
|
||||
0x is a protocol that facilitates the peer-to-peer exchange of [Ethereum](#ethereum-primer)-based assets. The protocol serves as an open standard and common building block for any developer needing exchange functionality. 0x provides secure [smart contracts](#ethereum-accounts-types) that are externally audited; [developer tools](/docs/tools) tailored to the 0x ecosystem; and open access to a [pool of shared liquidity](#networked-liquidity). Developers can integrate with 0x at the smart contract or application layer.
|
||||
0x is a protocol that facilitates the peer-to-peer exchange of [Ethereum](#ethereum-primer)-based assets. The protocol serves as an open standard and common building block for any developer needing exchange functionality. 0x provides secure [smart contracts](#ethereum-accounts-types) that are externally audited; [developer tools](/docs/tools) tailored to the 0x ecosystem; and open access to a [pool of shared liquidity](#networked-liquidity). Developers can integrate with 0x at the smart contract or application layer.
|
||||
|
||||
## What can I build on 0x?
|
||||
|
||||
@@ -31,25 +31,25 @@ A 0x order has the following fields:
|
||||
|
||||
| Field | Description |
|
||||
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| makerAddress | The party that creates the order. The maker is also one of the two parties that will be involved in the trade if the order gets filled. |
|
||||
| takerAddress | The party that is allowed to fill the order. If set to a specific party, the order cannot be filled by anyone else. If left unspecified, anyone can fill the order. |
|
||||
| makerAssetData | Contains all the identifying information about the asset(s) the order maker is trying to sell. |
|
||||
| takerAssetData | Identifying information of the asset(s) the taker must trade in exchange for the maker's asset(s). |
|
||||
| makerAssetAmount | Amount of the maker's asset(s) being offered by the maker. |
|
||||
| takerAssetAmount | Amount of the taker's asset(s) the maker will accept in exchange for their maker asset(s). In order to calculate the price the maker is offering, one can divide the `makerAssetAmount` by the `takerAssetAmount` (the calculation is [a bit more complex](https://0x.org/docs/guides/v2-specification#assetproxy) if multiple assets are involved). |
|
||||
| expirationTimeSeconds | Timestamp in seconds of when the order expires. Expired orders cannot be filled. |
|
||||
| salt | A value that can be used to guarentee order uniqueness. Typically it is set to a random number. |
|
||||
| feeRecipientAddress | The entity that will receive any fees stipulated by the order. This is typically used to incentivize off-chain order relay. |
|
||||
| makerFee | The fee to be paid by the order maker to the `feeRecipientAddress` in the event of an order fill. Partial fills result in partial fees. |
|
||||
| takerFee | The fee to be paid by the taker to the `feeRecipientAddress` in the event of an order fill. |
|
||||
| senderAddress | An advanced field that doesn't need to be set. It allows the maker to enforce that the order flow through some additional logic before it can be filled (e.g., a KYC whitelist) -- more on the ability to extend 0x later. |
|
||||
| `makerAddress` | The party that creates the order. The maker is also one of the two parties that will be involved in the trade if the order gets filled. |
|
||||
| `takerAddress` | The party that is allowed to fill the order. If set to a specific party, the order cannot be filled by anyone else. If left unspecified, anyone can fill the order. |
|
||||
| `makerAssetData` | Contains all the identifying information about the asset(s) the order maker is trying to sell. |
|
||||
| `takerAssetData` | Identifying information of the asset(s) the taker must trade in exchange for the maker's asset(s). |
|
||||
| `makerAssetAmount` | Amount of the maker's asset(s) being offered by the maker. |
|
||||
| `takerAssetAmount` | Amount of the taker's asset(s) the maker will accept in exchange for their maker asset(s). In order to calculate the price the maker is offering, one can divide the `makerAssetAmount` by the `takerAssetAmount` (the calculation is [a bit more complex](https://0x.org/docs/guides/v2-specification#assetproxy) if multiple assets are involved). |
|
||||
| `expirationTimeSeconds` | Timestamp in seconds of when the order expires. Expired orders cannot be filled. |
|
||||
| `salt` | A value that can be used to guarentee order uniqueness. Typically it is set to a random number. |
|
||||
| `feeRecipientAddress` | The entity that will receive any fees stipulated by the order. This is typically used to incentivize off-chain order relay. |
|
||||
| `makerFee` | The fee to be paid by the order maker to the `feeRecipientAddress` in the event of an order fill. Partial fills result in partial fees. |
|
||||
| `takerFee` | The fee to be paid by the taker to the `feeRecipientAddress` in the event of an order fill. |
|
||||
| `senderAddress` | An advanced field that doesn't need to be set. It allows the maker to enforce that the order flow through some additional logic before it can be filled (e.g., a KYC whitelist) -- more on the ability to extend 0x later. |
|
||||
|
||||
The 0x order message format is rigid enough to enforce the conditions under which an order maker would feel comfortable entering into a trade and yet flexible enough to represent many different kinds of trades. Currently, 0x supports trading:
|
||||
|
||||
### 1. [Fungible](https://www.investopedia.com/terms/f/fungibility.asp) tokens (those conforming to the [ERC20 standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md))
|
||||
|
||||
**Examples:**
|
||||
|
||||
|
||||
| Utility Tokens | Stable coins | Fiat-backed tokens | Crypto-backed tokens | In-game currencies | Securities |
|
||||
|-----------------------------------------------------------------|------------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|---------------------------------------------------|------------|
|
||||
| [Ether](https://blog.0xproject.com/canonical-weth-a9aa7d0279dd) | [Dai](https://makerdao.com/en/dai) | [USDC](https://www.coinbase.com/usdc) | [WBTC](https://www.wbtc.network/) | [MANA in Decentraland](https://decentraland.org/) | TBA |
|
||||
@@ -57,7 +57,7 @@ The 0x order message format is rigid enough to enforce the conditions under whic
|
||||
| [Augur REP](https://www.augur.net/) | | [Tether EUR](https://etherscan.io/token/0xabdf147870235fcfc34153828c769a70b3fae01f) | [vEOS](https://etherscan.io/token/0x8055f300b7d209ace52dc16a49352d301b2fcce2) | | |
|
||||
| [Livepeer Token](https://livepeer.org/) | | [XCHF](https://etherscan.io/token/0xb4272071ecadd69d933adcd19ca99fe80664fc08) | [vAtom](https://etherscan.io/token/0xc5637328da2e0a3400274a4088cea2e25fb91446) | | |
|
||||
|
||||
|
||||
|
||||
### 2. [Non-fungible]() tokens (Those conforming to the [ERC721 standard](http://erc721.org/))
|
||||
|
||||
**Examples:**
|
||||
@@ -83,7 +83,7 @@ A [cryptographic hash function](https://en.wikipedia.org/wiki/Cryptographic_hash
|
||||
|
||||
0x uses a hash function to create an `order digest` (order hash) that uniquely identifies all the order fields chosen by the maker. Changing any of the fields of the order will cause the order hash to change. Thanks to this property of hash functions, the order hash can be used as a unique identifier for an order. Another nice aspect of using a hash function is that all order hashes will have the same fixed length, regardless of the complexity or size of the order's fields.
|
||||
|
||||
|
||||
<Image src="/images/docs/hashing.svg" align="center" alt="Hashing" width="350px" padding="20px" marginBottom="3rem" />
|
||||
|
||||
We now have a unique, fixed-length identifier we can generate for every single permutation of a 0x order. The next step is to allow a maker to cryptographically commit to this succinct representation of their 0x order.
|
||||
|
||||
@@ -96,25 +96,25 @@ A [digital signature](https://en.wikipedia.org/wiki/Digital_signature) is a math
|
||||
|
||||
0x uses a digital signature to allow order makers to cryptographically commit to the 0x order they author. This allows the maker to rest assured that they cannot be tricked into filling any order except the ones they've authored. In turn, the potential counter-parties can verify that the maker did indeed author their 0x order(s).
|
||||
|
||||
|
||||
<Image src="/images/docs/signing.svg" align="center" alt="Signing" width="625px" padding="20px" marginBottom="3rem" />
|
||||
|
||||
For a 0x order to be considered valid and fillable, it must have all the stipulated fields mentioned above and include a digital signature from the maker attesting to all the chosen field values. At this point, the 0x order is ready to be shared with potential counter-parties.
|
||||
|
||||
## Off-chain relay, on-chain settlement
|
||||
|
||||
Up until this point, the 0x order has been created by the maker and has not yet left their computer. In order for a trade to occur, the maker must find someone willing to take the other side of the trade. Unlike other decentralized exchanges, 0x does not store orders on the blockchain. Instead orders are stored off-chain and only trade settlement occurs on-chain.
|
||||
Up until this point, the 0x order has been created by the maker and has not yet left their computer. In order for a trade to occur, the maker must find someone willing to take the other side of the trade. Unlike other decentralized exchanges, 0x does not store orders on the blockchain. Instead orders are stored off-chain and only trade settlement occurs on-chain.
|
||||
|
||||
If the maker already knows their desired counter-party, they can simply send the 0x order directly to them (i.e., via email, chat or an over-the-counter platform). If the maker doesn't know a counter-party willing to take the other side of the trade, the order can be submitted to a 0x relayer in hopes of finding a counter-party. A "relayer" is any entity that helps traders create, find and fill 0x orders. Existing relayers can be found by browsing the [Explore 0x](https://0x.org/explore) page. Anyone can build a 0x relayer and begin earning fees for every 0x trade they facilitate.
|
||||
|
||||
Once someone finds and wishes to fill the 0x order authored by the maker, they are able to fill it by submitting the order, along with the amount they wish to fill it for, to the blockchain. The 0x protocol's settlement logic will verify the makers digital signature and that all the conditions of the trade are satisfied. If so, the assets involved will be atomically swapped between the maker and taker. If any of the orders conditions are not met however, the fill request is rejected.
|
||||
|
||||
<Animation name="onOff" />
|
||||
<Animation name="onOff" marginBottom="3rem" />
|
||||
|
||||
## A non-custodial exchange protocol
|
||||
|
||||
Centralized exchanges require traders to deposit the assets they wish to trade with the exchange. From this point onwards, the exchange has full custody over the assets and the trader can only trade with other traders at that specific exchange. Centralized exchanges become large targets for hackers because they aggregate the assets of all their users into one place. There have been [over $1.5 billion stolen](https://discover.ledger.com/hackstimeline/) from centralized exchanges in the last 10 years. In response to this, the 0x protocol enables developers to build non-custodial exchanges; ones that never take custody over traders assets. Instead, the assets are settled directly between the two trader's wallets when an order is filled. This drastically reduces the counter-party risk involved with exchanging assets. Traders only need to trust a small amount of the 0x protocol source code running on the blockchain. All source code with the priviledge to move trader funds is open source, immutable and verifiable on-chain.
|
||||
|
||||
<Animation name="cexDex" />
|
||||
<Animation name="cexDex" padding="20px" marginBottom="3rem" />
|
||||
|
||||
## Networked liquidity
|
||||
|
||||
@@ -124,7 +124,7 @@ In order to help relayers share liquidity, the 0x core team has published [a sta
|
||||
|
||||
In addition to an API standard, the 0x core team is also building [0x Mesh](https://0x-org.gitbook.io/mesh/), a peer-to-peer network for sharing 0x orders. Anyone can [spin up a Mesh node](https://github.com/0xProject/0x-mesh/) and immediately start sharing 0x orders with others in the ecosystem. We hope to enable the creation of a globally accessible, physically distributed orderbook with more liquidity then any single centralized exchange.
|
||||
|
||||
<Animation name="mesh" />
|
||||
<Animation name="mesh" padding="30px" />
|
||||
|
||||
## Extending the 0x protocol
|
||||
|
||||
@@ -132,13 +132,13 @@ By design, the 0x protocol is built to be highly modular and extensible. Some ch
|
||||
|
||||
Another type of the 0x protocol extension that does not require any kind of approval to be used are aptly called [0x extensions](https://0x.org/extensions). 0x extensions add arbitrary logic that 0x orders must flow through before they can get filled or cancelled.
|
||||
|
||||
|
||||
<Image src="/images/docs/extension.png" align="center" alt="Extensions" width="700px" padding="20px" marginBottom="3rem" />
|
||||
|
||||
Examples of the types of features this enables are trading whitelists (KYC, invite-only, etc...), [Dutch auctions](https://0x.org/docs/guides/0x-extensions-explained#dutch-auction-contract) and [trade coordinators](https://0x.org/docs/guides/v2-coordinatior-specification) to name a few. We are just beginning to see the innovation this ability to permissionlessly extend the 0x protocol will unleash.
|
||||
|
||||
## Up next
|
||||
|
||||
We hope this conceptual overview of 0x was helpful in giving you a better understanding of what the 0x protocol is and the fundamental building blocks it provides developers (e.g., a standard order format, non-custodial trading/settlement, a shared liquidity pool and 0x extensions). In the next section we will dive deeper into the current technical implementation of the 0x protocol.
|
||||
We hope this conceptual overview of 0x was helpful in giving you a better understanding of what the 0x protocol is and the fundamental building blocks it provides developers (e.g., a standard order format, non-custodial trading/settlement, a shared liquidity pool and 0x extensions). In the next section we will dive deeper into the current technical implementation of the 0x protocol.
|
||||
|
||||
# 0x and Ethereum development
|
||||
|
||||
@@ -162,7 +162,7 @@ An EOA is an Ethereum account that is directly controlled by a human being. Both
|
||||
|
||||
A smart contract account is generated everytime a smart contract program is deployed to the blockchain. The contract code lives at this address. In order to invoke a function defined within a smart contract program, one must send a transaction to it's address. The transaction will also specify which function of this program the caller wishes to invoke, along with which parameters to supply. E.g., when filling an order using 0x, the taker will send an Etherem transaction to the 0x exchange contract address, specifying it should invoke the `fillOrder` function, and supply as parameters the order they want filled, and how much they want to fill it for.
|
||||
|
||||
|
||||
<Image src="/images/docs/eoa_smart_contract.svg" align="center" alt="EOA vs Smart Contract" width="650px" padding="20px" marginBottom="2.5rem" />
|
||||
|
||||
## Gas
|
||||
|
||||
@@ -251,22 +251,22 @@ Once all these fields are gathered, they are [hashed](https://en.wikipedia.org/w
|
||||
|
||||
## Subscribing to smart contract events
|
||||
|
||||
As a 0x developer, there might be times when you need to get notified when a state change occurs on-chain. For example, you might want to get an update as soon as orders from a specific maker get filled or cancelled. Ethereum let's smart contracts emit events during execution. These events can then be subscribed to and processed by your application.
|
||||
As a 0x developer, there might be times when you need to get notified when a state change occurs on-chain. For example, you might want to get an update as soon as orders from a specific maker get filled or cancelled. Ethereum let's smart contracts emit events during execution. These events can then be subscribed to and processed by your application.
|
||||
|
||||
Example 0x event:
|
||||
```solidity
|
||||
// Fill event is emitted whenever an order is filled.
|
||||
event Fill(
|
||||
address indexed makerAddress, // Address that created the order.
|
||||
address indexed makerAddress, // Address that created the order.
|
||||
address indexed feeRecipientAddress, // Address that received fees.
|
||||
address takerAddress, // Address that filled the order.
|
||||
address senderAddress, // Address that called the Exchange contract (msg.sender).
|
||||
uint256 makerAssetFilledAmount, // Amount of makerAsset sold by maker and bought by taker.
|
||||
uint256 makerAssetFilledAmount, // Amount of makerAsset sold by maker and bought by taker.
|
||||
uint256 takerAssetFilledAmount, // Amount of takerAsset sold by taker and bought by maker.
|
||||
uint256 makerFeePaid, // Amount of ZRX paid to feeRecipient by maker.
|
||||
uint256 takerFeePaid, // Amount of ZRX paid to feeRecipient by taker.
|
||||
bytes32 indexed orderHash, // EIP712 hash of order (see LibOrder.getOrderHash).
|
||||
bytes makerAssetData, // Encoded data specific to makerAsset.
|
||||
bytes makerAssetData, // Encoded data specific to makerAsset.
|
||||
bytes takerAssetData // Encoded data specific to takerAsset.
|
||||
);
|
||||
```
|
||||
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 51 KiB |
66
packages/website/public/images/docs/hashing.svg
generated
66
packages/website/public/images/docs/hashing.svg
generated
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 27 KiB |
91
packages/website/public/images/docs/signing.svg
generated
91
packages/website/public/images/docs/signing.svg
generated
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 48 KiB |
Reference in New Issue
Block a user