Keeper Integration Guide
Integrating your trading bot with Rook enables you to capture profit while providing fundamental infrastructure for Rook product users.
Make sure you've read the following pages first before proceeding
Now that you understand the basic high-level architecture and the concept of Keeper addresses, you may begin the integration procedure.
These are the steps required to integrate your trading operation with Rook as a Keeper.
- KeeperIdentityAddress, KeeperStakeAddress(s), KeeperTakerAddress(s).
- Generate your KIA, contact Rook, and submit this address to us to be registered. Once the KIA is registered, you can then make API calls to the Coordinator to register your KSAs and KTAs.
- Obtain your API key from Rook, this can be done once your KIA is registered. You will need this key to access the Coordinator.
- You must register both your EOAs and your trading smart contracts as KTAs. In other words, for every trade you perform you must have KTAs registered for your taker address and your txOrigin address. If you're trading with a smart contract, you need both. If you're trading with an EOA only, you only need your EOA.
- Integrate your bot with the Coordinator's HTTP server.
- You'll need this to make calls to get your payment channel state and other general information about the Coordinator.
- Integrate your bot with the Coordinator's WebSocket server.
- You'll use this to make bids and monitor auction progress in real-time.
- While connected, call the keepAlive WebSocket API frequently based on the documentation so the coordinator knows you're connected. Failure to call the keepAlive endpoint within the timeout period will result in your connection being terminated.
- Make sure your WebSocket connection is set to auto-reconnect upon disconnect. That way if your bot loses internet or for some reason drops the connection with the Coordinator, it can automatically re-connect.
- Automate the process of calling these APIs every time your bot starts up. That way when you add more addresses they can be automatically registered.
- Our backend service will automatically whitelist your taker addresses with our trading protocol. You will not have to pay gas to perform that whitelist yourself.
- Acquire and stake ROOK on the Coordinator Staking contract. These addresses can be found in the Contracts Registry.
- Acquire ROOK tokens to stake on the staking contract, this ROOK will be used as bidding power to capture MEV.
- Stake your ROOK on the staking contract calling the
stake()function from your KSA. You can automate this from your bot, call it directly from Etherscan, or call it directly from our web app.
- Finding MEV and placing a bid.
- Take your trading bot exactly as is, and make this change to it. When it's finding MEV, and that MEV involves filling an order or liquidating a position in Rook, do not just immediately fill or liquidate. Instead, you must first place your bid with the Coordinator to perform that action.
- The Coordinator will receive the bid and quickly start an auction. You will supply a
requestIdwith your bid. Keep this, you'll need it later. - The Coordinator will reply with the result. You simply monitor your WebSocket connection for a greenlight message. When you receive the message, you can verify that you've been greenlit by doing the following:
- Confirm that the message payload's
requestIdmatches the one that you sent in your bid. - Confirm that the KIA, KSA, and KTA match you.
- Confirm that the message payload's
greenlitproperty shows a win.
- If you've been greenlit, you can then resume the MEV capture process and execute the order fill or liquidation.
- All of these steps will happen very quickly.
- Broadcasting your transaction.
- Once you've been greenlit, you're free to capture that MEV any way you'd like. This may involve Ethereum's public mempool, direct to miner, Flashbots, MiningDAO, etc. Use any means to include your transaction in the blockchain.
- Block number deadline.
- Each auction will have a block number deadline which represents the highest block in which this transaction is allowed to mine into. This is essentially a time limit for the Keeper to perform their action. In order to make a good reputation mark (or RepMark) on the auction, the Keeper must get their action complete within that deadline. If the action is either not completed or completed after that deadline, the Keeper will receive a bad RepMark.
- We highly recommend that you either build in a block number deadline protection mechanism to your smart contract or lean on a protocol that already uses one, like Flashbots.
- Example A) Your smart contract should say
if blockNumber > deadline: revert - Example B) Broadcast your tx to Flashbots only for block numbers:
deadline,deadline - 1,deadline - 2, etc. But NOT fordeadline + 1because that would result in a bad RepMark for being late.
- Periodically request refunds
- When a Keeper bids and fails, your bid remains spent on the payment channel. A refund is issued for all genuinely good failure cases.
- Critical
- Because claiming a refund will increment your
stakeNonce, it's important to acknowledge the possibility of a race condition for the Keeper that may impact their ability to trade unless properly handled. We recommend submitting refunds when trading activity is low, between trades, or during a few-second period when you believe you will not be submitting a bid through the payment channel. If you simultaneously submit a bid and a refund, they could end up attempting to use the same nonce. And if that happens, one of them will succeed and the other will fail. If your bid succeeds and the refund fails, that would be okay because you can simply re-submit the refund later. But if the refund succeeds and the bid fails, that would be bad because you're losing out of a profit opportunity just to claim a refund that you could have claimed later.
- TODO Create a refunds section
Keepers should be generating Ethereum signatures when signing commitment hashes. This involves prefixing the Ethereum signature header to commitment hashes as shown below and signing the result.
ethsigned_message = keccak_256(b'\x19Ethereum Signed Message:\n32' + commitment_hash_bytes)
Last modified 11mo ago