Chrysalis v2

Chrysalis v2 Architecture

Architecture documentation for Chrysalis v2, including the multi-agent control plane, settlement router, bridge adapters, receipts, and protocol execution flow.

User / trigger ──intent──▶ RoutePlannerAgent
                                  │
                    ┌─────────────┼──────────────┐
                    ▼             ▼              ▼
             RiskPolicyAgent  FeeQuoteAgent   (builds step pipeline)
             allowlists,      prices Gateway,
             slippage caps,   CCTP V2, BridgeKit
             transfer limits  routes; scores by
                              optimization goal
                    │             │
                    └──────┬──────┘
                           ▼
                 ProtocolActionAgent ──encodes calldata──▶ Orchestrator Pipeline
                                                                  │
                                        verify deposit -> bridge/mint -> call adapter
                                                                  │
                                                                  ▼
                                          ArcIntentRouterUpgradeable + adapter
                                          (EVM) / Anchor program (Solana) /
                                          Soroban contract (Stellar)
                                                                  │
                                                                  ▼
                                        Receipt NFT minted on Arc + JudgeNarratorAgent
                                        writes a plain-English audit narration

The agent control plane

Seven specialized agents cooperate to analyze, quote, secure, route, execute, and audit every intent:

Agent	Role
`RiskPolicyAgent`	Pre-flight policy enforcement - allowlists source/destination/protocol, caps slippage, enforces transfer limits, and flags fee-guard violations before an intent is priced.
`FeeQuoteAgent`	Computes and separates source gas, destination gas, bridge fees, protocol fees, slippage impact, and paymaster sponsorship, then scores eligible routes against the stated optimization goal.
`RoutePlannerAgent`	Selects the highest-scoring eligible route, flags intents that need manual approval, and builds the orchestrator's step-by-step execution plan.
`ProtocolActionAgent`	Encodes the actual call data per target - ABI-encoded calls for EVM adapters, instruction payloads for Solana Anchor programs, `Vec<Val>` arguments for Soroban contracts.
`JudgeNarratorAgent`	Turns a completed intent's execution steps, route choice, fees, and transaction hashes into a plain-English audit narration, including why alternative routes were rejected.
`NanopaymentAgent`	Runs EIP-3009/EIP-712 paid API access via x402 - challenges unauthenticated requests to premium endpoints and validates payment signatures to unlock them.
`TreasuryRebalancerAgent`	Watches USDC balances across supported networks and autonomously bridges from the largest-surplus chain back to Arc when the balance drops below a safety floor.

Router and adapters

ArcIntentRouterUpgradeable (UUPS-upgradeable) is the core EVM control point. It doesn't implement protocol logic itself - it registers adapters per (chain, protocol) key, routes execution to them, and can pause or swap an adapter without a state migration.

Function	Role
`registerAdapter(chainKey, protocolKey, adapter)`	Adapter-admin only. Wires a protocol adapter into the router for a given chain.
`setAdapterStatus(chainKey, protocolKey, enabled)`	Enables or disables a registered adapter without removing it.
`routeLocal(...)`	Executes an adapter call using funds already on this chain (no bridge hop needed).
`executeWithRouterBalance(...)`	Executes using USDC the router already holds - the common path after a bridge/mint completes.
`recordRemoteIntent(...)`	Logs an intent that will be fulfilled on a different chain (Solana/Soroban), for audit and receipt purposes.
`pause()` / `unpause()`	Admin-only circuit breaker for the whole router.

Protocol adapters implement IProtocolAdapter and are isolated per protocol - UniswapV3Adapter, AaveV3Adapter, MorphoBlueAdapter, ArcUsycTellerAdapter, and GatewayWalletAdapter on the EVM side; Kamino, Raydium, and Marinade Anchor programs on Solana; Aquarius and Blend Soroban contracts on Stellar. Adding a new protocol means writing a new adapter and registering it - it never touches the router's core logic.

Bridge routing: Gateway, CCTP V2, and BridgeKit

The FeeQuoteAgent and RoutePlannerAgent choose a bridge per intent based on cost, speed, and the optimization goal:

Circle Gateway - a unified balance model with ~5s finality, implemented in gatewayService.ts. Preferred automatically for small EVM-to-EVM transfers (≤$100).
Circle CCTP V2 - native burn-and-mint via CctpBridgeAdapter.sol and cctpService.ts. This is the fallback that covers every supported chain, including Solana Devnet and Stellar Testnet, which Gateway doesn't reach.
Circle BridgeKit - an SDK-level abstraction for EVM-to-EVM transfers, implemented in circleBridgeKit.ts.

Every bridge is isolated behind its own service file and the router treats routes generically, so each one plugs into the same ArcIntentRouterUpgradeable pipeline without the core execution logic changing.

Gas sponsorship

Destination-chain gas is handled through circlePaymaster.ts, with three modes selectable per intent: sponsored (fully paid by the paymaster - the user needs zero native tokens), user_usdc (deducted from the user's USDC), or native (paid normally in ETH or the chain's native token).

Orchestration and receipting

Once an intent clears policy and is approved, the orchestrator pipeline runs the flow end-to-end: verifies the source deposit (EVM gas, Solana lamports, or Stellar stroops depending on origin), triggers the selected bridge route, waits for destination-router funding, executes the target protocol adapter payload, mints a Receipt NFT on Arc, and fires the JudgeNarratorAgent to generate the plain-English execution summary.