Links

Websocket

Currently, there is only public channel.

Connect

In the public channel, when the client successfully connects to the ZkLink node, the server will return a message with ID 0, which contains the listen_key automatically created by the server for the connection:
{ "result":
{
"listen_key": "9752db94ea664f1ea1e58074f547a9fe"
},
"error_code": 0,
"error_msg": "",
"id": 0
}
The server will send ping frame to the client every two minutes, and the client should reply the pong frame within 10 minutes, otherwise the connection will be automatically disconnected.

Public Topics

  • Topic of transaction execution results: txExecuteResult@{sub_account_id}, for example when sub_account_id is 1, the topic will be txExecuteResult@1;
  • full exit event: fullExitEvent@{sub_account_id}, for example when sub_account_id is 1, the topic will be fullExitEvent@1.

Subscribe & Unsubscribe Topics

The client can subscribe and unsubscribe to topics at any time after connecting, and only needs to send a request to the service:
{
"method": "subscribe",
"topics": ["fullExitEvent@01", "txExecuteResult@1"],
"id": 1
}
where the value of method can be subscribe or unSubscribe. The id in the response content is an unsigned integer, which serves as the unique identifier of the communication. It also contains the value of the currently subscribed topic list.
{
"result": {
"topics":["fullExitEvent@01", "txExecuteResult@1"]
},
"error_code":0,
"error_msg":"",
"id":1
}

Query Topic

GET /api/topics/{listen_key}
The client can use the listen_key(returned when the Websocket first connection) to query the topic list of its corresponding Websocket connection. The return value is:
["txExecuteResult@1", "fullExitEvent@1"]
When the Websocket connection corresponding to listen_key is disconnected, null is returned.

Data Push

Transaction Execution Results

topic: txExecuteResult@{sub_account_id}
Name
Type
Describe
type
String
Event type
tx_hash
TxHash
The tx hash on L1
tx
ZklinkTx
Transaction detail
receipt
struct
The transaction status after received
> executed
bool
The transaction finished executing or not
> executedTimestamp
Option
The Unix microsecond timestamp when transaction excute, when executed is false, the value will be null
> success
bool
The transaction executed successfull or not
> failReason
Option
The reason that transaction execute fail, the value will be null if transaction execute success
> block
Option
Block height that contains the transaction, it will be null if success is false
> index
Option
The transaction index in the block, if value will be null if success is false
updates
Update event
{
"type": "TxExecuteResult",
"tx_hash": "0xde9b5a916309f5097825ed1fb34eb5cc3a52faa1f5ef901aab54ef546d8e86b7",
"tx": {
"type": "Transfer",
"accountId": 8,
"fromSubAccountId": 3,
"toSubAccountId": 3,
"to": "0xbfDa941Bd2a0eddB57b10f8E8d3486A738B92cCC",
"token": 3,
"amount": "998000000000000000",
"fee": "3000000000000000",
"ts": 1646101085,
"nonce": 1,
"signature": {
"pubKey": "0x0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724",
"signature": "892c622afac908201df54a3cfdecf8eba46d5411bdc29365f5536f024c195f2893d6313a6371fe1659830e2560c1eaedbafcc835837593d017cd557074f0bb03"
}
},
"receipt": {
"executed": true,
"executedTimestamp": 1689731233000000,
"success": true,
"failReason": null,
"block": 3947,
"index": 1
},
"updates": [
{
"type": "BalanceUpdate",
"updateId": 12,
"accountId": 2,
"subAccountId": 0,
"coinId": 18,
"oldBalance": "3018976060000000000000",
"newBalance": "3018975850000000000000",
"oldNonce": 115,
"newNonce": 116
},
{
"type": "BalanceUpdate",
"updateId": 13,
"accountId": 2,
"subAccountId": 1,
"coinId": 18,
"oldBalance": "114000000000000",
"newBalance": "115000000000000",
"oldNonce": 115,
"newNonce": 116
},
{
"type": "BalanceUpdate",
"updateId": 14,
"accountId": 0,
"subAccountId": 0,
"coinId": 18,
"oldBalance": "1023826000000000000",
"newBalance": "1024035000000000000",
"oldNonce": 0,
"newNonce": 0
}
]
}

Full Exit Event

topic: fullExitEvent@{sub_account_id}
Name
Type
Description
type
String
Event type
tx_hash
TxHash
The tx hash on L1
tx
FullExit transaction
For example:
{
"type": "FullExitEvent",
"tx_hash": "0xde9b5a916309f5097825ed1fb34eb5cc3a52faa1f5ef901aab54ef546d8e86b7",
"tx": {
"type": "FullExit",
"toChainId": 1,
"accountId": 25,
"subAccountId": 1,
"exitAddress": "0xae08c2e27765faef5cb05908dbac12242caf91af",
"l2SourceToken": 47,
"l1TargetToken": 47,
"serialId": 43,
"ethHash": "0x748d32538f71d937d9e2c47adc26c499d0451b87e4fd337c2d6190c3271dafd7"
}
}