Overview
Theank-agents module provides scaffolding for agent-based market (ABM) simulations in ANK.
Key features:
- Pure planning architecture (agents propose, engine executes)
- Deterministic tie-breaking for reproducible results
- Built-in block builder (MEV-style transaction ordering)
- Pre-built agent types: noise traders, arbitrageurs, sandwich bots
- Pure planning: Agents only propose transactions. State changes happen when the engine executes the produced bundles.
- Determinism: Plans are stamped with
(agent_idx, seq)for consistent tie-breaking across runs. - Safety: A per-agent cap (
MAX_PLANS_PER_AGENT = 64) prevents flooding a tick.
Core Types
WorldView
A read-only snapshot of the world for agents to reason over.Fields
Protocol id → protocol-level market view (free-shape JSON).Each protocol’s
view_market() returns a custom JSON structure describing market state.UserId → on-engine wallet balances (e18).Maps user IDs to their token balances (all amounts in 1e18 scale).Methods
Build a
WorldView from the current engine state (cheap clone of views and portfolios).PlannedTx
A planned transaction with scheduling metadata used by block builders.Fields
The user on whose behalf this tx will execute.
The concrete tx (target protocol + action).
Higher
priority executes earlier (after gas bid).Simple stand-in for a “gas bid” used by builders to sort.
Methods
Construct a new planned transaction.
Traits
Agent
Trait implemented by any agent that can observe the world and produce a set of planned transactions each ABM tick.Methods
A short, stable name for logging/metrics.
One-time initialization hook (e.g., pre-compute handles).Default: Does nothing (returns
Ok(()))Run once every N ticks.Default:
1 (every tick)Plan transactions for the current tick. The engine executes the returned txs if they pass fees/risk policies.
BlockBuilder
Block builder abstraction: takes a pool of planned txs and returns per-user bundles. Builders decide ordering (e.g., by gas bid / priority) and how to group txs into bundles submitted to the engine.Methods
Build bundles for this tick from a set of planned transactions.
AbmRunner
Coordinates all agents with the engine. One “global tick”:- All agents observe the same
WorldView - Produce planned txs
- Builder assembles per-user bundles
- Engine executes all bundles at the same timestamp
Fields
Registered agents participating in the market.
Current block builder implementation (MEV policy).
Methods
Create an empty runner with
MevBlockBuilder as default builder.Replace the block builder.
Register an agent.
Initialize all agents once (called before the first tick).
Run one ABM tick: all agents act at the same timestamp.
Built-in Block Builders
MevBlockBuilder
A simple builder that sorts by:(gas_bid DESC, priority DESC, agent_idx ASC, seq ASC), then preserves per-user order when forming bundles.
Sorting logic:
- Higher
gas_bidfirst (MEV auction) - Higher
prioritywithin same gas bid - Lower
agent_idxfor deterministic tie-breaking - Lower
seqfor transaction order within agent
Built-in Agents
NoiseTraderAgent
A lightweight “noise trader” agent that submits periodic swaps to a DEX.Fields
User on whose behalf the trades are executed.
Target DEX protocol id (e.g.,
"uniswap-v3").Mean notional (1e18) for each swap.
Behavior
- Alternates trade direction each tick (deterministic)
- Creates one swap per tick
- Priority:
0, Gas bid:1
DexArbAgent
Try to close price gaps across two DEX markets (very simplified).Fields
User executing the arbitrage.
First DEX id (e.g.,
"uniswap-v3").Second DEX id.
If
abs(rel_gap) exceeds this threshold in bps, attempt a two-leg trade.Behavior
- Reads
mid_e18price from both DEX market views - Calculates relative price gap in basis points
- If gap exceeds threshold, submits buy + sell trades
- Priority:
5, Gas bid:5
SandwichBot
A super-light “sandwich bot” stub: front-run + back-run with higher gas.Fields
User on whose behalf the sandwich is executed.
Target DEX protocol id.
Behavior
- Creates two transactions per tick:
- Front-run: Priority
10, Gas bid100 - Back-run: Priority
-10, Gas bid100
- Front-run: Priority
- Amount:
0.5e18per leg
DEX Action Helpers
Strongly-typed helpers for building common DEX actions (avoid free-form JSON typos).swap_exact_in
Create aswap_exact_in action.
Signature:
Trade direction flag (token0 → token1).
Input amount (1e18 scale).
Minimum acceptable output amount (slippage guard).
Usage Examples
Basic ABM setup
Custom agent implementation
Custom block builder
Reading portfolio state in agents
Multi-agent coordination
Design Notes
Determinism
All agent logic is deterministic when:- Using deterministic RNG (seeded from
ctx.step_idx) - Avoiding system time / external I/O
- Reading from immutable
WorldView
Per-Agent Cap
MAX_PLANS_PER_AGENT = 64 prevents any single agent from flooding the mempool. If an agent returns more than 64 planned transactions, the list is truncated.
Execution Model
- Observation: All agents receive the same
WorldViewsnapshot - Planning: Agents independently produce
PlannedTxvectors - Building: Block builder sorts/groups transactions
- Execution: Engine executes all bundles at the same timestamp
Block Builder Semantics
MevBlockBuilder sort order:- gas_bid: Simulates MEV auction (highest bidder first)
- priority: User-defined urgency
- agent_idx: Deterministic tie-breaker
- seq: Preserves transaction order within agent
Gas Limits
Agents can setgas_limit on transactions. The engine may reject transactions exceeding available gas (if gas accounting is enabled).
Future Extensions
Theank-agents module is designed for extensibility:
- More agent types: Liquidators, rebalancers, governance bots
- Advanced builders: PBS-style separation, private order flow
- Machine learning: RL agents trained on historical data
- Multi-market: Agents operating across multiple protocols