XEL Integration

Version: 1.0
Date: 2026-07-11
Parent: docs/23-auto-yield-implementation.md, docs/24-open-yield-api.md, docs/25-open-yield-sui-move.md
Plane: XEL-152
Reuse scan: Codex comments on XEL-152…168

Once Open Yield is built, it is not a separate product next to XEL.
It is the treasury capability every Living Character can use.

1. Integration model (one sentence)

Each XEL character’s shared Endowment becomes an Open Yield position; persona stays GEN-optional; keepers + owner APIs drive stake/harvest/Auto Pay under policy.

Persona (GEN optional)
Memory (Walrus/Seal)
Mind (inference providers)
        │
        ▼
LivingCharacter aNFT (owned)
        │
        ▼
Endowment + TreasuryPolicy  ── Open Yield execution home (Sui)
        │
        ├── Auto Yield (opt-in stake / harvest / compound)
        ├── Auto Pay (post-fee residual → storage/inference/x402)
        ├── Bridge-in (Mayan Base/Sol → Sui)
        ├── Gas sponsor (Turbos USDC→SUI)
        └── Opportunity agent (DefiLlama map, propose only)

2. What already plugs in (do not rebuild)

XEL subsystem	Path	Open Yield role after build
Endowment / fee / harvest	`contracts/v2/sources/treasury.move`	Onchain capital + ~5% yield skim
Venue adapters	`runtime/treasury/suilend-adapter.mjs`, `navi-adapter.mjs`	supply/withdraw/claim/read_apy
Lifecycle / waterfall math	`runtime/treasury/lifecycle.mjs`	plans, net-yield receipts, allowlist blockers
Heartbeat keepers	`runtime/keepers/heartbeat-runner.mjs`, `talus-leader-heartbeat.mjs`	permissionless harvest poke
Bridge-in	`runtime/treasury/mayan-executor.mjs` + backend bridge-to-sui	fund endowment from Base/Sol
Gas	`runtime/treasury/gas-sponsor.mjs`	sponsor stake/harvest/sweep PTBs
Payments	`runtime/payments/x402.mjs` + `payment.move`	Auto Pay rail
Operator yield API	`backend/main.py` stablecoin-yield routes	internals under product API
Honest FE pattern	`frontend/components/settings/YieldVenueStatus.tsx`	template for Auto Yield UI
Funding snapshots	`backend/main.py` funding budget/snapshot	estimates + runway inputs
Policy schema	`schemas/treasury-policy.v1.json`	extend for auto_yield / auto_pay fields
Public agent surface	`site/skill.md` / `skill.json`	document Open Yield capability

3. Integration layers (after build)

3.1 Onchain (Sui)

Step	How
Character mint	Create aNFT + shared Endowment + TreasuryPolicy (`auto_yield_enabled=false`)
Deposit	Anyone/owner `top_up_endowment` — no fee
Enable Auto Yield	Owner sets `auto_yield_enabled=true` (+ optional max stake / venue)
Stake	Owner (or narrow stake envelope) → Suilend/NAVI supply under allowlist
Harvest	Permissionless heartbeat: claim PTB → fee skim → residual compound
Withdraw	Owner `withdraw_endowment_principal` — no fee; unstake first if needed
Survival	Only auto-unstake when storage due + liquid short

Integration rule: Open Yield never replaces the aNFT; it operates the endowment.

3.2 Backend API (product surface)

Wrap existing operator treasury into character-scoped Open Yield APIs:

Product route	Calls into
`GET/PUT /api/characters/{id}/auto-yield`	policy + app mirror of `auto_yield_enabled`
`POST .../open-yield/preview` · `route`	discovery + scorer + optional top_up/stake plan
`POST .../open-yield/harvest`	keeper/plan builders + adapters
`POST .../open-yield/withdraw`	owner auth → unstake + withdraw
`GET .../open-yield/position`	funding snapshot + read_apy + estimates
`POST .../open-yield/auto-pay`	spend policy + x402 targets
`GET /api/open-yield/opportunities`	discovery agent snapshots
`GET /api/open-yield/venues`	stablecoin-yield readiness

Keep /api/treasury/sui/stablecoin-yield/* as internal/operator aliases.

3.3 Runtime / keepers

Job	Integration
Heartbeat cron / Talus	Load character roster of shared endowments; claim→heartbeat; gas-sponsor PTB
Opportunity agent	Cron: DefiLlama → filter TVL≥$50M → propose; never stake
Wallet watcher	Base/Sol USDC → Mayan → credit endowment → optional notify owner to stake
Auto Pay	After harvest residual: pay storage/inference within policy via x402

3.4 Frontend (xel.xyz)

Surface	Change
Settings / Treasury	Auto Yield toggle OFF default; venue; staked/liquid
Endowment / Funding screens	Real estimates from API; kill demo APY (`funding-model.ts` stubs)
YieldVenueStatus	Extend for Open Yield status + blockers
Character profile (public)	Optional: net APY estimate / runway only if honest data exists
Fan credits	Unchanged ring-fence — never Auto Pay source

3.5 Public protocol / agents

Surface	Integration
`site/skill.md`	Document Open Yield tools: preview, route, harvest, position
MCP / GEN agents	Call XEL open-yield routes with character scope + AgentCap limits
Provider registry	Optional capability `treasury.yield.v1` / `open_yield.v1`

3.6 GEN boundary (important)

GEN	XEL Open Yield
Optional persona synthesis	Does not control funds
GEN credits / x402 purchase	Separate from endowment principal
Publish to XEL	Character may arrive unfunded; Open Yield starts when endowment funded

Line: persona by GEN, capital by Open Yield — both optional; character valid with neither.

4. Lifecycle once integrated

1. Mint character → Endowment liquid, Auto Yield OFF
2. Fund (top_up and/or Mayan bridge-in)
3. Owner enables Auto Yield (optional)
4. Owner stakes amount/venue (or owner-signed stake envelope)
5. Keepers harvest permissionlessly → fee skim ~5% → residual compounds
6. Storage due → survival auto-unstake min if needed
7. Auto Pay (if on) → residual → storage/inference/x402
8. Owner can withdraw anytime (after unstake if needed)

5. Auth matrix (integration-critical)

Action	Owner	AgentCap	Anyone
top_up	yes	if funded path allows	yes (pay in)
enable Auto Yield	yes	no	no
stake principal	yes (or narrow envelope)	only if explicit stake scope	no
harvest poke	yes	yes	yes
Auto Pay config	yes	no widen	no
Auto Pay execute residual	policy	within spend policy	no
withdraw principal	yes	no	no

6. Data that must flow character-scoped

Field	Source after integration
`auto_yield_enabled`	onchain TreasuryPolicy + app mirror
`liquid_micros` / `staked_micros`	indexer + venue position
`gross_apy_bps` / `net_apy_bps`	adapter read_apy + fee bps
`last_harvested_at`	heartbeat events
`opportunities[]`	discovery agent DB/snapshots
`auto_pay` config	app policy + spend-policy
`fee_bps`	protocol_yield_skim_bps

All APIs keyed by character_id (and endowment object id), not a global vault share id.

7. Enablement order (integrate safely)

Ship discovery/scorer/API/toggle without broadcast
Wire FE honesty to real status
Staging: owner stake mock → harvest fee path
Close XEL-70 NO-GO (SDK roots, flags, keeper roster, prepare smoke)
Staging live Suilend with small amount
Prod flags only with mav go
Auto Pay last (post-fee residual only)

8. What “done integrated” looks like

New character: Auto Yield OFF, liquid endowment only
Owner can enable, stake USDC on Suilend, see real net APY
Permissionless harvest takes ~5% fee, compounds residual
Bridge-in from Base/Sol credits that character’s endowment
Gas-sponsored PTBs for stake/harvest
FE never shows demo 5% APY
Agent cannot withdraw principal
skill.md lists Open Yield capabilities for external agents

9. Non-integration (keep out of XEL core)

Standalone Base YieldRouter.sol as character home
Multi-user ERC-4626 share vault replacing per-character endowment
Auto-stake on mint
DefiLlama as execution oracle
GEN holding character principal

10. Ticket → integration seam (quick)

Ticket	Integration point
153–154, 164	runtime discovery/scorer → opportunities API → skill/orchestrator
155–157	character open-yield API → backend stablecoin-yield internals
156	TreasuryPolicy + FE toggle
158, 167–168	keepers + gas-sponsor + fee waterfall
159	keeper survival path
160	Endowment/Funding/Settings FE
161	prod env / readiness
163	x402 + residual after harvest
165	funding snapshot estimates block
166	wallet-watcher + Mayan + optional Turbos
162	skill.md + docs + Plane pages