Skip to Content
Agents & Automation

Agents and Automation

TL;DR: Self-run agents play from their own wallet; delegated agents act for a user via DelegationHub sessions. The TypeScript Agent SDK (agents/sdk/) provides ready-made loops. See Maintenance & Bots for keeper surfaces.

ClaimRush is permissionless:

  • EOAs and smart contracts can play.
  • Anyone can build bots/agents.

Governance note:

  • ClaimToken and VeClaimNFT are permanent direct roots.
  • MineCore, Furnace, MarketRouter, and ShareholderRoyalties are proxy-backed runtime contracts governed through owned proxy admins.
  • Wiring setters are onlyOwner, governed through the live TimelockController.
  • ClaimToken freezes and renounces ownership during Wire.s.sol; the post-audit freeze-and-burn batch then freezes MineCore, Furnace, VeClaimNFT, and ShareholderRoyalties. None of those wiring locks disable proxy-admin upgrades until the quartet proxy admins are burned.
  • Gameplay is permissionless from day one.
  • Agents should monitor: pause flags, guardian/owner changes, registry token disables, operational allowlist updates, proxy-admin ownership changes, and runtime implementation upgrades.
  • See Security, guardian, pausing.

This page covers:

  • Self-run agents: agent plays from its own wallet.
  • Delegated agents: agent acts for a user address via DelegationHub sessions.

CRAL pack

Machine-readable CRAL companion (runnable manifests and guardrails):

Key manifest IDs (quick map):

  • Install: 10.install
  • Snapshot: 21.snapshot.example
  • Quotes: 23.quote.takeover_with_token
  • Prices: 24.prices.live
  • Events: 30.events.stream, 32.events.backfill.subgraph
  • Harness: 40.harness.run
  • Agent loop: 51.agent.loop.dry_run_once, 52.agent.loop.execute
  • Monitor + durability: 57.agent.monitor, 58.agent.event_cursor
  • Tx reliability: 59.agent.tx_replacement, 59.agent.backoff
  • Private RPC: 55.private_rpc.route, 56.private_rpc.only
  • Auto approvals: 54.agent.auto_approve
  • Achievements: 54.achievements.jsonl
  • Delegation: 61.delegation.create_session.local_demo, 62.delegation.agent_run.once
  • Plans: 71.plan.write, 72.plan.execute
  • Market demo: 74.market.demo.help, 75.market.offer.create.simulate
  • Strategy + replay: 77.strategy.modules, 78.strategy.dev_runner, 79.replay.runner
  • Action coverage audit: 76.action.coverage
  • Subgraph health: 80.subgraph.health
  • Operational guidance: 90.ops.guidance.self_run

Use the Markdown page for explanation. Use the CRAL file for automation.

Repo entrypoints

WhatWhere
Agent tooling rootagents/
TypeScript SDKagents/sdk/
Local manifestsdeployments/<network>.json
ABIsabis/<network>/*.abi.json
Optional snapshot bundlersrc/lens/AgentLens.sol
MineCore takeover quotersrc/MineCoreQuoter.sol
Furnace quoter (heavy view math)src/FurnaceQuoter.sol
Spot swap quoting (DexAdapter + registries)agents/sdk/src/dexQuotes.ts
Live prices helper (CLAIM/ETH + entry tokens)agents/sdk/src/prices.ts
Event cursor (reorg-safe checkpoints)agents/sdk/src/agent/eventCursor.ts
Monitor endpoint (HTTP)agents/sdk/src/agent/monitor.ts
Tx manager + replacementagents/sdk/src/tx/txManager.ts
Backoff / circuit breakeragents/sdk/src/agent/backoff.ts
Strategy plugins + loaderagents/sdk/src/agent/strategies.ts, agents/sdk/src/agent/strategyLoader.ts
Strategy templatesagents/sdk/strategies/
Replay runneragents/sdk/src/agent/replay.ts, agents/sdk/examples/replay.ts
Achievements telemetry (SDK)agents/sdk/src/achievements/
Achievements JSONL schemaagents/sdk/schemas/achievements.v1.schema.json

The SDK is designed for:

  • deterministic inputs (snapshots)
  • event-driven wakeups (JSONL event stream)
  • safe execution (dry-run by default; explicit --execute)

Install

From repo root:

npm -C agents/sdk ci

Read state for decision making

Snapshot API

The SDK exposes getGameStateSnapshot(opts) where opts must include publicClient and manifest; optional fields such as user, abiNetwork, and agentLensAddress refine the snapshot. It returns:

  • meta (chainId, blockNumber, timestamps)
  • addresses (contract addresses from manifest)
  • global (MineCore/Furnace/Royalties/Ve/Market/LP vault/Dex state)
  • optional user slice (balances + claimables + config) when a wallet address is provided

Run the snapshot example:

RPC_URL=http://127.0.0.1:8545 \ USER_ADDRESS=0xYourAgentAddress \ npm -C agents/sdk run example:snapshot

Performance: If AgentLens is deployed and present in the manifest, the snapshot prefers:

  • AgentLens.readGlobalV1()
  • AgentLens.readUserV1(user)

…and falls back to publicClient.multicall() (or sequential reads).

Optional onchain snapshot bundler (AgentLens)

AgentLens is a pure view contract that bundles reads into two calls:

  • readGlobalV1()
  • readUserV1(user)

Local deploys include it in deployments/local.json.

Important wiring note:

  • AgentLens snapshots addresses as constructor immutables. If the canonical bundle is rewired, redeploy AgentLens and refresh the manifest (see Wiring safety model).
  • Local deploy flow deploys AgentLens only after MaintenanceHub exists so the snapshot matches the final bundle.
  • DeployAgentLens.s.sol fails closed if any required input points at a non-contract address, and verifies the supplied addresses resolve to one canonical bundle before deploying.
  • Companion optional modules must be supplied together: MaintenanceHub requires MarketRouter + DexAdapter; LpStakingVault7D and GenesisLPVault24M require DexAdapter; LaunchController requires DexAdapter + GenesisLPVault24M.
  • scripts/verify_deployment.py checks AgentLens immutables exactly against the manifest, including optional 0x0 fields.

Use cases:

  • reduce RPC calls for high-frequency agents
  • reduce “N reads” variance across RPC providers

Quote token takeovers

MineCore.takeoverWithToken(tokenIn, amountIn, minEthOut, maxPrice) requires both a minEthOut slippage guard and a maxPrice guard.

Use the view-only contract MineCoreQuoter (and the SDK helpers) to:

  • validate the allowlisted takeover route for tokenIn
  • compute the expected ETH out for a given amountIn
  • derive a safe minEthOut from a slippage setting

Example (local):

# Default uses wrapped native (WETH) + amountIn = current takeover price RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:takeover-token-quote # Custom token route (token must be enabled in MineCoreEntryTokenRegistry; the EntryTokenRegistry instance wired to MineCore) # AMOUNT_IN is raw base units (example: 1 USDC = 1000000) RPC_URL=http://127.0.0.1:8545 \ TOKEN_IN=0xYourTokenAddress \ AMOUNT_IN=1000000 \ SLIPPAGE_BPS=100 \ npm -C agents/sdk run example:takeover-token-quote

Outputs include:

  • expectedEthOut
  • takeoverPriceAtQuote
  • minEthOut (slippage-adjusted)
  • minEthOutStrict (optional: clamped to never be below takeover price)

Agent rule of thumb:

  • never hardcode a route
  • always compute minEthOut from a quote and an explicit slippage policy

Live prices and swap quotes

Most strategies need spot prices for:

  • CLAIM/ETH (how expensive it is to acquire CLAIM, or what ETH you get back)
  • entry tokens in ETH or CLAIM (to decide between paying with ETH vs token, or whether a token path is economical)

The SDK includes getLivePrices(params) where params must include contracts and publicClient, plus either subgraphUrl for subgraph-backed token discovery or an explicit entryTokens list. It:

  • enumerates enabled entry tokens from the subgraph (EntryTokenConfig)
  • computes spot quotes from onchain reads using the protocol’s DexAdapter.getAmountsOut
  • uses allowlisted routes from the registries (no hardcoded Aerodrome paths)
  • optionally includes the subgraph TokenPricingSnapshot (CLAIM/ETH TWAP + ETH/USD)

Example:

RPC_URL=http://127.0.0.1:8545 \ SUBGRAPH_URL=http://127.0.0.1:8000/subgraphs/name/claimrush/local \ npm -C agents/sdk run example:prices # Optional tuning # MAX_TOKENS=200 (default) # INCLUDE_SUBGRAPH_PRICING=true (default) # Optional: enable in-memory caching + RPC throttling (useful when polling) # PRICES_CACHE=1 # PRICES_RPC_CONCURRENCY=16 # PRICES_QUOTE_TTL_MS=5000 (set 0 to disable quote caching) # PRICES_ENTRYTOKENS_TTL_MS=60000 (entry token enumeration via subgraph) # PRICES_PRICING_TTL_MS=15000 (subgraph pricing snapshot) # PRICES_META_TTL_MS=21600000 (ERC20 metadata) # PRICES_DEX_TTL_MS=300000 (DexAdapter config)

Notes:

  • Cached quotes are for decision support / UI. For tx guardrails (minOut), re-quote immediately before sending.
  • Spot quotes are size-dependent. The default snapshot quotes 1 token (10^decimals) per entry token.
  • Treat subgraph pricing as informational (it can lag). Spot quotes come from onchain reads.
  • In this repo, TokenPricingSnapshot is optional in practice: the subgraph defines the entity shape, but no bundled producer populates live pricing fields by itself. Agents should treat missing or stale snapshot values as normal and fall back to onchain spot quotes.
  • If a token fails to quote, the output includes per-token errors. Agents should treat those tokens as unknown/unsupported.

Listen to events

JSONL event stream

The SDK includes an event streamer that prints one event per line (JSONL).

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:events

Filters:

  • --contracts MineCore,Furnace
  • --events Takeover,FurnaceEnter
  • --from-block 0
  • --poll (HTTP polling fallback)

Optional subgraph backfill

If you have a subgraph endpoint, you can backfill recent history before starting the live RPC stream.

RPC_URL=http://127.0.0.1:8545 \ SUBGRAPH_URL=http://127.0.0.1:8000/subgraphs/name/claimrush/local \ npm -C agents/sdk run example:events -- --backfill --backfill-limit 100

Backfilled events include source: "subgraph" (live RPC events use source: "rpc").

Local simulation harness

Use the harness to run a deterministic “golden path” and write artifacts:

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:harness

Artifacts are written under:

  • agents/sdk/out/harness-<timestamp>/

Live agent loop

The SDK includes a reference live loop:

  • takes snapshots
  • (optionally) listens to events
  • proposes actions
  • can execute transactions if explicitly enabled

Dry-run once:

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:agent -- --once

Execute (sends tx):

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:agent -- --execute

Spending actions are opt-in:

  • --enable-furnace-entry --furnace-eth-in <amount>
  • --enable-takeovers --max-takeover-eth <cap>

Private RPC for takeovers and swaps (optional)

Takeovers and swap-heavy actions are MEV-sensitive. If you operate a private tx endpoint (protected RPC / builder relay), the SDK can route selected transactions there.

Config

  • Env: PRIVATE_RPC_URL, PRIVATE_RPC_MODE=off|route|only
  • CLI: --private-rpc-url, --private-rpc-mode off|route|only

Modes

  • route: send allowlisted actions via PRIVATE_RPC_URL, everything else via RPC_URL
  • only: block execution of non-allowlisted actions (dry-run still works)
  • off: disable private routing (default when PRIVATE_RPC_URL is unset)

Allowlisted actions (v3)

  • Takeovers (MEV-sensitive):
    • mineCore.takeover, mineCore.takeoverFor
    • mineCore.takeoverWithToken
  • Furnace entry (swap-heavy when token-based):
    • furnace.enterWithEth, furnace.enterWithEthFor
    • furnace.enterWithToken, furnace.enterWithTokenFromCallerFor
    • furnace.enterWithClaim, furnace.enterWithClaimFromCallerFor
  • Market exits / fills (swap/quote sensitive):
    • marketRouter.sellLockToFurnace, marketRouter.sellListedLockToFurnace, marketRouter.executeAutoFurnace
  • Royalties lock-mode claim (routes ETH through Furnace):
    • royalties.claimShareholderLock
  • ClaimAllHelper when it performs a Furnace lock:
    • claimAllHelper.claimShareholderForUser, claimAllHelper.claimAllFor when mode=LOCK_FURNACE (1)

Notes

  • Reads and simulations always use RPC_URL (private routing only affects sending).
  • In PRIVATE_RPC_MODE=only, non-allowlisted writes (offers/listings/approvals/config) are blocked. Use route for mixed workloads.
  • Private RPC providers are trusted infrastructure. Use only endpoints you trust.

Example (strict allowlist mode)

RPC_URL=http://127.0.0.1:8545 PRIVATE_RPC_URL=http://127.0.0.1:8545 PRIVATE_RPC_MODE=only npm -C agents/sdk run example:agent -- --execute --enable-takeovers --max-takeover-eth 0.01

Reliability and monitoring

These knobs are optional, but recommended for real unattended bots.

Monitor endpoint (optional)

Expose a local HTTP endpoint with agent health + recent telemetry:

  • Enable: --monitor (or env AGENT_MONITOR_ENABLED=1)
  • Bind: AGENT_MONITOR_HOST=127.0.0.1 (default), AGENT_MONITOR_PORT=8787 (default)
  • Optional auth: AGENT_MONITOR_TOKEN=<secret>
  • Ring size: AGENT_MONITOR_MAX_RECENT=200 (default)

Example:

RPC_URL=http://127.0.0.1:8545 npm -C agents/sdk run example:agent -- --once --monitor curl http://127.0.0.1:8787/health

Durable event cursor (events + reorg safety)

When events are enabled, the agent persists a cursor file:

  • agents/sdk/out/agent-state/<chain>/<chainId>/<agent[-for-user]>/event-cursor.json
  • This includes the last processed block + a recent-key set used to dedupe events across reorgs.
  • On startup, the agent rewinds a small number of blocks and replays deterministically.

Config (env)

  • AGENT_STATE_DIR=<path> (override state root)
  • EVENT_CURSOR_REWIND_BLOCKS=20 (default)
  • EVENT_CURSOR_MAX_KEYS=5000 (default)

Nonce manager + tx replacement (optional)

For MEV-sensitive txs and flaky RPCs, the SDK can manage nonces and fee-bump stuck txs:

  • TX_MANAGE_NONCES=1 (managed nonce allocation + receipt timeout; useful when mixing public + private RPC)
  • TX_REPLACEMENT_ENABLED=1 (implies managed nonces; fee-bump + resubmit stuck txs)
    • TX_REPLACEMENT_TIMEOUT_MS=45000 (receipt timeout; also the per-attempt replacement window when enabled)
    • TX_REPLACEMENT_MAX_ATTEMPTS=3
    • TX_POLL_INTERVAL_MS=1500
    • TX_FEE_BUMP_BPS=12500 (+25% per attempt)

The per-action txs.jsonl file records nonce, attempts, and hashes when replacement is enabled.

Backoff circuit breaker (execute mode)

When --execute is enabled, the runner uses an explicit circuit breaker:

  • Default: enabled (set BACKOFF_ENABLED=0 to disable)
  • Emits achievements: BACKOFF_ENTERED, BACKOFF_CLEARED
  • Config (env):
    • BACKOFF_BASE_MS=1000
    • BACKOFF_MAX_MS=600000
    • BACKOFF_MULTIPLIER=2
    • BACKOFF_MAX_TIMEOUTS=3
    • BACKOFF_MAX_ERRORS=10
    • BACKOFF_RESET_AFTER_MS=600000

Replay + strategy development (offline)

Record ticks in a live run, then replay offline to regression-test decision-making:

  • Record: WRITE_TICK_RECORDS=1 (live agent)
  • Replay: npm -C agents/sdk run example:replay -- --run-dir agents/sdk/out/agent-<timestamp> --compare --pretty
  • Strategy modules:
    • Load into the live agent: --strategy-module ./path/to/strategy.mjs
    • Example: npm -C agents/sdk run example:agent -- --strategy-module ./my-strategy.mjs
    • Or via env: STRATEGY_MODULES=./a.mjs,./b.mjs
    • Templates live in agents/sdk/strategies/
  • Fast iteration: npm -C agents/sdk run example:strategy -- --run-dir ... --strategy-module ... --pretty

Achievements telemetry

The SDK writes a compact JSONL telemetry stream in two modes:

  • Live agent: agents/sdk/out/agent-<timestamp>/achievements.jsonl
  • Plan executor: agents/sdk/out/execute-plan-<timestamp>/achievements.jsonl

Use this for:

  • dashboards / alerting / postmortems
  • third-party analytics pipelines that subscribe to agent telemetry
  • feeding an external AI a compressed “what happened recently” context window

The JSON Schema lives at:

  • agents/sdk/schemas/achievements.v1.schema.json

Per-kind data payloads are documented in the schema’s $defs/AchievementData discriminated union. Subscribe to this schema rather than reverse-engineering the emitter.

Format

  • each line is an Achievement object with:
    • ts (ms since unix epoch)
    • kind (string enum — see schema for full list)
    • level (info | warn | error)
    • optional context: chain, chainId, agent, user, blockNumber, txHash, data

Achievement kinds (v1)

  • Value milestones:
    • TAKEOVER_SUCCESS
    • REIGN_REWARD_COLLECTED
    • FURNACE_LOCK_CREATED
    • ROYALTIES_CLAIMED
    • AUTOCOMPOUND_EXECUTED
  • Frontend profile badges (optional):
    • BADGE_UNLOCKED
  • Safety/ops:
    • SLIPPAGE_GUARD_TRIGGERED
    • SESSION_EXPIRED
    • PAUSED_ACTION_SKIPPED
    • REVERTED_TX
    • RPC_LAG_DETECTED
    • SUBGRAPH_LAG_DETECTED
  • Optional scoring:
    • ACTION_UTILITY (only if EMIT_ACTION_UTILITY=1)

Frontend badge polling (optional)

  • Set ACHIEVEMENTS_BASE_URL=<url> to enable (works in both the live agent and the plan executor).
  • The agent polls: {ACHIEVEMENTS_BASE_URL}/api/achievements?address=<user>&chainId=<chainId>.
  • Supported chain ids: 8453 (Base), 84532 (Base sepolia), 31337 (local Anvil).
  • First successful poll initializes a baseline and emits nothing.
  • After a confirmed onchain tx, the agent requests a one-shot refresh (debounced, refresh=1).
  • Badge definitions are ported from the frontend into agents/sdk/src/achievements/profileBadges.ts (delegation-only badges excluded).

Tuning (env)

  • ACHIEVEMENTS_POLL_MS=20000 (default)
  • ACHIEVEMENTS_REFRESH_COOLDOWN_MS=5000 (default)
  • ACHIEVEMENTS_TIMEOUT_MS=10000 (default)

Notes

  • Treat data as versioned/best-effort. Use kind and level as stable keys.
  • The public JSON Schema (achievements.v1.schema.json) documents every data payload shape per kind. Third-party dashboards should validate against this schema.
  • Achievements are telemetry and reward hooks, not an objective to “farm”.

Delegated agents

Delegated agents run from the bot’s wallet, but act for a user address via DelegationHub sessions.

High-level model:

  • User grants a session: (delegate, perms, expiry).
  • Bot submits txs from its own address (pays gas and any ETH/CLAIM spend), calling delegated protocol entry points.
  • Protocol contracts resolve their canonical auth roots onchain and then verify the session via DelegationHub.isAuthorized(...). Do not assume a raw stored delegationHub pointer is trusted in isolation.

Create or refresh a session

In production, the user signature should come from their wallet (EOA) or an EIP-1271 smart wallet.

Local demo (actor0=user, actor1=delegate):

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:delegation

Run the live agent for a user

Use --acting-for to switch the agent into delegated mode.

# run the delegate (actor1) but act for the user address RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:agent -- --actor-index 1 --acting-for 0xUserAddress --once # execute (sends tx) RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:agent -- --actor-index 1 --acting-for 0xUserAddress --execute

Notes:

  • Strategy flags like --enable-furnace-entry / --enable-takeovers still apply, but the SDK will prefer delegated entry points when --acting-for is set.
  • The session must include the required permission bits for each action (see Bot sessions (DelegationHub)).

Delegated smoke test harness

The harness includes a small delegated scenario:

RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:harness -- --scenario delegated

This performs:

  • DelegationHub.setSessionBySig (user signs, delegate submits)
  • Furnace.enterWithEthFor(user, ...) (delegate pays, user receives ve)
  • MineCore.takeoverFor(user, maxPrice) (delegate pays, user becomes King)

Plan format for external AI

If you want an external AI system to decide actions, use AgentPlan v1:

  • example:plan writes a plan JSON file
  • example:execute-plan simulates or executes a plan
RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:plan -- --out /tmp/agent-plan.json --pretty RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:execute-plan -- --plan /tmp/agent-plan.json # Optional: emit achievements.jsonl (and poll frontend badges) ACHIEVEMENTS_BASE_URL=http://127.0.0.1:3000 \ npm -C agents/sdk run example:execute-plan -- --plan /tmp/agent-plan.json --execute

Tip: the same knobs are also available as CLI flags (see --help):

  • --achievements-base-url
  • --achievements-poll-ms
  • --achievements-refresh-cooldown-ms
  • --achievements-timeout-ms

Market actions (offers, listings, sells) are expressed as plan actions too:

# Show available commands RPC_URL=http://127.0.0.1:8545 \ npm -C agents/sdk run example:market -- --help # Example: create an offer (simulated) RPC_URL=http://127.0.0.1:8545 TARGET_BONUS_BPS=2500 BUDGET_CLAIM=1000000000000000000 DURATION_DAYS=30 \ npm -C agents/sdk run example:market -- --cmd offer-create

Delegated mode: add --acting-for 0xUserAddress to example:plan so the plan targets a user identity (and uses delegated entry points when executed).

The JSON Schema lives at:

  • agents/sdk/schemas/agent-plan.v1.schema.json

Action coverage (AgentPlan v1)

The SDK executor covers (nearly) the full gameplay surface for self-run agents:

  • MineCore
    • Takeovers: mineCore.takeover, mineCore.takeoverWithToken
    • Config: mineCore.setCurrentReignRecipients, mineCore.setKingAutoLockConfig
    • Withdrawals: mineCore.withdrawKingBalance, mineCore.withdrawRefundBalance
  • Furnace
    • Entry: furnace.enterWithEth, furnace.enterWithClaim, furnace.enterWithToken
  • ShareholderRoyalties
    • Claims: royalties.claimShareholderEth, royalties.claimShareholderLock
    • Config: royalties.setAutoCompoundConfig
  • MarketRouter
    • Listings: marketRouter.listLock, marketRouter.delistLock, marketRouter.cancelExpiredListing
    • Offers: marketRouter.createBonusTargetEscrowWithTarget, marketRouter.cancelBonusTargetEscrow, marketRouter.extendBonusTargetEscrowExpiry, marketRouter.cancelExpiredBonusTargetEscrow, marketRouter.executeAutoFurnace
    • Exits: marketRouter.sellLockToFurnace, marketRouter.sellListedLockToFurnace
  • VeClaimNFT (veCLAIM positions)
    • Maintenance: furnace.extendWithBonus, furnace.extendWithBonusFor, ve.mergeLocks, ve.unlock, ve.setAutoMax
    • Checkpoints: ve.checkpointGlobalState, ve.checkpointTotalVe
  • Approvals
    • ERC20: erc20.approve, erc20.ensureAllowance
    • veNFT: ve.approve, ve.setApprovalForAll

Auto approvals

For unattended operation, the agent can automatically insert the required ERC20 and veNFT approval actions ahead of swap/takeover/market actions.

Enable (env vars)

  • AUTO_APPROVE_ENABLED=1
  • AUTO_APPROVE_MODE=exact|max (default: exact)
  • AUTO_APPROVE_NFT=0|1 (default: 1)

Notes

  • Auto approvals are inserted only when executing transactions (dry-run does not send approvals).
  • Not compatible with PRIVATE_RPC_MODE=only (approval txs are blocked). Pre-approve, or use PRIVATE_RPC_MODE=route.
  • veNFT auto approvals use per-tokenId approve (not setApprovalForAll) for safety.

Delegated mode adds ...For(user) action variants where the protocol exposes them, plus safe account-management actions (auto-compound configs and ve maintenance).

Canonical source of truth:

  • agents/sdk/schemas/agent-plan.v1.schema.json (action enum + field set)

Subgraph health and core/event-discoverable address parity

Before relying on subgraph data in production, validate:

  • indexing lag vs RPC head
  • core/event-discoverable protocol contract address parity vs current manifest
RPC_URL=... \ SUBGRAPH_URL=... \ npm -C agents/sdk run example:subgraph-health -- --pretty

Operational guidance

For self-run agents:

  • Use a dedicated wallet (separate from treasury / cold storage).
  • Always cap spend (maxTakeoverEth, max actions per cycle).
  • Always include slippage floors and deadlines.
  • Treat MineCore contention reverts as normal; re-quote right before send.
  • Log everything (snapshots, decisions, tx hashes, reverts).

For delegated agents:

  • Prefer short session expiries (hours, not days) to limit user exposure.
  • Re-check session validity before executing; user may revoke mid-cycle.
  • Track permission bits required per action type (see Bot sessions).
  • Separate spend accounting: bot pays gas and ETH/CLAIM, user receives benefits.
  • Log the user address (--acting-for) with every action for audit trails.
  • Handle EIP-1271 smart wallet signatures in production (not just EOA).
  • Monitor for session expiry approaching; prompt user to refresh proactively.

See also