Trevault (TVLT)

Working name — pending domain/socials/USPTO clearance. See CLAUDE.md §0.1 for why "Meridian" and "USDM" were ruled out before this repo existed.

A Solana CDP (collateralized debt position) protocol that accepts BlackRock's BUIDL (tokenized US Treasury fund) as collateral and mints a stablecoin, TVLT, against it.

Why this exists

Holding a tokenized Treasury fund today means choosing between earning yield or having liquidity — sell BUIDL to get cash, and the yield stops. Trevault lets a position do both:

1. Capital efficiency — keep earning Treasury yield on deposited BUIDL while minting TVLT against it as collateral, instead of selling for liquidity.
2. Peg stability — a cut of accrued yield flows into a Reserve Buffer that absorbs bad debt and can defend the peg, instead of relying purely on static overcollateralization.
3. Expanded BUIDL utility — BUIDL becomes usable as collateral, a liquidity source, and a stability reserve inside DeFi, not just a passive yield wrapper.

Architecture

Seven Anchor programs. The one design invariant that overrides everything else: logic and custody are strictly separated. The CDP Engine never holds tokens. The Vault and Mint never make economic decisions — they execute what the Engine authorizes via CPI, with the Vault performing an independent re-check before releasing funds (defense in depth, not redundant trust).

#	Program	Role	Holds tokens?	Makes economic decisions?
1	Collateral Vault	Custody of deposited BUIDL	Yes	No
2	CDP Engine	Collateral ratio, borrow limits, position state	No	Yes
3	Stablecoin Mint	Sole mint/burn authority for TVLT	No (mint authority only)	No
4	Oracle Adapter	Validated price gateway (Pyth + Switchboard)	No	No (validation only)
5	Liquidation Engine	Detects and closes undercollateralized positions	No	Yes (re-verifies, never trusts input)
6	Yield Manager	Accrues yield, splits user/reserve portions	No	Yes (split logic only)
7	Reserve Buffer	Holds reserve TVLT, absorbs bad debt, peg defense	Yes (TVLT only)	No (passive + multisig-gated)

CPI graph

User wallet → Frontend → Collateral Vault (deposit, direct user call)

CDP Engine ⇄CPI⇄ Collateral Vault      (withdraw/seize, Engine-authorized,
                                         one-directional — Vault re-checks
                                         its own copy of position state,
                                         no callback into the Engine)
CDP Engine  CPI→  Stablecoin Mint      (mint/burn, Engine-authorized)
CDP Engine  CPI→  Oracle Adapter       (get_price — always via adapter,
                                         Engine never reads oracle accounts directly)
CDP Engine  →     Liquidation Engine   (health-factor signal)

Liquidation Engine CPI→ Stablecoin Mint    (burn from liquidator)
Liquidation Engine CPI→ Collateral Vault   (seize)
Liquidation Engine CPI→ Reserve Buffer     (absorb_bad_debt, on shortfall)

Yield Manager CPI→ Oracle Adapter      (get_price for collateral value)
Yield Manager CPI→ Stablecoin Mint     (mint claimed yield — POC only)
Yield Manager CPI→ Reserve Buffer      (receive_yield / flush_to_reserve)

Full hand-drawn reference diagram:

Frozen conventions

• Fixed-point math: 6 decimal places everywhere (1_000_000 = 1.00 = 100%). Raw Pyth-style exponent math is only allowed inside the Oracle Adapter's normalize_price step.
• PDA seeds (exact strings, do not vary per program): ["vault", buidl_mint] · ["position", user] · ["config"] · ["yield_state", user] · ["yield_config"] · ["reserve"] · ["price_cache", mint] · ["liq_config"] · ["stablecoin_mint"]
• CPI authorization is identity-based: every CPI-only instruction checks caller_program_id against a Pubkey stored in that program's own config account — never inferred from account ordering.
• Events: every state-changing instruction emits a typed event, feeding the off-chain solvency dashboard and indexers.

See CLAUDE.md for the full list of locked decisions and the guardrails an agent (or a reviewer) should check a PR against.

Tech stack

• Chain: Solana, Anchor framework, Rust
• Oracles: Pyth (primary) + Switchboard (fallback/cross-check)
• Collateral asset: BlackRock BUIDL, SPL Token-2022 with a compliance transfer hook (issuer-enforced KYC — the protocol never implements KYC itself)
• Admin: multisig (e.g. Squads), 3-of-5, gates all config updates and emergency actions
• Off-chain: event-driven indexer feeding a solvency dashboard (Phase 8)

Repository layout

programs/
  common/              # shared fixed-point math, STABLECOIN_SYMBOL constant
  oracle-adapter/
  stablecoin-mint/
  collateral-vault/
  cdp-engine/
  reserve-buffer/
  yield-manager/
  liquidation-engine/
docs/
  spec.md              # full instruction-level spec (copy of meridian.md)
  architecture-diagram.png
tests/
Anchor.toml
CLAUDE.md              # build order, locked decisions, PR guardrails

Getting started

Prerequisites: Rust, the Solana CLI, the Anchor CLI, and Node (for the test suite).

anchor build
anchor test              # localnet
anchor deploy --provider.cluster devnet

Build status

Following the phase order in CLAUDE.md (each phase's CPI targets must exist before the next phase needs them):

• Phase 0 — Workspace bootstrap
• Phase 1 — Oracle Adapter
• Phase 2 — Stablecoin Mint
• Phase 3 — Collateral Vault
• Phase 4 — CDP Engine — POC Milestone 1 (deposit → mint → repay)
• Phase 5 — Reserve Buffer
• Phase 6 — Yield Manager — POC Milestone 2 (yield accrual + reserve split)
• Phase 7 — Liquidation Engine — POC Milestone 3 (liquidation loop closes)
• Phase 8 — Integration, solvency dashboard, devnet POC
• Phase 9 — Frontend (Deposit / Mint / Repay / Yield-Reserve modules)
• Phase 10 — Grant submission polish

Contributing / working with Claude Code

CLAUDE.md is the authoritative project-context file for Claude Code — it encodes the locked decisions (naming, CPI direction, fixed-point convention) and the self-check guardrails a PR should be held to. Read it before docs/spec.md; it governs sequencing and scope, the spec governs implementation detail.