The JSON-RPC API is intended to be a private API. The API should only be accessible to the developers running the Mesh node and should not be exposed to the public. The API runs on a separate port from the peer-to-peer protocols and access to it can be controlled via a firewall.
Peers in the network do not use the JSON-RPC API and instead use a peer-to-peer PubSub mechanism (usually this is not something you need to worry about).
Similarities to the Ethereum JSON-RPC API
Our JSON-RPC API is very similar to the Ethereum JSON-RPC API; we even use a lot of the same code from go-ethereum.
Some key differences:
It is only accessible via HTTP and WebSocket transports (IPC not supported)
uint256 amounts should not be hex encoded, but rather sent as numerical strings
Since the API adheres to the JSON-RPC 2.0 spec, you can use any JSON-RPC 2.0 compliant client in the language of your choice. The clients made for Ethereum work even better since they extend the standard to include subscriptions.
accepted: means the order was found to be fillable for a non-zero amount and was therefore added to 0x Mesh (unless it already added of course)
rejected: means the order was not added to Mesh, however there could be many reasons for this. For example:
The order could have been unfillable
It could have failed some Mesh-specific validation (e.g., max order acceptable size in bytes)
The network request to the Ethereum RPC endpoint used to validate the order failed
Some rejected reasons warrant attempting to add the order again. Currently, the only reason we recommend re-trying adding the order is for the NetworkRequestFailed status code. Make sure to leave some time between attempts.
Note: The fillableTakerAssetAmount takes into account the amount of the order that has already been filled AND the maker's balance/allowance. Thus, it represents the amount this order could actually be filled for at this moment in time.
mesh_getOrders
Gets orders already stored in a Mesh node at a particular snapshot of the DB state. This is a paginated endpoint with parameters (page, perPage and snapshotID).
This payload is requesting 100 orders from the 1st page (think: offset). The third parameter is the snapshotID which should be left empty for the first request. The response will include the snapshotID that can then be supplied in subsequent requests.
Allows the caller to subscribe to a stream of OrderEvents. An OrderEvent contains either newly discovered orders found by Mesh via the P2P network, or updates to the fillability of a previously discovered order (e.g., if an order gets filled, cancelled, expired, etc...). OrderEvents do not correspond 1-to-1 to smart contract events. Rather, an OrderEvent about an orders fillability change represents the aggregate change to it's fillability given all the transactions included within the most recently mined/reverted blocks.
Example: If an order is both filled and cancelled within a single block, the EndState of the OrderEvent will be CANCELLED (since this is the final state of the order after this block is mined). The OrderEventwill however list the contract events intercepted that could have impacted this orders fillability. This list will include both the fill event and cancellation event.
Mesh has implemented subscriptions in the same manner as Geth. In order to start a subscription, you must send the following payload:
result contains the subscriptionId that uniquely identifies this subscription. The subscription is now active. You will now receive event payloads from Mesh of the following form:
After a sustained network disruption, it is possible that a WebSocket connection between client and server fails to reconnect. Both sides of the connection are unable to distinguish between network latency and a dropped connection and might continue to wait for new messages on the dropped connection. In order to avoid this, and promptly establish a new connection, clients can subscribe to a heartbeat from the server. The server will emit a heartbeat every 5 seconds. If the client hasn't received the expected heartbeat in a while, it can proactively close the connection and establish a new one. There are affordances for checking this edge-case in the WebSocket specification however our research has found that many WebSocket clients fail to provide this functionality. We therefore decided to support it at the application-level.
result contains the subscriptionId that uniquely identifies this subscription. The subscription is now active. You will now receive event payloads from Mesh of the following form:
