Rook
Search…
Coordinator HTTP API
The Rook Protocol HTTP API is used by Keepers to communicate with the Coordinator for general communications.
Under Construction This documentation is being actively worked on. Use at your own risk, or consult Rook developers directly with questions.

Introduction

HTTP endpoint

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

Headers

{
'content-type': 'application/json',
'Api-Key': '1243-567-890',
}

HTTP Methods

Get Keeper Stake Channel

Retrieve the payment channel for a Keeper.
GET /keeperStakeChannel
Query parameters:
  • stakeAddress: The address of the KSA that owns the channel.
  • channelNonce: The channel nonce for the channel being fetched.
Example Call:
/keeperStakeChannel?stakeAddress=0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141&channelNonce=0
Example Response:
{
"result": {
"stakeAddress": "0x333d1ecc55e5e27c29ad39ba4e435bb78f6a7141",
"channelNonce": 0,
"stakedAmount": 1000000000000000000,
"refundAccrued": 0,
"latestBidAmount": 17606335671297342,
"latestStakeAddressSignedCommitment": {
"stakeAddress": "0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141",
"stakeSpent": 17606335671297342,
"stakeNonce": 1,
"channelNonce": 0,
"previousCommitmentHash": "0x0000000000000000000000000000000000000000",
"stakeAddressSignature": "0x456db65684e614577d81464fe8e85ba425dfe5517f5b3ee35e6f254b47e1567f6e4df8f335c28e52735459d033944ee2648f3e9e2f63244608d31cb42b710c401c",
"coordinatorSignature": "0xa333e269e3dce93846fe1a1d21cb62381f7d35ea7fd01f78464d04ddfea5b34b55ae391cf731d5c14ecd2dea6ae71831b29ffcbf3bd7b702d3c64663e20860411b",
"stakeAddressInstantWithdrawalSignature": null,
"coordinatorInstantWithdrawalSignature": null
},
"latestCommitment": {
"stakeAddress": "0x333d1ecc55e5e27c29ad39ba4e435bb78f6a7141",
"stakeSpent": 0,
"stakeNonce": 2,
"channelNonce": 0,
"previousCommitmentHash": "0xbe8454781dfc5a217358b1247e0a74946b1940ffb43bea506e9ea0f7dc74cd2c",
"stakeAddressSignature": null,
"coordinatorSignature": "0xeb4bc5684e6146055a525e17c306251c90e0138785684e614162fb610ae6cc5f183541b33f76fcd9be0cd6043bac3b1259044e93b45413f03472a2b59867c7421c",
"stakeAddressInstantWithdrawalSignature": null,
"coordinatorInstantWithdrawalSignature": null
},
"isOpen": true,
"fullySettled": false
},
"message": "Ok"
}
  • refundAccrued indicates the outstanding refunds accrued in the payment channel from lost auctions and failure to fill orders.
  • isOpen is true if the Coordinator is still accepting bid commitments from the channel and false otherwise.
  • fullySettled is set to true once the KSA has withdrawn their remaining Rook for the payment channel from the staking contract and false otherwise.
  • latestStakeAddressSignedCommitment may not necessarily be the latest commitment. When Keepers request a refund, the Coordinator generates a new commitment with the refundAccrued subtracted from the prior commitment's stakeSpent. This commitment will only have the Coordinator's signature on it. If the Keeper wants to withdraw with this commitment, they still have everything they need.

Get Info

Retrieve relevant contract addresses, greenlight algorithm parameters, and general information about the Coordinator.
GET /info
Example Response:
{
"result": {
"stakeContract": "0x6662db49A05Cbe2Fb2Da2aa449f55197050E0164",
"chainId": 1,
"greenlightScoreWeight": {
"bid": 4.0,
"random": 1.0,
"targetFillAmount": 2.0,
"reputation": 1.0,
"stake": 1.0
},
"greenlightScorePower": {
"bid": 2.0,
"random": 1.0,
"targetFillAmount": 4.0,
"reputation": 1.2,
"stake": 1.2
},
"minBidThreshold_percentageOfHighestBid": 0.3,
"bidAllocationPercentage": {
"user": 0.8,
"burn": 0.04,
"stakingPool": 0.1,
"keeperDAO": 0.06
},
"auctionDuration_seconds": 3,
"keeperActionDeadline_blocks": 4
},
"message": "Ok"
}

Get Refund Request Message Hash

Retrieve message hash for signing that will be used to initiate an instant withdrawal request.
GET /refundRequestMessageHash
Query Parameters:
  • stakeAddress: The stake address withdrawing their staked Rook.
  • stakeNonce: The latest stake nonce of the channel being withdrawn from.
  • channelNonce: The channel nonce of the channel being withdrawn from.
Example Call:
refundRequestMessageHash?stakeAddress=0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141&channelNonce=0&stakeNonce=5
Example Response:
{
"result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
"message": "Ok"
}
A Keeper can calculate the hash themselves. The message hash is calculated in python as:
keccak_256(
eth_abi.encode_single(
'(string,address,uint256,uint256)',
['refund', stakeAddress, stakeNonce, channelNonce]
)
)

Get Stake Address Identity Registration Message Hash

Retrieve message hash for signing that will be used to register a KSA with an identity address.
GET /stakeAddressIdentityRegistrationMessageHash
Query Parameters:
  • stakeAddress: The stake address being registered.
  • identityAddress: The identity address the stake address is being registered to.
  • expirationTime: Unix timestamp in seconds. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
"result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
"message": "Ok"
}

Register Stake Address Identity

Register a KSA to an identity address.
POST /registerStakeAddressIdentity
Query Parameters:
  • stakeAddress: The stake address being registered.
  • identityAddress: The identity address the stake address is being registered to.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
  • stakeAddressSignature: Only required if the stakeAddress is already registered to an identityAddress.
  • identityAddressSignature: The Ethereum signature of the identity address on the hash output from /stakeAddressIdentityRegistrationMessageHash

Get Taker Address Identity Registration Message Hash

Retrieve message hash for signing that will be used to register a KTA with an identity address.
GET /takerAddressIdentityRegistrationMessageHash
Query Parameters:
  • takerAddress: The taker address being registered.
  • identityAddress: The identity address the taker address is being registered to.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
"result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
"message": "Ok"
}

Register Taker Address Identity

Register a KTA to an identity address.
POST /registerTakerAddressIdentity
Query Parameters:
  • takerAddress: The taker address being registered.
  • identityAddress: The identity address the stake address is being registered to.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
  • takerAddressSignature: Only required if the takerAddress is already registered to an identityAddress.
  • identityAddressSignature: The Ethereum signature of the identity address on the hash output from /takerAddressIdentityRegistrationMessageHash

Get Address Identity Unregistration Message Hash

Retrieve message hash for signing that will be used to unregister a KTA or KSA from an identity address.
GET /addressIdentityUnregistrationMessageHash
Query Parameters:
  • identityAddress: The identity address the KTA or KSA is being unregistered from.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
"result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
"message": "Ok"
}

Unregister Stake Address Identity

Unregister a KSA from an identity address.
POST /unregisterStakeAddressIdentity
Query Parameters:
  • stakeAddress: The stake address being unregistered.
  • identityAddress: The identity address the stake address is being unregistered from.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
  • identityAddressSignature: The Ethereum signature of the identity address on the hash output from /addressIdentityUnregistrationMessageHash

Unregister Taker Address Identity

Unregister a KTA from an identity address.
POST /unregisterTakerAddressIdentity
Query Parameters:
  • takerAddress: The taker address being unregistered.
  • identityAddress: The identity address the taker address is being unregistered from.
  • expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
  • identityAddressSignature: The Ethereum signature of the identity address on the hash output from /addressIdentityUnregistrationMessageHash

Get Instant Withdrawal Request Message Hash

Retrieve message hash for signing that will be used to initiate an instant withdrawal request.
GET /instantWithdrawalRequestMessageHash
Query Parameters:
  • stakeAddress: The stake address withdrawing their staked Rook.
  • channelNonce: The channel nonce of the channel being withdrawn from.
Example Response:
{
"result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
"message": "Ok"
}

Initiate Instant Withdrawal

Initiate an instant withdrawal. Once fully processed, the coordinator's instant withdrawal signature can be retrieved from the /keeperStakeChannel endpoint.
POST /initiateInstantWithdrawal
Query Parameters:
  • stakeAddress: The stake address being unregistered.
  • channelNonce: The channel nonce of the channel being withdrawn from
  • stakeAddressSignature: The Ethereum signature of the stake address on the hash output from /instantWithdrawalRequestMessageHash

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:
{
"channel": "limitOrder",
"requestId": 38520892865339,
"type": "subscribe"
}
Example Success Response:
{
"type": "subscribe",
"channel": "limitOrder",
"message": "Successfully subscribed to channel",
}

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:
{
"bids":[
{
"auctionId":"0x5a23000386c7b763f77e947bd64571afbde64d848d207fa981c32587eafaec00",
"chainId":31337,
"channel":"limitOrder",
"protocol":"zrxV4RFQ",
"takerTokenTargetFillAmount":222
}
],
"payment":{
"stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
"stakeSpent":66159044473427503,
"stakeNonce":1,
"channelNonce":0,
"previousCommitmentHash":"0x0000000000000000000000000000000000000000",
"stakeAddressSignature":"0x29b2daf2484ad20bf31d2f4e8da5656ccb14f4f0cfac1d9742d101bec79144a95ad7cbc3c8d039823dd38a2ca384dfc762041743e908ec514fccae4b3e293d0e1b",
"identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
"takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00"
},
"requestId":29234464271939,
"type":"bid"
}

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:
{
"payload":{
"channelNonce": 0,
"stakeAddress": "0x407EA0314F43E4cbBab28Bfd47f391e8968c9643",
"stakeAddressSignature": "0xf293586e495027b5893c00000016040b3041f4aef9d5ae000051fe2dac7c73aa64cc127bd156beb2f9b4d69c80ab3dd2cfc494b31cbb69b83844a78dc85859711c",
"stakeNonce": 1
},
"requestId": 33684210724642,
"type": "refund"
}
Example Response:
{
"type": "refund",
"requestId": "33684210724642",
"payload": {
"refundCommitment": {
"stakeAddress": "0x407ea0314f43e4cbbab28bfd47f391e8968c9643",
"stakeSpent": 0,
"stakeNonce": 2,
"channelNonce": 0,
"previousCommitmentHash": "0x38fc7f3df34366e402d8b665cba162cde3508bfbb333fa77450ce1529a539ecb",
"stakeAddressSignature": null,
"coordinatorSignature": "0x5b8df00000e3a0539a042ffcd26d000002a8912e2d568a4a862126acc122aa342f12c56f4d7b01117cf6ac393464b3c4f52998c8f2b0b9725d0282c7f1e2f76d1c",
"stakeAddressInstantWithdrawalSignature": null,
"coordinatorInstantWithdrawalSignature": null
}
}
}

Auction

Used by the Coordinator to deliver information about who has been greenlit for an auction.
Example Greenlight Message:
{
"channel":"limitOrder",
"type":"auction",
"requestId":82091778811918,
"payload":{
"auctionIdList":[
"0xab29508897ee5a2714fa58705bd834390e8cf9979b5202680c05ca2e4459a05c"
],
"identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
"stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
"takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00",
"greenlit":1,
"bidState":"locked"
}
}

Keep Alive

Used to keep connection alive.
Example Request:
{
"type": "keepAlive"
}

Get Info

Used to retrieve relevant contract addresses.
Example Request:
{
"type": "info",
"requestId": 33684210724642
}

Payment Channels Staking Contract

Structs

StakeCommitment

struct StakeCommitment {
address stakeAddress;
uint256 stakeSpent;
uint256 stakeNonce;
uint256 channelNonce;
bytes data;
bytes stakeAddressSignature;
bytes coordinatorSignature;
}
See Transacting Using the Payment Channel for an explanation of each field.

Methods

getStakerState

function getStakerState(address _stakeAddress) public view returns (
uint256 _stakedAmount,
uint256 _stakeNonce,
uint256 _stakeSpent,
uint256 _channelNonce,
uint256 _withdrawalTimelock
);
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

function stakeCommitmentHash(
address _stakeAddress,
uint256 _stakeSpent,
uint256 _stakeNonce,
uint256 _channelNonce,
bytes memory _data
) public pure returns (bytes32);
Used to calculate the hash of a payment channel commitment for signing.

getCurrentWithdrawalTimelock

function getCurrentWithdrawalTimelock(
address _stakeAddress
) public view returns (uint256);
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

function stake(uint256 _amount) public;
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

function initiateTimelockedWithdrawal(
StakeCommitment memory _commitment
) external;
Used to initiate the timelocked withdrawal process.

executeTimelockedWithdrawal

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

executeInstantWithdrawal

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