Skip to content

Architecture

Status: Canonical architecture (mav diagram + Phase-1 reality)
Date: 2026-07-11
Authority: docs/00-product-constitution.md · docs/00-product-scope-correction.md
Brand: DAY · dayprotocol.com · Limitless Labs

Product: agent-native yield router — markets → route → optional Auto Yield → harvest → Auto Pay.
Not product core: vaults / SuperVaults / “deposit into our vault.”

1. Architecture diagram (Mermaid)

Copy into mermaid.live to render.

flowchart TB
    subgraph UserLayer["User / Agent Layer"]
        A[AI Agents / Characters]
        B[Developers / dApps]
        C[SDK - TypeScript / Python]
    end

    subgraph OrchestratorLayer["Orchestrator Layer (Offchain)"]
        D[Orchestrator Agent]
        E[Decision Engine<br/>Goal-based Routing]
        F[Data Fetcher<br/>Discovery + adapter reads]
        AP[Auto Pay policy]
    end

    subgraph OnchainLayer["Onchain Execution Layer"]
        subgraph Sui["Sui Chain — Phase 1 home"]
            G1[YieldRouter]
            H1[AdapterRegistry]
            I1[Adapters<br/>Suilend, NAVI, Scallop, Haedal...]
        end

        subgraph Solana["Solana Chain — Phase 1 home"]
            G2[YieldRouter]
            H2[AdapterRegistry]
            I2[Adapters<br/>Kamino, marginfi, Jito...]
        end

        subgraph Base["Base — bridge-in / discovery"]
            G3[YieldRouter later]
            H3[AdapterRegistry later]
            I3[Adapters later<br/>Morpho, Aave...]
        end

        subgraph Arbitrum["Arbitrum — expansion"]
            G4[YieldRouter later]
            H4[AdapterRegistry later]
            I4[Adapters later]
        end
    end

    subgraph DataLayer["Data Layer"]
        J[DefiLlama map optional]
        K[Adapter read_apy truth]
        X[x402 pay path optional]
    end

    subgraph CrossChain["Cross-Chain Layer"]
        L[Mayan compose<br/>CCTP / Wormhole under the hood]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    E --> F
    E --> AP
    F --> J
    F --> K
    AP --> X
    E --> G1
    E --> G2
    E -.->|not Phase-1 home| G3
    E -.->|not Phase-1 home| G4

    G1 --> H1
    H1 --> I1
    G2 --> H2
    H2 --> I2
    G3 --> H3
    H3 --> I3
    G4 --> H4
    H4 --> I4

    I1 --> L
    I2 --> L
    I3 --> L
    I4 --> L

    L --> G1
    L --> G2

    classDef user fill:#e3f2fd,stroke:#1976d2
    classDef offchain fill:#fff3e0,stroke:#f57c00
    classDef onchain fill:#e8f5e9,stroke:#388e3c
    classDef data fill:#f3e5f5,stroke:#7b1fa2
    classDef xchain fill:#eceff1,stroke:#546e7a

    class A,B,C user
    class D,E,F,AP offchain
    class G1,G2,G3,G4,H1,H2,H3,H4,I1,I2,I3,I4 onchain
    class J,K,X data
    class L xchain

Phase-1 emphasis (what we ship first)

flowchart LR
    SDK["@dayprotocol/sdk"] --> API["DAY API / Orchestrator"]
    API --> Disc["Discovery map<br/>DefiLlama"]
    API --> Truth["read_apy<br/>venue adapters"]
    API --> Plan["prepare plans"]
    Plan --> SuiR["Sui YieldRouter path"]
    Plan --> SolR["Solana YieldRouter path"]
    Base["Base USDC"] -->|Mayan| SuiR
    Base -->|Mayan| SolR
    SuiR --> AdS["Suilend / NAVI / …"]
    SolR --> AdL["Kamino / Jito / …"]
    AdS --> Harvest["harvest + fee (see /fees/)"]
    AdL --> Harvest
    Harvest --> AutoPay["Auto Pay residual"]

2. Layers

Layer	Components	Responsibility
User / Agent	SDK, AI agents, dApps	Call DAY without custody
Orchestrator (offchain)	Decision engine, data fetcher, Auto Pay policy	Goal → route plan; prepare/execute gates
Onchain execution	YieldRouter, AdapterRegistry, Adapters	deposit / withdraw / harvest / fee math
Data	DefiLlama map + adapter `read_apy`; optional x402	Discovery ≠ truth
Cross-chain	Mayan compose (not DIY multi-AMB)	Fund Phase-1 homes; credit after delivery

3. Key components

Component	Description	Where
YieldRouter	Entry for route/stake/unstake/harvest under owner policy	Onchain per execution home (Sui, Sol first)
AdapterRegistry	Allowlisted protocols + readiness	Onchain + offchain registry mirror (`form-registry`)
Adapters (Forms)	Thin connectors to venues	Onchain wrappers + offchain planners today
Orchestrator	Goal-based routing, enablement, kill switch	Offchain (`/api/day/*`)
Auto Pay	Post-fee residual → storage / inference / x402	Offchain policy + optional pay rails
Gas sponsor	Plan/size gas fronting for agent txs	Offchain plan → onchain when enabled
Bridge	Mayan Base/Eth/Sol/Sui → Sui\|Sol	Plan + delivery + rescue (S7/S8)
Swap	Turbos (Sui), Jupiter (Sol)	Plan now; live when wired

4. Alignments / corrections vs first sketch

Sketch	DAY reality
Wormhole / LayerZero as product layer	Compose Mayan (uses CCTP/Wormhole under the hood). Do not reimplement multi-AMB.
Base + Arbitrum as full homes	Phase 1 execution homes = Sui + Solana. Base = bridge-in / treasury. Arb = expansion backlog.
x402 as primary yield data bus	Discovery = DefiLlama map; truth = adapter `read_apy`. x402 = payments / optional paid data.
Vault product	Out of scope — see `docs/00-product-scope-correction.md`
Characters	Consumers of DAY, not the product core

5. Core flows (detailed)

5.1 Deposit / route (Auto Yield OFF default)

sequenceDiagram
    participant Agent
    participant SDK
    participant Orch as Orchestrator
    participant Router as YieldRouter
    participant Reg as AdapterRegistry
    participant Ad as Adapter Form
    participant Venue as External venue

    Agent->>SDK: goal + amount + policy
    SDK->>Orch: preview / prepare
    Orch->>Orch: allowlist + readiness + read_apy
    Orch-->>SDK: plan (no invent APY)
    Agent->>SDK: execute (owner opt-in if stake)
    SDK->>Router: deposit/route
    Router->>Reg: resolve adapter
    Reg->>Ad: supply
    Ad->>Venue: protocol supply
    Venue-->>Agent: position at venue / receipt

5.2 Harvest + fee + Auto Pay

sequenceDiagram
    participant Anyone as Keeper / agent
    participant Orch as Orchestrator
    participant Router as YieldRouter
    participant Ad as Adapter
    participant Venue

    Anyone->>Orch: harvest trigger
    Orch->>Router: harvest plan
    Router->>Ad: claim / realize yield
    Ad->>Venue: claim_yield / exchange rate
    Venue-->>Router: gross yield
    Router->>Router: apply fee schedule (see /fees/)
    Router->>Router: survival bills optional
    Router-->>Orch: residual
    Orch->>Orch: Auto Pay residual only

5.3 Bridge-in (Base → home)

sequenceDiagram
    participant Owner
    participant Orch
    participant Mayan
    participant Home as YieldRouter home

    Owner->>Orch: bridge plan Base→Sui|Sol
    Orch->>Mayan: compose rail
    Mayan-->>Home: delivery
    Orch->>Orch: actualReceived vs minOut
    alt actual >= minOut
        Orch->>Home: credit actual
    else under minOut / failed
        Orch->>Owner: rescue destination = owner
    end

6. Repo map (today)

Diagram piece	Code today
SDK	`packages/sdk` `@dayprotocol/sdk`
Orchestrator / API	`api/server.mjs`, `api/handlers.mjs`
Decision / scorer	`runtime/scorer/`, `runtime/discovery/`
Adapter registry	`runtime/adapters/form-registry.mjs`
Venue adapters	`runtime/adapters/*`, XEL suilend/navi live path
Bridge / swap / gas	`runtime/bridge/`, `runtime/gas/`
Auto Pay	`runtime/payments/auto-pay.mjs`
Onchain YieldRouter	Sui mainnet live + Solana program live + Base/Arb DayRegistry — see `docs/30-deployed-package-ids.md`

7. Non-goals

No vault farm product / SuperVault core
No team custody of principal
No fee on deposit/withdraw
No multi-AMB reimplementation
No contract lock / UpgradeCap burn until explicit go

Doc	Role
`docs/00-product-constitution.md`	Principles
`docs/00-product-scope-correction.md`	No vaults
`docs/09-fee-model.md`	see Fees
`docs/22-versioning-strategy.md`	Package versions (unlock for now)
`docs/29-architecture-implementation.md`	Rails inventory
`docs/33-full-e2e-test-plan.md`	Test matrix