Architecture

Two entry points. One deterministic engine. Every intent flows through the same pipeline regardless of whether it arrives via CLI, API, or chat.

Pipeline

CLI build command
$ defi-skills build \ --action aave_supply \ --args '{"asset":"USDC","amount":"500"}'
or
API POST /v1/build
{ "action": "aave_supply", "arguments": { "asset": "USDC", "amount": "500" }, "from_address": "0x..." }
action + human-readable args
STAGE 1 build_payload()

Iterates payload_args from the playbook in order. Dispatches each to a resolver by its source field. Resolvers convert human-readable values to on-chain values.

Core Resolvers
  • token_address (symbol to checksum address)
  • amount (human to Wei with decimals)
  • ens_or_hex (ENS name to address)
  • fee_tier (auto-detect from pair)
  • deadline (timestamp + buffer)
  • amount_or_balance ("max" to balanceOf)
Protocol Resolvers
  • Uniswap quotes + tick ranges
  • Balancer pool IDs + swap limits
  • Curve min amounts + pool math
  • EigenLayer strategies + deposits
  • Lido withdrawal requests + hints
  • Aave reward asset discovery
ExecutablePayload (resolved args)
STAGE 2 encode_tx()

Loads ABI by function selector. Maps resolved values to ABI parameters via param_mapping. Coerces types (address, uint256, bytes). Encodes calldata via eth_abi.encode.

USDC → 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 500 → 500000000 (6 decimals) ABI → supply(address,uint256,address,uint16) data → 0x617ba037000000000000000000000000a0b86991...
OUTPUT Ordered Transaction Array

[approval txs] then [action tx]. Unsigned. EIP-55 checksummed. Never signs.

{ "chain_id": 1, "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2", "value": "0", "data": "0x617ba037..." }

Data layer

All local. No runtime fetches to populate. The engine reads these at init and uses them during resolution.

JSON
12 Playbooks
Action specs, contracts, param mappings, approvals. One file per protocol.
ABI
ABI Cache
Etherscan-verified ABIs. Fetched once offline via fetch_abis.
TOK
Token Cache
Symbol to address + decimals. Immutable on-chain data. Auto-updates on new tokens.
REG
Registry
Governance-mutable state. EigenLayer strategies, Compound tokens. Manual refresh.

External services

Called only during resolution, not at init. All optional depending on the action.

Alchemy RPC
Balances, decimals, ENS, quotes
Etherscan
ABI fetching, proxy detection (offline only)
1inch
Token discovery, fallback symbol lookup
The Graph
Balancer pool IDs

Agent layer (optional)

The chat command and API sessions add an LLM agent on top. The agent uses tool calling to discover actions, check parameters, and invoke the deterministic engine. It never touches the engine internals.

AGENT LLM Tool-Calling Loop
Tools Available
  • list_actions -- discover protocols
  • action_info -- check parameters
  • build_transaction -- invoke engine
Flow
  • User sends intent in natural language
  • Agent identifies action, calls action_info
  • Agent calls build_transaction with correct args
  • Returns unsigned tx to user

Roadmap

CURRENT

Phase 1: CLI + Bundled API

Open-source CLI with deterministic build and chat commands. Hosted API bundles both the agent and engine. API key auth with rate limiting (free: 50/day).

NEXT

Phase 2: Agent Layer (Planning + Search)

Structured protocol registry with live data from DeFiLlama. Search tools replace LLM knowledge for protocol discovery. Agent becomes a search interface over curated data, not an advisor. Benchmarkable at every step.

FUTURE

Phase 3: Multi-Chain + Community Playbooks

L2 support (Arbitrum, Optimism, Base). Community-contributed playbooks with verification pipeline. TypeScript SDK. Portfolio awareness and position management.