On Developing With 0x
Emoon recently announced our integration with the 0x protocol. We are big believers in the 0x project and their vision. We want to help grow the ecosystem around 0x and, with that in mind, we would like to provide guidance for those interested in adopting 0x.
Diving into 0x can be daunting. The sheer amount of developer documentation and open source code can be overwhelming for someone just getting started. With this in mind, we have outlined below steps for how to get started with integrating 0x.
Step 1 — Read the White Paper
Just like anyone in cryptocurrency needs to read Satoshi’s white paper to understand the foundation of bitcoin and blockchain, reading the 0x white paper is highly encouraged to understand the foundation of the protocol. At 13 pages, it isn’t particularly long and it does a great job of cogently outlining its aims and architecture. Figure 2 of Section 3 is the crux. The diagram and workflow is essential to understanding 0x; in fact, here it is reproduced below:
Another great resource for getting an overview of 0x is the podcast interview with Will Warren by Laura Shin.There’s even a transcript!
Step 2 — Understand Orders Deeply
Whether you are a creator of orders, a relayer of orders, or a consumer of orders, it is imperative that you understand the composition of a 0x order. We’ve listed the properties of an order below for good measure:
- exchangeAddress : The Exchange address.
- makerAddress : Ethereum address of the Maker.
- takerAddress : Ethereum address of the Taker.
- senderAddress : Ethereum address of a Sender .
- feeRecipientAddress : Ethereum address of the Relayer .
- expirationTimeSeconds: When will the order expire (in unix time).
- salt: Random number to make the order (and therefore its hash) unique.
- makerAssetAmount: The amount of token the Maker is offering.
- takerAssetAmount: The amount of token the Maker is requesting from the Taker.
- makerAssetData: The token address the Maker is offering.
- takerAssetData: The token address the Maker is requesting from the Taker.
- makerFee: How many ZRX the Maker will pay as a fee to the Relayer.
- takerFee : How many ZRX the Taker will pay as a fee to the Relayer.
A few things worth calling out. First, you have to wrap your head around maker and taker. Without doing so, you’re in trouble. Remember, the maker is the seller and the taker is the buyer.
Second, one might expect to see a price field. Isn’t that the point of an order after all? However, the price is a computed value, thus it doesn’t need to be a property of the order. Here is how to compute price: the takerAmount divided by the makerAmount gives you the price in the taker denomination. Confused? Let’s look at some examples:
Bob want to sell 1 Crypto Date for .001 ETH. He sets the makerAssetAmount to 1 since he is offering to sell one crypto date and the takerAssetAmount to .001 since that is the amount he wants in return. So the price he is asking for his Crypto Date is .001 / 1 = .001 ETH.
That example is obvious since we are selling only one asset. What if we are selling more than one asset and we know the price we want to get. In that case, we do simple algebra to get the taker amount: maker amount multiplied by price.
Here’s an example, where you know the price but want to get the takerAssetAmount. Alice wants to sell 100 ABC tokens for .5 ETH per token. So in this case, to figure out the correct amount to put in the takerAssetAmount, we need to solve for takerAssetAmount. Using our earlier equation, takerAssetAmount / 100 = .5. So using basic math to solve for takerAssetAmount, we would have .5 * 100 = 50.
If you use the 0x SDK, much of this work is handled for you, but regardless, it is important to understand the structure of an order if you want to have a sense of how the protocol works.
Step 3 — Get To Know The 0x Smart Contracts (Or Not)
At its core, 0x is a set of smart contracts that have been audited, verified and are great building blocks to use when facilitating atomic swaps on chain. One of the main reasons Emoon migrated to using the 0x protocol was to remove our dependency on writing smart contracts ourselves and incurring the responsibility that accompanies authoring such code.
Because we had written our own smart contracts, it was interesting to delve into the source code of the 0x smart contracts — in particular the forwarding contract — to understand how they worked under the hood. Solidity code is in fact quite readable. It is helpful to understand all the asserts in the code to know why a transaction might fail.
However, reading the source code of the contracts isn’t required. It is akin to reading the HTTP spec — not all web developers do, but it certainly is useful.
Step 4 — The 0x SDK: A Modular Set Of Packages
One can use the 0x protocol without ever using the 0x SDK. If you are going to go down that route, check out the existing ABI’s that have been published for all the 0x smart contracts. You can grab these, point at an Ethereum provider and start partying away with JSON-RPC calls.
That said, the 0x SDK is a beautiful thing. There is a lot of well written code, in addition to a plethora of comprehensive unit tests. The SDK is quite modular and can be consumed based on circumstance.
Deciding if, when and how much to use the 0x SDK is unique to each project depending on factors such as the existing codebase, the developers’ understanding of blockchain development, the use cases, the download size requirements and the software platform. If you are newer to developing dApps on the Ethereum blockchain, using the entire SDK is probably a good idea. But if you are more seasoned, you can pick and choose from modules. Take a look here at the explanations of each package and then grab packages as you need them.
Here are a few thoughts on particularly useful modules:
- If you are creating signed orders, using the 0x order utils is highly recommended. There’s a lot of trickiness in getting signatures right and if an order is incorrectly signed, it is completely useless.
- If you are using TypeScript, the 0x types library is very handy.
- Even if you are rolling your own ABI interaction, using the 0x contract addresses saves cutting/pasting/maintaining Ethereum addresses for the various 0x smart contracts.
- The 0x samples are really helpful regardless of how much of the SDK you use, to understand the workflow of how the protocol works (approvals, on chain balance validation, etc.). In particular, for consumers of signed orders, the starter project is immensely helpful. And for relayers, the relayer launch kit is very good.
Step 5 — Don’t Be Afraid To Ask For Help!
The 0x community is super helpful! Either post a GitHub issue or reach out on their Discord and a very friendly engineer will most likely be more than willing to help out!
While the Emoon experience of integrating with 0x was positive, there were some gotchas for our particular use case that are worth calling out:
- @0x/subproviders Doesn’t Work With Angular 6 When Doing Production Builds For Client or Server. Read more here.
- Old Version of bignumber.js. Read more here.
- If using the forwarding contract, remember that the taker (aka the buyer) pays any forwarding fees, not the maker (seller). As such, one has to factor that fee into the amount of ETH sent to the forwarding contract. This works differently than many other smart contracts that do atomic swaps, like Crypto Kitties for example, which take the fee from the seller.
- Also, if using the forwarding contract, remember that the maker (the seller) gets paid in WETH. The buyer is nicely abstracted from WETH but the seller is not, which is important to communicate to sellers who may be surprised when their order is filled but their ETH balance remains unchanged.
- Reading the 0x contracts is quite tricky, because of all the includes and nested files. Best bet is to actually print them out so you can bounce around between includes.
We are big fans of the 0x project at Emoon. The architecture is solid; the smart contracts are solid; the SDK is solid. We look forward to seeing the ecosystem around 0x continue to grow. Feel free to reach out to us if you have questions!