harb/services/txnBot/AGENTS.md

Transaction Bot - Agent Guide

Automation service that maintains liquidity alignment and tax enforcement for the KRAIKEN protocol.

Responsibilities

• Monitor Ponder GraphQL metrics to detect when recenter() should be triggered.
• Track staking positions for overdue taxes and call payTax() when profitable.
• Expose a status endpoint (GET /status) for operational visibility.

Architecture

• service.js - Main loop that polls the GraphQL endpoint, evaluates triggers, and submits transactions.
• generateKey.js - Utility for provisioning dedicated bot wallets.
• package.json scripts - npm install, npm start, and debug runs via DEBUG=* npm start.
• ES Module: This service uses "type": "module" and imports kraiken-lib as an ES module. All imports use ES module syntax (import instead of require()).
• Node.js Compatibility: Requires Node.js ≥14 with ES module support. The __dirname and __filename globals are not available; use import.meta.url with fileURLToPath() instead.

Configuration

Set the following environment variables (automatically generated when the stack script is used):

ENVIRONMENT=BASE_SEPOLIA_LOCAL_FORK|BASE_MAINNET_LOCAL_FORK|BASE_SEPOLIA|BASE
PROVIDER_URL=<rpc-url>
PRIVATE_KEY=<hex-private-key>
LM_CONTRACT_ADDRESS=<liquidity-manager-address>
STAKE_CONTRACT_ADDRESS=<stake-contract-address>
GRAPHQL_ENDPOINT=<ponder-graphql-url>
# Optional: PORT=43069

Operations

• Launch via nohup ./scripts/dev.sh start &; the script handles env injection and process supervision.
• For focused debugging, run npm install then npm start within services/txnBot/ after the stack is already up.
• Monitor logs for transaction receipts and ensure gas pricing stays within acceptable bounds.

Safety Checklist

• Use dedicated wallets and keep balances minimal.
• Rotate keys if compromise is suspected; update secrets before restarting the stack.
• Observe exponential backoff behaviour and avoid hammering RPC endpoints on failure.