cred402/docs/collateral.md
caelum0x 24d073ee83 feat: KeeperHub execution layer + Flare interoperable/confidential credit
Two hackathon integrations spanning the whole credit stack, sim-first
(green with no keys) with real integrations behind env flags.

KeeperHub — the on-chain execution & reliability layer (lib/keeperhub/):
- OnchainExecutor: pay-per-execution (x402/MPP) -> simulate -> smart gas
  with exponential backoff -> MEV-protected private routing -> audit trail;
  real MCP client to app.keeperhub.com; deterministic sim fallback.
- Autonomous Credit Keeper: FTSO position health -> check->execute deleverage.
- Credit Automations: declarative price/health/schedule rules as workflows.
- Autonomous Scheduler: KeeperHub-cron loop running keeper + automations.

Flare — interoperable + confidential primitives (packages/.../flare, lib/flare):
- FXRP credit satellite: CAN-gated, FTSO-priced, FDC-attested; Coston2
  Solidity vault (contracts/flare/).
- Confidential Compute credit scoring (TEE-attested, private inputs).
- FTSO-priced multi-asset collateral; FAssets mint->collateralize lifecycle.

x402 Credit-Service Marketplace: sells cred402's intelligence pay-per-call
over x402 (402->pay->200); paid receipts feed the revenue->reputation loop.

Wiring: 78 MCP tools, /v1 + /api routes, console Flare + x402 tabs, 11 demo
CLIs, 8 feature docs + docs/SUBMISSIONS.md, recorded demo video (media/).
346 tests pass; 7 adversarial verification workflows caught + fixed ~37
correctness/security issues.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-11 23:34:23 +03:00

10 KiB
Raw Permalink Blame History

FTSO-priced collateral — borrowing power for agent credit

Reputation gives an agent a base USD cap; posting collateral expands it. An agent can post several assets — USDC, BTC, ETH, XRP, FLR — each marked to its live FTSO feed and discounted by a per-asset LTV haircut. The LTV-weighted USD value adds to the reputation cap to form the agent's borrowing power. This is Flare's multi-feed FTSO oracle doing exactly what it is for: pricing a basket of heterogeneous assets on-chain, with no third-party price API, turning agent credit into a real over-collateralized primitive.

An agent's Flare credit line is drawn in the FAsset FXRP but capped in USD by its creditworthiness. Reputation sets that cap; it does not have to be the only source of borrowing power. CollateralVault (lib/flare/collateral.ts) lets an agent post collateral in several assets and expands its borrowing power by the LTV-weighted USD value of the basket — so a position that trips a margin call against the reputation cap alone can be cured by posting collateral instead of repaying debt.


The model

Borrowing power is additive: the reputation cap plus the LTV-haircut value of every posted asset. The health factor is the same as before — it just divides against the larger denominator.

  collateral_usd      = Σ (asset_amount × FTSO(asset/USD) × LTV)   (per-asset haircut)
  borrowing_power_usd = cap_usd + collateral_usd
  health_factor       = borrowing_power_usd / debt_usd             (> 1 = within power; ∞ when no debt)

Each asset is valued at its live FTSO price, then discounted by its LTV advance rate: volatile assets advance less. The result (value_usd × ltv) is that asset's contribution to borrowing power.

Supported assets (COLLATERAL_ASSETS)

Symbol FTSO feed Decimals LTV Rationale
USDC USDC/USD 6 95% Stable — advances almost par.
BTC BTC/USD 8 80% Deep, liquid, but volatile.
ETH ETH/USD 18 75% Liquid, more volatile than BTC.
XRP XRP/USD 6 60% Native to the FXRP debt asset; heavier haircut.
FLR FLR/USD 18 40% Flare-native, most volatile — most conservative advance.

Deposits are held per agent, in each asset's smallest units (amount_whole × 10^decimals). Valuation is live FTSO with the deterministic sim reference price as a fallback — identical shape either way, so the demo and tests run with no keys.

Additive by design — no collateral means unchanged behavior

Collateral is strictly additive. PositionEngine (lib/flare/positions.ts) takes an optional collateral source; when an agent has posted nothing (or no vault is wired), collateral_usd is 0, borrowing_power_usd collapses to cap_usd, and the health factor is exactly what it was before this feature. Existing behavior and tests stay green — collateral only ever raises borrowing power, never lowers it.


Integration — the keeper and automations assess against borrowing power

The Autonomous Credit Keeper and Credit Automations classify positions off the health factor, and that health factor is now borrowing_power_usd / debt_usd. Two consequences:

  • Posting collateral can cure a margin call with NO repay. Where the keeper's only cure used to be deleveraging (repaying FXRP), an agent can now expand borrowing power by posting collateral and lift the health factor above the margin-call line without touching its debt. Deleveraging and collateralizing are two ways to raise the same ratio — one shrinks the numerator's debt, the other grows the denominator's power.
  • The what-if price stress test still applies. The FTSO XRP/USD priceOverride re-marks the FXRP debt at a hypothetical price and recomputes the health factor against the collateral-expanded borrowing power — so you can ask "does my collateral still hold if XRP rallies 50%?" before the market moves.

Worked example

npm run collateral:run (scripts/collateral_run.ts) runs the flow end to end — sim by default (no keys, no network), real FTSO behind FLARE_RPC_URL:

┌────────────────────────────────────────────────────┐
│ Cred402 collateral — FTSO-priced borrowing power │
└────────────────────────────────────────────────────┘

● Scene 1 — Draw 8,500 FXRP — over the reputation cap
  debt $4420 vs cap $5000 (collateral $0) → borrowing power $5000
  health factor 1.13 · status MARGIN_CALL

● Scene 2 — Post collateral (USDC + BTC + ETH), valued by FTSO
  0.03 BTC @ $64000 (sim) = $1920 → $1536 power (LTV 80%)
  0.5 ETH @ $3200 (sim) = $1600 → $1200 power (LTV 75%)
  1500 USDC @ $1 (sim) = $1500 → $1425 power (LTV 95%)
  total collateral value $5020 → borrowing power +$4161

● Scene 3 — Position after collateral
  borrowing power now $9161 (cap $5000 + collateral $4161)
  health factor 1.13 → 2.07 · status HEALTHY — cured with no repay

● Scene 4 — Stress — XRP/USD +50% to $0.78
  debt would be $6630 · HF 1.38 · status HEALTHY

Reading it end to end:

  • Scene 1 — margin call. The agent draws 8,500 FXRP. At the FTSO XRP/USD price of $0.52 that debt is worth $4,420 against a $5,000 reputation cap → HF 1.13, below the 1.15 margin-call line: MARGIN_CALL. No collateral yet, so borrowing power equals the cap.
  • Scene 2 — post collateral. The agent posts three assets. Each is priced by FTSO (0.03 BTC @ $64,000, 0.5 ETH @ $3,200, 1,500 USDC @ $1) and discounted by its LTV: $1,536 + $1,200 + $1,425. A $5,020 gross basket contributes +$4,161 of borrowing power.
  • Scene 3 — cured, no repay. Borrowing power rises to $9,161 (cap $5,000 + collateral $4,161). The same $4,420 debt now divides against $9,161 → HF 2.07, HEALTHY. The margin call is cured without repaying a single FXRP.
  • Scene 4 — stress test. The priceOverride what-if rallies XRP/USD +50% to $0.78: the FXRP debt would be worth $6,630, but against the $9,161 collateral-expanded power the HF is still 1.38 → HEALTHY. This is hypothetical, marked what-if — nothing is executed.

Surfaces

The identical vault + engine is exposed on every Cred402 surface.

MCP tools (mcp/tools.ts)

Tool Purpose
cred402.deposit_collateral Post FTSO-priced collateral (USDC/BTC/ETH/XRP/FLR) to expand an agent's borrowing power. Each asset is marked to its live FTSO feed and discounted by an LTV haircut; the resulting borrowing power is added to the reputation cap in the agent's position health. Returns the new balance + basket valuation.
cred402.collateral_value Value an agent's posted collateral basket in USD via FTSO, with per-asset LTV haircuts, plus the total borrowing power it contributes.

/v1 endpoints (api/v1/router.ts)

Method Route Returns
GET /v1/agents/:id/collateral The agent's collateral basket valued in USD via FTSO, with per-asset LTV haircuts and total borrowing power.
POST /v1/agents/:id/collateral { symbol, amount } → deposit collateral; returns the new balance, basket valuation, and the updated position.
POST /v1/agents/:id/collateral/withdraw { symbol, amount } → withdraw collateral (reverts on insufficient balance); returns the new balance, valuation, and updated position.

Console (api/server.ts + api/state.ts)

Method Route Returns
GET /api/collateral Read-only view for the Flare tab Collateral panel: the seller's basket valuation + current position. Safe to poll.
POST /api/demo/collateral One-click demo: open a margin-called FXRP position, then post 3,000 USDC (+$2,850 borrowing power at 95% LTV) to cure it — before / after positions + valuation, no repay.

State methods: collateralView, runCollateralDemo, and the underlying depositCollateral / withdrawCollateral / collateralValue.

Script

npm run collateral:run      # scripts/collateral_run.ts — the full margin-call → post collateral → cured → stress-test demo

What's real vs sim

Following the repo's real-behind-env + deterministic sim convention — same return shapes either way, so the demo and tests run with zero keys:

Capability Real (env set) Sim (default)
Collateral pricing Each asset's FtsoV2.getFeedById eth_call via FLARE_RPC_URL, FtsoV2 resolved from the FlareContractRegistry Deterministic FTSO reference prices per feed; RPC failure degrades to sim

The LTV haircuts, per-agent deposit accounting, and the additive cap + collateral borrowing-power model are enforced identically in both modes — only the price feed differs.


Bringing XRP as collateral (FAssets)

The XRP collateral asset in the table above does not have to be XRP an agent already holds on Flare — it can be minted on demand from real XRP via FAssets. An agent reserves minting on the FXRP AssetManager, pays the underlying XRP on the XRP Ledger, the FDC attests that payment, and executeMinting mints FXRP 1:1. Because FXRP is XRP bridged 1:1 on the same XRP/USD feed, that minted FXRP is posted straight into the CollateralVault as the XRP asset (60% LTV) — expanding borrowing power with no repay and no new debt.

  real XRP → mint FXRP (FDC-attested, 1:1) → post as XRP collateral → borrowing power +$= fxrp_whole × FTSO(XRP/USD) × 0.60

This closes the interoperable-asset loop: real XRP liquidity becomes on-chain agent working capital that backs a credit line. mintAndCollateralize (api/state.ts) does the whole loop in one call; cred402.mint_fxrp with collateralize=true (MCP) and POST /v1/fassets/mint {collateralize:true} (REST) expose it. Full lifecycle, state machine, fail-closed attestation rule, and a worked example: fassets.md.


References

  • FAssets mint → collateralize (where minted FXRP collateral comes from): fassets.md
  • Risk engine + health factor: credit_keeper.md
  • FTSO oracle, FXRP, and the wider Flare satellite: flare_integration.md
  • Vault: lib/flare/collateral.ts · Engine: lib/flare/positions.ts · Demo: scripts/collateral_run.ts