LongbowDocs
Launch App
OverviewGetting StartedContracts & ABIIntegration GuideHTTP APIERC-8056 Stock StandardLiquidity & ReservesKeeper Node GuideError Codes & DebuggingFAQ & Risks

Keeper Node Guide

Keepers are independent off-chain bot nodes that poll active orders, check trigger criteria using Chainlink price feeds, and call executeOrder to close swaps.

Why it is permissionless

In Longbow, the keeper is a convenience layer, not a central authority. Anyone can run a keeper bot. The LongbowExecutor contract verifies all execution conditions on-chain: the current Chainlink oracle price, feed timestamps, reentrancy guards, and slippage.

If a malicious keeper tries to trigger an order before the price feed crosses the user's limit, the contract's internal assertion checks fail, and the transaction reverts immediately.

The Loop Logic

A keeper bot polls the database or graph mirror of active orders, then runs a checking loop:

keeper-loop.ts
import { ethers } from "ethers";

// ABI snippet for checking and executing orders
const EXECUTOR_ABI = [
  "function canExecute(uint256 id) external view returns (bool ok, string memory reason)",
  "function executeOrder(uint256 id, address[] calldata path) external returns (uint256 amountOut)",
];

async function checkAndFillOrders(executorContract, activeOrderIds) {
  for (const id of activeOrderIds) {
    try {
      // 1 — Check if order criteria holds on-chain (static call)
      const [canFill, reason] = await executorContract.canExecute(id);
      
      if (canFill) {
        console.log(`Order #${id} is triggerable! Executing transaction...`);
        
        // 2 — Execute on-chain (will pull tokens and swap via Uniswap V2 router)
        // Path should be [tokenIn, USDG] or [USDG, tokenOut]
        const path = getExecutionPath(id); 
        
        const tx = await executorContract.executeOrder(id, path, {
          gasLimit: 300_000, // Safe maximum on Robinhood Chain L2
        });
        
        const receipt = await tx.wait();
        console.log(`Order #${id} successfully executed in block ${receipt.blockNumber}!`);
      } else {
        console.log(`Order #${id} cannot be executed: ${reason}`);
      }
    } catch (err) {
      console.error(`Failed evaluation/execution for order #${id}:`, err.message);
    }
  }
}

Keeper Incentives

Keepers incur L2 gas costs when submitting execution transactions. To incentivize keepers, executions include a small tip (retained from the output swap tokens or charged as a minor premium). On Robinhood Chain, gas costs are extremely low (fractions of a cent), meaning even small tips provide healthy profit margins for keeper operators.

Deployment & Running

The repository includes a ready-to-run keeper package inside apps/keeper. You can deploy it locally or on a VPS (Ubuntu/Debian) using PM2 for process monitoring:

ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'longbow-keeper',
      script: 'packages/keeper/index.js',
      instances: 1,
      autorestart: true,
      watch: false,
      env: {
        NODE_ENV: 'production',
        USE_MOCKS: 'false',
        KEEPER_PRIVATE_KEY: '0x...',
        RPC_URL: 'https://rpc.mainnet.chain.robinhood.com',
        EXECUTOR_ADDRESS: '0x8bce...'
      }
    }
  ]
};

Troubleshooting Keepers

  • High Rejection Rates — If a transaction is submitted but reverts, another keeper might have beat you to it in the same block, or the price slipped back below the threshold.
  • Insufficent Balance — Ensure the keeper's private key account is funded with Robinhood Chain native ETH to cover gas fees.