Rook
Search…
Coordinator WS API
The Rook Protocol WebSocket API is used by Keepers to communicate with the Coordinator in real-time.
Under Construction This documentation is being actively worked on. Use at your own risk, or consult Rook developers directly with questions.

Introduction

WS endpoint

This API is API key protected and currently only provided to Keepers. Contact us to gain access.

API Key

Each request requires a valid API key which must be provided in the message payload. Contact us to acquire an API key.
1
{
2
'apiKey': '1243-567-890',
3
}
Copied!

ChainId

Please use chainId 1 when communicating with the Coordinator on Ethereum mainnet. Do note that many of these examples may contain a different chainId because they were copied from a test environment.

WebSocket API

Message Types

The message type is specified in the JSON payload using the type field.

Subscribe

Used to subscribe to a channel to receive messages indicating when a new auction of a particular type has started.
Example Request:
1
{
2
"apiKey": "1243-567-890",
3
"channel": "limitOrder",
4
"requestId": 38520892865339,
5
"type": "subscribe"
6
}
Copied!
Example Success Response:
1
{
2
"type": "subscribe",
3
"channel": "limitOrder",
4
"message": "Successfully subscribed to channel",
5
}
Copied!

Bid

Used to place a bid on one or more orders. See placing bids for how to structure the payment field. See the example below for the limit order bid format. The auctionId is the hiding book order hash.
Example Request:
1
{
2
"bids":[
3
{
4
"auctionId":"0x5a23000386c7b763f77e947bd64571afbde64d848d207fa981c32587eafaec00",
5
"chainId":31337,
6
"channel":"limitOrder",
7
"protocol":"zrxV4RFQ",
8
"takerTokenTargetFillAmount":222
9
}
10
],
11
"payment":{
12
"stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
13
"stakeSpent":66159044473427503,
14
"stakeNonce":1,
15
"channelNonce":0,
16
"previousCommitmentHash":"0x0000000000000000000000000000000000000000",
17
"stakeAddressSignature":"0x29b2daf2484ad20bf31d2f4e8da5656ccb14f4f0cfac1d9742d101bec79144a95ad7cbc3c8d039823dd38a2ca384dfc762041743e908ec514fccae4b3e293d0e1b",
18
"identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
19
"takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00"
20
},
21
"requestId":29234464271939,
22
"type":"bid",
23
"apiKey": "1243-567-890",
24
}
Copied!

Refund

Used to issue any outstanding refunds. Must provide a stake address, channel nonce, the latest stake nonce, and a signature from the stake address in the payload. See refunds:
Example Request:
1
{
2
"payload":{
3
"channelNonce": 0,
4
"stakeAddress": "0x407EA0314F43E4cbBab28Bfd47f391e8968c9643",
5
"stakeAddressSignature": "0xf293586e495027b5893c00000016040b3041f4aef9d5ae000051fe2dac7c73aa64cc127bd156beb2f9b4d69c80ab3dd2cfc494b31cbb69b83844a78dc85859711c",
6
"stakeNonce": 1
7
},
8
"requestId": 33684210724642,
9
"type": "refund",
10
"apiKey": "1243-567-890",
11
}
Copied!
Example Response:
1
{
2
"type": "refund",
3
"requestId": "33684210724642",
4
"payload": {
5
"refundCommitment": {
6
"stakeAddress": "0x407ea0314f43e4cbbab28bfd47f391e8968c9643",
7
"stakeSpent": 0,
8
"stakeNonce": 2,
9
"channelNonce": 0,
10
"previousCommitmentHash": "0x38fc7f3df34366e402d8b665cba162cde3508bfbb333fa77450ce1529a539ecb",
11
"stakeAddressSignature": null,
12
"coordinatorSignature": "0x5b8df00000e3a0539a042ffcd26d000002a8912e2d568a4a862126acc122aa342f12c56f4d7b01117cf6ac393464b3c4f52998c8f2b0b9725d0282c7f1e2f76d1c",
13
"stakeAddressInstantWithdrawalSignature": null,
14
"coordinatorInstantWithdrawalSignature": null
15
}
16
}
17
}
Copied!

Auction

Used by the Coordinator to deliver information about who has been greenlit for an auction.
Example Greenlight Message:
1
{
2
"channel":"limitOrder",
3
"type":"auction",
4
"requestId":82091778811918,
5
"payload":{
6
"auctionIdList":[
7
"0xab29508897ee5a2714fa58705bd834390e8cf9979b5202680c05ca2e4459a05c"
8
],
9
"identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
10
"stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
11
"takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00",
12
"greenlit":1,
13
"bidState":"locked"
14
}
15
}
Copied!

Keep Alive

Used to keep the connection alive.
Example Request:
1
{
2
"type": "keepAlive",
3
"requestId":82091778811918,
4
"apiKey": "1243-567-890",
5
}
Copied!

Get Info

Used to retrieve relevant contract addresses.
Example Request:
1
{
2
"type": "info",
3
"requestId": 33684210724642,
4
"apiKey": "1243-567-890",
5
}
Copied!

Enumerated Types

Messages to and from the Coordinator may contain enumerated types. Please refer to this section to determine what each value corresponds with. For example, let's say a Keeper wants to place a bid to fill a limit order on zrxV4RFQ. They would use bid, zrxV4RFQ, and limitOrder when constructing their message payload.

Protocol

1
class Protocol(Enum):
2
zrxV4RFQ = "zrxV4RFQ"
3
keeperDAOSwapV0 = "swapV0"
Copied!

BidState

1
class BidState(Enum):
2
awaitingBids = 1
3
locked = 2
4
softCanceled = 3
Copied!

Channel

1
class Channel(Enum):
2
limitOrder = "limitOrder"
3
kCompound = "kCompound"
4
kAave = "kAave"
5
bProtocol = "bProtocol"
Copied!

MessageType

1
class MessageType(Enum):
2
subscribe = "subscribe"
3
keepAlive = "keepAlive"
4
bid = "bid"
5
auction = "auction"
6
info = "info"
7
refund = "refund"
Copied!

GreenlightResult

1
class GreenlightResult(Enum):
2
lose = 0
3
win = 1
Copied!

Payment Channels Staking Contract

Structs

StakeCommitment

1
struct StakeCommitment {
2
address stakeAddress;
3
uint256 stakeSpent;
4
uint256 stakeNonce;
5
uint256 channelNonce;
6
bytes data;
7
bytes stakeAddressSignature;
8
bytes coordinatorSignature;
9
}
Copied!
See Transacting Using the Payment Channel for an explanation of each field.

Methods

getStakerState

1
function getStakerState(address _stakeAddress) public view returns (
2
uint256 _stakedAmount,
3
uint256 _stakeNonce,
4
uint256 _stakeSpent,
5
uint256 _channelNonce,
6
uint256 _withdrawalTimelock
7
);
Copied!
Used to retrieve the most recent settled state for a payment channel. _withdrawalTimelock will be non-zero if the payment channel is currently in the timelocked withdrawal process and will indicate the timestamp of the timelock's expiration.

stakeCommitmentHash

1
function stakeCommitmentHash(
2
address _stakeAddress,
3
uint256 _stakeSpent,
4
uint256 _stakeNonce,
5
uint256 _channelNonce,
6
bytes memory _data
7
) public pure returns (bytes32);
Copied!
Used to calculate the hash of a payment channel commitment for signing.

getCurrentWithdrawalTimelock

1
function getCurrentWithdrawalTimelock(
2
address _stakeAddress
3
) public view returns (uint256);
Copied!
Used to retrieve the current withdrawal timelock for the payment channel of the provided stake address. It will be zero if there is no timelock and will return the timestamp of the timelock's expiry otherwise.

stake

1
function stake(uint256 _amount) public;
Copied!
Used to stake rook, adding rook to the active payment channel of msg.sender if there is one, and creating a new payment channel otherwise. Not that additional rook cannot be staked for a payment channel that is currently in a withdrawal timelock.

initiateTimelockedWithdrawal

1
function initiateTimelockedWithdrawal(
2
StakeCommitment memory _commitment
3
) external;
Copied!
Used to initiate the timelocked withdrawal process.

executeTimelockedWithdrawal

1
function executeTimelockedWithdrawal(
2
address _stakeAddress
3
) public;
Copied!
Used to complete the timelocked withdrawal process and withdraw the remaining rook in a payment channel.

executeInstantWithdrawal

1
function executeInstantWithdrawal(
2
StakeCommitment memory _commitment
3
) external;
Copied!
Used to complete the instant withdrawal process and withdraw the remaining rook in a payment channel.