harb/services/txnBot/AGENTS.md

<!-- last-reviewed: 209e0c798ea85204c5fe466ba7b54b874095e08f -->
# 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.
chore: gardener housekeeping 2026-03-23 AGENTS.md watermarks refreshed to HEAD (209e0c7). Key content updates: - root AGENTS.md: added packages/analytics/ to directory map - landing/AGENTS.md: documented @harb/analytics integration and Umami funnel tracking - web-app/AGENTS.md: documented analytics events (wallet_connect, swap_initiated, stake_created) - onchain/AGENTS.md: documented AttackRunner fixes (taxRate as index, vm.warp, same-broadcast recenter), 2000-trade floor-ratchet evidence Pending actions (6): promote #1083 and #1086 to backlog, unblock #1099. 2026-03-23 18:07:12 +00:00			`<!-- last-reviewed: 209e0c798ea85204c5fe466ba7b54b874095e08f -->`
fix agent 2025-09-24 09:57:20 +02:00			`# 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`.
fix/podman-postgres-integration (#37) resolves #25 Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: johba <johba@harb.eth> Reviewed-on: https://codeberg.org/johba/harb/pulls/37 2025-10-01 20:26:49 +02:00			- 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.
fix agent 2025-09-24 09:57:20 +02:00
			`## Configuration`
			`Set the following environment variables (automatically generated when the stack script is used):`
			```
fix: txnBot AGENTS.md ENVIRONMENT enum is stale (#784) 2026-03-15 08:57:15 +00:00			`ENVIRONMENT=BASE_SEPOLIA_LOCAL_FORK\|BASE_MAINNET_LOCAL_FORK\|BASE_SEPOLIA\|BASE`
fix agent 2025-09-24 09:57:20 +02:00			`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`
health checks (#39) resolves #35 Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: johba <johba@harb.eth> Reviewed-on: https://codeberg.org/johba/harb/pulls/39 2025-10-02 14:37:59 +02:00			- Launch via `nohup ./scripts/dev.sh start &`; the script handles env injection and process supervision.
fix agent 2025-09-24 09:57:20 +02:00			- 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.`