The ZrxTool development kit is suitable for quickly adding support for the 0x protocol for Go applications, and realizing the off-chain generation, circulation and on-chain settlement of ERC20 exchange orders. The official download address of ZrxTool development kit: 0x protocol docking Golang development kit .
1. Overview of the development kit
The ZrxTool development kit mainly includes the following features:
- Generate compliant 0x orders offline and sign offline
- Built-in 0x Mesh network support, you can submit 0x orders to the Mesh network, or query the existing 0x orders in the Mesh network
- Settle 0x orders on the Ethereum chain, support the main chain, Ropsten/Rinkeby/Kovan test chain
- Support local Ganache private chain for efficient development and testing
The ZrxTool development kit supports Go 1.13, and the current version is 1.0.0. The main types and relationships are shown in the following figure:
The main code file list of ZrxTool is as follows:
| Code file | Description |
|---|---|
| zrxtool/order/ | 0x order package directory |
| zrxtool/order/factory.go | 0x order package object instantiation code |
| zrxtool/order/erc20.go | ERC20 token related operation code |
| zrxtool/order/validity.go | 0x order signature related code |
| zrxtool/order/liquidity.go | 0x order Mesh network support code |
| zrxtool/order/fill.go | 0x order settlement code on the Ethereum chain |
| zrxtool/order/query.go | 0x Mesh network order query code |
| zrxtool/zrx/ | Protocol package directory on the Ethereum chain |
| zrxtool/zrx/DevUtils/ | 0x DevTuils protocol docking package |
| zrxtool/zrx/ERC20Token/ | Ethereum ERC20 protocol docking package |
| zrxtool/zrx/Exchange | 0x Exchange protocol docking package |
| zrxtool/zrx/WETH9/ | WETH9 protocol docking package |
| zrxtool/demo/ | Demo code directory |
| zrxtool/demo/wraporder.go | 0x order creation demo code |
| zrxtool/demo/prepare.go | 0x Optional preparation operation demo code before order submission |
| zrxtool/demo/addorder.go | Demonstration code for submitting 0x order to Mesh network |
| zrxtool/demo/getorders.go | Mesh network 0x order query demo code |
| zrxtool/demo/fillorder.go | On-chain order execution demo code |
| go.mod | Go module management files |
| go.sum | Go module management files |
2. Run the demo program
Before running the demo program preset in the development kit, please ensure that the 0x Mesh node and the Ethereum node have been properly deployed.
0x order packaging : execute the following command to run the 0x order packaging demo:
go run demo/wraporder.go
The output is as follows:
ERC20 authorization : Execute the following commands to run WETH exchange and ERC20 authorization demonstration:
go run demo/prepare.go
The output is as follows:
Submit 0x order : Execute the following command to submit 0x order to Mesh network:
go run demo/addorder.go
The output is as follows:
Query 0x orders : execute the following command to query 0x orders in the Mesh network:
go run demo/getorders.go
The output is as follows:
Execute 0x order : execute the following order to settle the order on the chain:
go run demo/fillorder.go
The output is as follows:
3. Create 0x order
The entry class of the ZrxTool development kit OrderWrappercan be considered as an enhanced version of 0x order, which can directly interact with mesh nodes and 0x chain protocols.
You can create an instance of OrderWrapper directly, or use the WrapJson()method of the order package to create, and then use this encapsulated 0x order object to submit, execute, and other operations.
For example, the following code uses JSON description to create 0x order:
// import zrxtool/order
jsonOrder := `{
"chainId": 1337,
"exchangeAddress": "0x48bacb9266a570d521063ef5dd96e61686dbe788",
"makerAddress": "0x5409ED021D9299bf6814279A6A1411A7e866A631",
"makerAssetAmount": 5000000000000000000,
"makerAssetAddress": "0x871dd7c2b4b25e1aa18728e9d5f2af4c4e431f5c",
"takerAssetAddress": "0x0b1ba0af832d7c05fd64161e0db78e85978e8082",
"takerAssetAmount": 100000000000000000,
"makerFee": 0,
"takerFee": 0,
"expirationTimeSeconds": 1598025600,
"salt": 7898123
}` // JSON订单
orderWrapper,_ := order.WrapJson([]byte(jsonOrder))
4. Bind Ethereum and Mesh network
Use the ObjectWrapper Bind()method to bind the order packaging object to a specific Ethereum network and Mesh network for subsequent order operations. E.g:
orderWrapper.Bind(
"http://localhost:8545", // 以太坊节点RPC API
"ws://localhost:60557" // Mesh节点 WS RPC API
)
5. Code asset data
The 0x protocol requires that the asset contract information be encoded into a specified asset data format, which can be done using the EncodeAssetData()method of OrderWrapper .
For example, to encode ZRX tokens on the Ganache chain:
zrxAddress := "0x871dd7c2b4b25e1aa18728e9d5f2af4c4e431f5c"
data,_ := orderWrapper.EncodeAssetData(zrxAddress)
OrderWrapper provides two syntactic sugars for encoding digital assets specified by Maker and Taker. E.g:
data1, _ := orderWrapper.EncodeMakerAssetData() //编码订单中Maker的资产
data2, _ := orderWrapper.EncodeTakerAssetData() //编码订单中Taker的资产
Note : These two syntactic sugars not only return the encoded asset data, but also update the MakerAssetDatasum TakerAssetDatafield value of the encapsulated 0x order object .
6. Maker signature
In accordance with the requirements of the 0x agreement, Maker needs to sign before submitting an order. This can be done using the SignWithMakerKey()method of OrderWrapper . E.g:
makerKey := "0xf2f48ee19680706196e2e3…030670656b0e0164837257d"
signedOrder,_ := := orderWrapper.SignWithMakerKey(makerKey)
Note : In addition to returning the signed order object, this method also updates the Signaturefields of the encapsulated 0x order object .
7. Submit 0x order to Mesh network
Use the SubmitToMesh()method of OrderWrapper to submit 0x orders to the Mesh network. E.g:
orderId,_ := orderWrapper.SubmitToMesh() // 返回订单ID
When the order is received by the Mesh node, the above call will return the order ID. If the order is rejected by the Mesh node or other errors occur, a non-empty error object will be returned.
One of the main reasons why orders with correct signatures are rejected by Mesh nodes is that Maker or Taker did not authorize the 0x protocol to operate their token assets to be traded.
8. Query 0x orders in the Mesh network
Use the GetMeshOrder()method of the order package to query the 0x order in the Mesh network. This method supports paging results. E.g:
rsp, _ := order.GetMeshOrders(
"ws://localhost:60557", // Mesh节点WS RPC API
0, // 查询页号
100 // 每页结果数量
)
for _, oi := range rsp.OrdersInfos {
Fmt.Printf("signed order => %+v\n", oi.SignedOrder)
}
9. Taker executes the order
Taker uses the FillOrder()method of OrderWrapper to execute orders. E.g:
value := big.NewInt(100000000) // 执行数量
fee := big.NewInt(100000000000000000) // 手续费
key :="0x5d862464fe930345…d219789b3eb2128075a76f72" // taker私钥
txid, _ := orderWrapper.FillOrder(value,fee,key) //返回交易ID
10. ERC20 asset authorization
One of the main reasons why the 0x order submitted to the Mesh node is rejected is that the 0x protocol is not properly authorized for ERC20 assets. OrderWrapper provides ApproveAsset()methods to facilitate
this operation.
For example, Maker authorizes the 0x chain protocol to operate the ZRX tokens it holds, and the authorized number is 1E18:
zrxAddress := "0x871dd7c2b4b25e1aa18728e9d5f2af4c4e431f5c"
value := big.NewInt(1000000000000000000)
makerKey := "0xf2f48ee19680706196e2e3…030670656b0e0164837257d"
txid,_ := orderWrapper.ApproveAsset(zrxAddress,value, makerKey) //返回授权交易ID
There is no need to perform authorization operations every time, for example, you can perform a nearly unlimited authorization:
txid,_ := orderWrapper.ApproveAssetUnlimited(zrxAddress, makerKey)
This method actually sets the number of authorizations to 2^256.
OrderWrapper also provides four syntactic sugars for Maker and Taker authorization operations:
makerKey := "0x…" // Maker私钥
takerKey := "0x…" // Taker私钥
orderWrapper.ApproveMakerAsset(makerKey) // 按订单信息Maker授权
orderWrapper.ApproveMakerAssetUnlimited(makerKey) // 无限量Maker授权
orderWrapper.ApproveTakerAsset(takerKey) // 按订单信息Taker授权
orderWrapper.ApproveTakerAssetUnlimit(takerKey) // 无限量Taker授权
11. Ether/WETH conversion
The 0x protocol cannot directly process ETH/ERC20 exchange, so you need to convert ETH to WETH one-to-one first. You can use the OrderWrapper WrapEther()method to encapsulate ETH into WETH, or use the UnwrapEther()method to convert WETH to ETH. E.g:
key := "0x.." //兑换人私钥
txid, _ := orderWrapper.WrapEther(big.NewInt(1000), key) //返回交易ID
OrderWrapper also provides two syntactic sugars for Maker and Taker to convert ETH to WETH, for example:
txid1, _ := orderWrapper.WrapMakerEther(makerKey) // 按订单信息兑换WETH
txid2, _ := orderWrapper.WrapTakerEther(takerKey) // 按订单信息兑换WETH
ZrxTool official download address: http://sc.hubwiz.com/codebag/zrxtool/