ava-4.0

# Ava

**The execution layer for agents that do DeFi.**

Your AI agent can ship an app, run research, book a flight, buy a thing. Ask
it to supply 300 USDC to Morpho on Base and bridge the rest to Avalanche, and
you get an explanation, maybe some code, and no transaction. Asked directly,
Claude answers: *"No. No wallet, no signer, no RPC."*

Ava is the part that can.

```
"Supply 300 USDC to Morpho on Base, bridge no more than 200 to Avalanche,
 then supply what arrives to Aave"

  leg_1  lend    base                morpho   USDC  300
  leg_2  bridge  base -> avalanche   bridge   USDC  max 200
  leg_3  lend    avalanche           aave     USDC  amount from leg_2
```

Three dependent actions from one sentence. `leg_3` waits for `leg_2` and
supplies the amount the bridge **actually delivered**, not the 200 that was
requested, because a bridge delivers less than it accepts and a number chosen
at planning time is wrong by exactly the fee.

**New here?** Jump to [Onboarding](#onboarding). It is a verified first hour:
setup, the one trap that breaks a fresh clone, and the house rules that exist
because ignoring them shipped a bug.

## Confirmed on mainnet

Ava built the calldata, signed it with its own Turnkey key, broadcast it, and
the chain confirmed it. The canonical list is `apps/site/src/lib/settlements.ts`,
and `apps/site/scripts/verify-settlements.mjs` re-reads every row from a public
node before the site is allowed to build. Last run 2026-08-18, all seven matched:

| Chain | Venue | Transaction | Block |
|---|---|---|---|
| Base | Morpho gtUSDCp | [`0x97b78540…36bbba`](https://basescan.org/tx/0x97b78540cd233446b83fffacbdf7ab7e514446f914268c1fae14d5429e36bbba) | 49315911 |
| Base | Morpho gtUSDCp | [`0xce4109e4…6b0a7f`](https://basescan.org/tx/0xce4109e49eaa780588d0569c8886211132eee12377a1d16f22ba8b6d176b0a7f) | 49327027 |
| Avalanche | Aave v3 | [`0x12990c11…f4209f`](https://snowtrace.io/tx/0x12990c11b1e8a7a7eff5e594823669a6778d2a6886474d29d7f5cf450bf4209f) | 92231544 |
| BNB Chain | Aave v3 | [`0x7737cf5c…08b9de`](https://bscscan.com/tx/0x7737cf5cb76d1d4ac8e39f3ea4098a173534c259fb854dbc7ac991872608b9de) | 114508635 |
| Monad | Aave v3 | [`0x50940c95…8715cf`](https://monadexplorer.com/tx/0x50940c9510bef0cb595ecaf2b40d57d4cfa04227b6568ded4ea0541abd8715cf) | 92954146 |
| Monad | Aave v3 | [`0x1b23c35d…628af7`](https://monadexplorer.com/tx/0x1b23c35d5c7c58746961777fdc9eb468823be549a3784869ff0d71b326628af7) | 93291520 |
| BNB Chain | SushiSwap via LI.FI | [`0x14850931…de0542`](https://bscscan.com/tx/0x14850931f8eb6a8adb1687d3065396bb26c297ad2d321fadfe59b1e73ede0542) | 114518492 |

The two BNB rows were previously transposed here: `0x14850931…` was labelled
Aave v3 when its `to` is the LI.FI diamond, and `0x7737cf5c…` was labelled a
LI.FI swap when its `to` is the Aave v3 pool. `settlements.ts` was corrected and
this table was not, which is why the verifier now reads from that one source.

A mainnet proof shows a path executed once. It is not a claim that the route is
ready for unattended capital, and this repository never treats it as one.

## Two ways to authorize

**One-shot.** The user is present, sees the exact plan, signs it.

**Standing.** The user is asleep. "Every hour rotate my USDC into the best yield
on Base using Aave and Morpho, never more than 200 per rotation, never over
1000 total, stop after 30 days." They sign the **bounds** once over EIP-712, and
every later rotation is checked by code rather than by a human. Editing any
limit after signing breaks the signature.

Asking a human at every rotation would defeat the product. Relaxing the check
would defeat the point.

## Try it in one call

```bash
curl -sX POST https://api.getava.xyz/v1/users/session \
  -H 'content-type: application/json' -d '{}'
```

No CAPTCHA, no email, no wallet popup. Then connect a coding agent over MCP:

```bash
claude mcp add --transport http ava https://api.getava.xyz/mcp \
  --header "Authorization: Bearer <token>"
```

Codex, Cursor and Grok setups are at [getava.xyz/install](https://www.getava.xyz/install).
Machine-readable summary at [getava.xyz/llms.txt](https://www.getava.xyz/llms.txt).

## Live routes

Five lending routes are callable through the authenticated API today: Morpho
Blue on Base, and Aave v3 on Monad, Avalanche, BNB Chain and Arbitrum One.
Four of the five have settled a real mainnet transaction. Arbitrum has not:
its addresses are RPC-verified and every gate on the path is the same one the
other four use, but nothing has ever been signed there, so its registry entry
carries `mainnetProven: false` and the capability table prints "no" in its
settled-on-mainnet column. Callable and proven are different claims.

Everything else in the capability registry carries a `notExecutableReason`
saying exactly why it is not callable: no executor implemented, an executor
nothing imports, operator disabled, or proven by script only.

## What does not work yet

Execution of multi-leg workflows is not wired end to end. The planner, the
authorization layer and the per-leg reservation exist and are tested; nothing
yet drives them from a signed plan to a chain. The full list is in
[`docs/production-architecture-review/WORKFLOW_MILESTONE.md`](docs/production-architecture-review/WORKFLOW_MILESTONE.md)
and is deliberately longer than the list of what does.

## Check it yourself

```bash
bash scripts/workflow-gates.sh    # 17 gates: cross-chain, same-chain, standing
bash scripts/standing-e2e.sh      # signs with a key the server never sees
node testbench/run.mjs            # a prompt file, through the real MCP call
pnpm run test                     # ~1000 tests
```

The canonical design and route table are in
[`docs/SYSTEM_ARCHITECTURE.md`](docs/SYSTEM_ARCHITECTURE.md).

Legacy `frontend/`, `server/`, `eigenlayer/`, and agent folders outside this tree remain v3 reference code. New production code lives under `v4/`.

Technical constitution (research-locked stack): [`docs/STACK.md`](docs/STACK.md).

## Architecture spine

```text
intent (kind) -> policy -> kind dispatcher -> venue adapter -> workflow -> receipt
```

Kind is primary. Swap/rebalance enter the solver market (CoW, Jupiter, Cetus, ...). Lend, bridge, stake, and perp use protocol-family adapters and never fall through to a default swap venue.

Execution is intentionally fail-closed. The stack validates, plans, and can dry-run. It does not treat missing signatures, missing approvals, or missing venue adapters as success.

## Live production endpoints

| Surface | URL | Status |
|---|---|---|
| Product web | https://www.getava.xyz | Vercel static, LIVE |
| Public API | https://api.getava.xyz | Fly.io always-on, LIVE |
| Health | https://api.getava.xyz/health | `{"ok":true,"productionMode":true,"dependencies":{"ledger":"postgres",...}}` |
| MCP | https://api.getava.xyz/mcp | 11 tools observed on 2026-08-07 |

```bash
# Verify production
curl -fsS https://api.getava.xyz/health
curl -sS -X POST https://api.getava.xyz/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

## Packages

| Package | Path | Purpose |
|---|---|---|
| `@ava/intent` | `packages/intent` | Versioned `AvaIntent` / `StrategyIR`, `IntentKind`, canonical hashes |
| `@ava/policy` | `packages/policy` | Deterministic policy evaluator for intents and strategies |
| `@ava/verifiability` | `packages/verifiability` | Execution receipt schemas, hashes, invariants |
| `@ava/ledger` | `packages/ledger` | Append-only in-memory ledger and outbox interface |
| `@ava/ledger-postgres` | `packages/ledger-postgres` | Postgres-backed ledger and receipt store |
| `@ava/broker-cow` | `packages/broker-cow` | CoW drafts, dry-run transport, HTTP Orderbook transport |
| `@ava/broker-router` | `packages/broker-router` | Kind-first dispatch; CoW + Jupiter prepare-only for swap kinds; fail closed otherwise |
| `@ava/capability-registry` | `packages/capability-registry` | Capability kind x chain x venue registry |
| `@ava/wallet-policy` | `packages/wallet-policy` | Session permissions and signature request gate |
| `@ava/wallet-turnkey` | `packages/wallet-turnkey` | Real Turnkey-backed, policy-gated signer |
| `@ava/condition-engine` | `packages/condition-engine` | Deterministic StrategyIR trigger evaluator |
| `@ava/adapter-jupiter` | `packages/adapter-jupiter` | Solana Jupiter quote + unsigned swap build |
| `@ava/adapter-cetus` | `packages/adapter-cetus` | Sui Cetus quote/build (injected SDK client) |
| `@ava/adapter-deepbook` | `packages/adapter-deepbook` | Sui DeepBook quote/build (injected SDK client) |
| `@ava/adapter-suilend` | `packages/adapter-suilend` | Sui Suilend prepare/build (injected SDK client) |
| `@ava/adapter-walrus` | `packages/adapter-walrus` | Walrus decentralized storage HTTP adapter |
| `@ava/adapter-membase` | `packages/adapter-membase` | Membase / Unibase agent memory HTTP adapter |

## Apps

| App | Path | Purpose |
|---|---|---|
| `@ava/api-worker` | `apps/api-worker` | Hono ingress: health, capabilities, parse, plan, conditions, fail-closed execute, receipts |
| `@ava/execution-worker` | `apps/execution-worker` | In-process execution workflow, Turnkey signature port, CoW transport selection |
| `@ava/agent-service` | `apps/agent-service` | Mastra cognitive tools + OpenRouter model contract for intent/policy/plan |
| `@ava/web` | `apps/web` | Product shell UI (roles + chat + portfolio/events); live at [www.getava.xyz](https://www.getava.xyz) |

## Onboarding

Every command in this section was run against a fresh `git clone` on
2026-08-10, and the surprises are written down rather than smoothed over.
`bash scripts/onboarding-check.sh` re-verifies these claims, so they cannot
quietly stop being true.

If you only read one line: **run `pnpm test`, never `pnpm -r test`.**

### First run

Requires Node 22+ (23.10 is what this was verified on) and `pnpm@9.15.4`, which
is pinned in `packageManager`. Docker is NOT required to run the tests.

```