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
13 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

Future Roadmap: Help Us Shape It

NOW

What's Live Today

Open-source CLI and hosted API with 13 protocol playbooks across 6 chains (Ethereum, Arbitrum, Base, Optimism, Polygon, Sepolia). Deterministic transaction building, conversational agent, API key auth with rate limiting.

POSSIBLE PATHS

Where This Could Go

These are directions we're exploring. Community input will shape what comes next:

  • Expanded multi-chain coverage beyond the current 6 supported networks
  • Community-contributed playbooks with a verification pipeline
  • Smarter agent layer with protocol search and live on-chain data
  • SDK for frontend integrations
CONTRIBUTE

Build With Us

defi-skills is open source. Add a new protocol by writing a JSON playbook. Propose new directions via GitHub issues. The roadmap is yours to shape.