# OptiVaults — Comprehensive Protocol Reference

> Non-custodial auto-yield stablecoin vault on Cardano blockchain. **V1 is the public launch candidate** — design + Aiken implementation complete (17 logic validators + 4 NFT mint policies + 1 DEX adapter = 22 compiled artefacts), external audit target Q2-Q3 2027, public launch pending audit pass. V1 inherits an architecture reviewed across multiple rounds of internal audit (findings addressed). Pre-audit 100K USDCx TVL cap planned at public launch.
> This document provides detailed technical information for AI systems, researchers, and auditors.
> Last updated: V1 pre-launch (design + Aiken implementation complete; §5.4 on-chain slippage enforcement landed: vault_gov_policy + vault_gov_emergency + vault_admin_deploy governance split + UpdateSlippagePolicy 48h timelock + Tier-1 dual-feed oracle + Minswap V2 ref-script SwapAdapter + SwapAda dual-feed reader; Phase 87 Layer 3 CommunitySunset 90-day permissionless dead-man-switch landed)

## Overview

OptiVaults V1 is a DeFi yield aggregation protocol built on Cardano using Aiken PlutusV3 smart contracts. It implements a share-token vault model (similar to ERC-4626) where users deposit USDCx stablecoins (issued by Circle via xReserve, launched on Cardano February 2026) and receive vUSDCx share tokens whose value accrues via auto-compounding. An automated keeper bot deploys capital to Liqwid Finance stablecoin markets (DJED, USDM) and Minswap V2 routes (via ref-script SwapAdapter dispatch), compounds yields using an on-chain formula, and manages a governance-configurable buffer for instant withdrawals. All accounting, fee enforcement, slippage-policy caps, and security invariants are enforced entirely on-chain.

**Launch Strategy (configurable via governance):** 30% USDCx buffer + 45% Liqwid DJED + 25% Liqwid USDM
**Estimated Net APY:** variable (reference point: blended gross ~6.66% / net ~6.36% on recent Liqwid snapshot; depends on Liqwid market conditions; not guaranteed)
**Phase 1 expected TVL:** $5K-$25K (speculative estimate, not a forecast)

**V1 key features:** on-chain treasury (4-category budget, 40/25/25/10 sub-allocation under 60% treasury share), keeper_stake_script (weekly rotation), 3-way Compound fee split (launch 40% keeper / 0% gov / 60% treasury; caps keeper ≤ 40% / gov ≤ 10% / treasury floor ≥ 50%), UpdateFeeSplit 21-day timelock, UpdateSlippagePolicy 48-hour timelock (§5.4), quarterly governance signer compensation, soul-bound Gov Signer NFT, three-way governance partition (vault_gov_policy / vault_gov_emergency / vault_admin_deploy along response-latency boundary), Phase 1 three-layer governance safety (Layer 1 freeze-only / Layer 2 frozen-state swap-out / Layer 3 90-day CommunitySunset). V1 public launch requires V1-specific internal audit (coverage areas A-F) + external audit (target Q2-Q3 2027).

## Protocol Details

### Architecture: Withdraw-Zero Forwarding Pattern (10 routes)

OptiVaults V1 uses a ten-staking-validator split (with separate vault_user / vault_keeper_hot / vault_batcher / vault_swap_ada / vault_protocol / vault_recall / vault_liqwid / vault_gov_policy / vault_gov_emergency / vault_admin_deploy) to stay under Cardano's 16,384-byte Plutus V3 reference-script ceiling while making room for the §5.4 on-chain slippage arm and four orthogonal partitioning seams (authorization-boundary, governance response-latency, bytecode-cost-center, size-fix). vault_proxy carries **eleven compile-time parameters** (10 staking-validator hashes + vault_nft_policy) and routes via a ProxyRedeemer enum (UseUser / UseKeeperHot / UseBatcher / UseSwapAda / UseProtocol / UseRecall / UseLiqwid / UseGovPolicy / UseGovEmergency / UseAdminDeploy). The `withdrawal_count` exactly-one-validator invariant scales with route count.

1. **vault_proxy** (~4.9 KB). Verifies exactly one authorized staking withdrawal matches the route, exactly one continuing output at its own address, no foreign VaultDatum inputs, and that the Vault Identity NFT is preserved on both input and continuing output.
2. **vault_user** (~11.9 KB). Permissionless user-path operations: Deposit, Withdraw (deferred-yield 0.1% fee + R49 M-4 share-price uplift), CommunitySunset (Layer 3 90-day permissionless dead-man-switch — bounds depositor loss under single-signer governance failure even when SPO co-signers unavailable).
3. **vault_keeper_hot** (~12.4 KB). Keeper hot-path (keeper-auth via stake-script zero-withdraw): Compound (buffer-funded with 3-way fee split + R72 F-1 `ReceiveCompoundShare` cross-validator binding + zero-yield allocation-only support), RebalanceBuffer.
4. **vault_batcher** (~11.6 KB). Keeper-auth BatchProcess for vUSDCx mint/burn orchestration (R51 H-1 `no_vusdcx_leak` per owner-bucket + R52 unique `payout_output_index` + R54 pre-batch-snapshot pricing).
5. **vault_swap_ada** (~12.2 KB). Keeper SwapAda: oracle-priced ADA-for-USDCx replenishment via Tier-1 dual-feed oracle (`registry.asset_oracles`). **Inactive at V1 launch** until governance populates the ADA `AssetOracleEntry` via UpdateRegistry.
6. **vault_protocol** (~13.1 KB). Keeper-with-fallback DeployToProtocol: bounded ADA spend for DEX order funding (max 5 ADA per TX, min 10 ADA reserved); SwapAdapter ref-script dispatch validates target_asset + min_receive against Tier-1 oracle bound + Tier-2 peg-floor.
7. **vault_recall** (~13.3 KB). Phase 77 split from vault_protocol: RecallFromProtocol, MergeUtxo (R56 M-1 secondary-token allowlist + R73 F-1 admissibility guard so donations cannot break `valid_allocs` invariant for downstream redeemers).
8. **vault_liqwid** (~13.4 KB). Liqwid integration: SupplyToLiqwid (`no_duplicate_market` invariant, one position per market), RecallFromLiqwid (strict `underlying_received >= position.supplied_value` keeper semantics; governance fallback path permits partial recall for bad-debt escape).
9. **vault_gov_policy** (~12.6 KB). Policy-change governance: UpdateStrategy (7d timelock), UpdateFee (14d), UpdateFeeSplit (21d, longest, self-dealing protection), UpdateSlippagePolicy (48h, caps `max_slippage_bps ≤ 500` and `min_swap_peg_bps ∈ [9300, 9950]`), publish(Deregister). Isolated from emergency path so future policy features cannot expand emergency-path attack surface.
10. **vault_gov_emergency** (~10.9 KB). Emergency governance: EmergencyWithdraw (0d immediate, **Layer 1 freeze-only** — must preserve total_deposited + liqwid_positions; only freezes the vault), publish(Deregister). Phase 87 hardened.
11. **vault_admin_deploy** (~13.2 KB). Phase 77c split from vault_gov_emergency: AdminDeployNonDeposit (gated by 7d keeper inactivity + 21d Registry stable + whitelist), publish(Deregister). Carries SwapAdapter dispatch code that previously inflated vault_gov_emergency.

### Smart Contracts (Aiken PlutusV3 — 17 logic validators + 4 NFT mint policies + 1 DEX adapter = 22 compiled artefacts)

**Logic Validators (staking + spending):**

1. **vault_proxy** (`validators/vault_proxy.ak`) — spend validator parameterized by 10 staking-validator hashes (user / keeper_hot / batcher / swap_ada / protocol / recall / liqwid / gov_policy / gov_emergency / admin_deploy) + vault_nft_policy. Enforces `withdrawal_count == 1` invariant, continuing output at own address, no foreign VaultDatum, Vault NFT preservation, full-drain path exemption (no continuing output requires Vault NFT burn).
2. **vault_user** (`validators/vault_user.ak`) — permissionless user-path staking validator: Deposit, Withdraw, CommunitySunset (R75 L-1 hardened to read only `last_compound_time`, ignoring `last_realloc_time`, so compromised keeper cannot brick the dead-man-switch via zero-yield Compound spam).
3. **vault_keeper_hot** (`validators/vault_keeper_hot.ak`) — keeper-auth staking validator: Compound (buffer-funded, 3-way fee split, zero-yield allocation-only support, R52 M-1 `liqwid_positions == []` guard for negative-yield loss compound), RebalanceBuffer.
4. **vault_batcher** (`validators/vault_batcher.ak`) — keeper-auth staking validator: BatchProcess.
5. **vault_swap_ada** (`validators/vault_swap_ada.ak`) — keeper-auth staking validator: SwapAda (Tier-1 dual-feed oracle reader; 1h cooldown; validity-range width cap; vault.lovelace floor preserves operational ADA).
6. **vault_protocol** (`validators/vault_protocol.ak`) — keeper-with-fallback staking validator: DeployToProtocol (R71 L-1 min deploy floor; max_deploy_ada 5 ADA; min_vault_ada 10 ADA; SwapAdapter dispatch via `verify_swap_via_adapter`).
7. **vault_recall** (`validators/vault_recall.ak`) — keeper-with-fallback staking validator: RecallFromProtocol, MergeUtxo (R56 M-1 secondary-token allowlist; R73 F-1 admissibility guard).
8. **vault_liqwid** (`validators/vault_liqwid.ak`) — keeper-with-fallback staking validator: SupplyToLiqwid, RecallFromLiqwid (strict semantics with R56 M-3 orphan qToken guard; governance fallback allows partial recall).
9. **vault_gov_policy** (`validators/vault_gov_policy.ak`) — governance-only staking validator: UpdateStrategy (7d), UpdateFee (14d), UpdateFeeSplit (21d), UpdateSlippagePolicy (48h), publish(Deregister).
10. **vault_gov_emergency** (`validators/vault_gov_emergency.ak`) — governance-only staking validator: EmergencyWithdraw (0d immediate, freeze-only), publish(Deregister). R75 C-1 fixed: caller-holds-vUSDCx check now uses canonical `vusdcx_token_name = #"765553444378"` instead of empty asset name.
11. **vault_admin_deploy** (`validators/vault_admin_deploy.ak`) — governance-only staking validator: AdminDeployNonDeposit (7d keeper inactivity + 21d Registry stable + whitelist + SwapAdapter dispatch), publish(Deregister).
12. **keeper_stake_script** (`validators/keeper_stake_script.ak`) — keeper authorization with 3 RegistrationMode (GovernanceOnly / Mixed / PermissionlessWithBond). Weekly round-robin rotation (time-derived modular arithmetic, 7d period, 30-min failover); A-Plain auth (spends keeper_auth UTXO every TX + bumps nonce + updates `last_successful_tx_at`); PostBond / Withdraw / UpdateAuthDatum / SlashBond redeemers; bond-weighted rotation skeleton for Phase 3+.
13. **treasury** (`validators/treasury.ak`) — on-chain 4-category budget. Of the 60% treasury share at launch, sub-allocation **40% audit reserve / 25% operations / 25% R&D / 10% buffer** (audit-reserve accumulation rate = 24% of total fee, same as historical 80%×30% allocation). Receive (4-bucket) + Spend (24h cooldown, monthly cap, audit-floor, invoice-ref) + ReceiveGovForfeit (cross-validator from multisig_gov for forfeited unqualified-signer compensation) + UpdateParams (180d cooldown).
14. **multisig_gov** (`validators/multisig_gov.ak`) — m-of-n governance holding Governance NFT. 7-21d action-dependent timelocks + 1-of-n cancel veto + 37d action TTL cap + `governance_nft == 1` check; RotateSigners (m-of-n, 30d cooldown, min threshold ≥ 3); ReceiveCompoundShare (cross-validator binding for Compound-time gov pool top-up — R72 F-1 enforces this redeemer exclusively for the gov input on Compound); DistributeSignerCompensation (1-of-n, 90-day period); Heartbeat (signer liveness proof); QueueAction emergency branch requires non-empty `target_tx_hash`.
15. **registry** (`validators/registry.ak`) — **9-field datum** (gov policy + gov name + protocol_hashes + stable_tokens + liqwid_markets + asset_oracles + swap_adapter_hashes + last_update_time + keeper_pkh). 3 redeemers: UpdateRegistry (7d timelock + 1h per-update cooldown R40 M-1 + R71 M-1 `keeper_pkh` immutable + R72 F-3 oracle entry caps `max_disagreement_bps ≤ 1000`, `max_staleness_ms ≤ 3_600_000`), KeeperToggleMarket (1h cooldown, keeper unilateral, R71 L-2 `actually_toggled`), FastUpdateMarkets (1h timelock, governance fast-path for Liqwid pool migrations).
16. **order** (`validators/order.ak`) — batched order queue: Process (keeper, enforces slippage + `payout_output_index` + owner-bucket `no_vusdcx_leak` + R75 M-2 `tip_output_idx ≠ payout_output_index` non-aliasing), Cancel (user self-signed, any block), Expire (permissionless after `expires_at`; full-value refund per R65 N-2).
17. **vusdcx** (`validators/vusdcx.ak`) — share token minting policy. Mint bounds R16 H-2; first-deposit cap 10^18 constant (R68 `reasonable_max`); Vault NFT presence check via compile-time anchor (R55).

**NFT Mint Policies (one-shot + soul-bound):**

1. **vault_nft** (`validators/vault_nft.ak`) — one-shot UTXO-ref minting policy for Vault Identity NFT. Parameterized by a specific UTXO reference to guarantee uniqueness; burn branch allowed by token name only (R53 L-3); compile-time anchored in vault_proxy / vusdcx / order (R55 CRITICAL C-1 fix, replaces self-referential datum-field attack surface).
2. **governance_nft** (`validators/governance_nft.ak`) — one-shot UTXO-ref mint, held by multisig_gov.
3. **registry_auth_nft** (`validators/registry_auth_nft.ak`) — one-shot UTXO-ref mint, held by registry.
4. **gov_signer_nft** (`validators/gov_signer_nft.ak`) — soul-bound minting policy for Gov Signer NFTs; reputation-only (non-financial); burnt on rotation-out; tied to Governance NFT policy.

**DEX Adapter (B@launch=1 — ref-script dispatched):**

1. **minswap_v2_adapter** (`validators/minswap_v2_adapter.ak`) — Standalone Minswap V2 SwapAdapter staking validator (~5.0 KB unparameterized). R74 F-1 fix: uses `hop_chain` commitment + on-chain LP-name re-hash via Minswap canonical `compute_lp_asset_name` (sha3_256 of sha3_256-hashed canonically-sorted `(policy, name)` pair); `last_hop_target` exposes target asset. Verified byte-for-byte against Minswap test vectors (ADA/MIN = `82e2b1fd…`) + 3 real mainnet LP names (USDCx/NIGHT, NIGHT/ADA, ADA/DJED). **Post-launch new DEX additions go through governance UpdateRegistry adding a new adapter hash to `registry.swap_adapter_hashes` (cap 10 entries) — no V1 vault redeploy, no depositor migration.**

### VaultDatum (29 fields)

```
VaultDatum {
  // Mutable state (10 fields)
  total_deposited: Int,
  total_shares: Int,
  idle_buffer: Int,
  strategy_allocations: List<Allocation>,
  last_compound_time: Int,
  non_deposit_value: Int,
  frozen: Int,
  last_realloc_time: Int,
  liqwid_positions: List<LiqwidPosition>,
  last_fee_update_time: Int,

  // Policy fields (8 — adjustable via governance with timelocks, value-bounded)
  performance_fee_bps: Int,           // 0-450, UpdateFee 14d timelock, cap 4.5%
  early_withdraw_fee_bps: Int,
  min_hold_seconds: Int,
  buffer_target_bps: Int,             // UpdateStrategy 7d timelock
  keeper_fee_bps: Int,                // launch 4000=40%, cap 4000=40%, UpdateFeeSplit 21d
  gov_fee_bps: Int,                   // launch 0, cap 1000=10%, UpdateFeeSplit 21d (combined keeper+gov ≤ 5000=50%, treasury floor ≥ 50%)
  max_slippage_bps: Int,              // cap 500=5%, UpdateSlippagePolicy 48h
  min_swap_peg_bps: Int,              // window [9300, 9950], UpdateSlippagePolicy 48h

  // Immutable fields (10 — references frozen)
  keeper_pkh: VerificationKeyHash,
  fee_collector: VerificationKeyHash,
  vault_version: Int,
  vusdcx_policy: ByteArray,
  deposit_token_policy: ByteArray,
  deposit_token_name: ByteArray,
  order_script_hash: ByteArray,
  registry_hash: ByteArray,
  registry_auth_policy: ByteArray,
  last_ada_swap_time: Int,            // SwapAda cooldown tracking (mutable index but immutable semantic)

  // Phase 87 Layer 3 dead-man-switch (1 field)
  community_sunset_triggered: Int,    // 0 = not triggered; 1 = CommunitySunset has fired (any vUSDCx holder may invoke after 90d keeper inactivity, opens permissionless DeployToProtocol path for swap-out + 1:1 USDCx exit)
}
```

**Immutable semantics:** "15 immutable fields" means 15 of the 29 datum field references cannot be swapped by any redeemer — the field must remain present with the same type across every state transition (enforced by `check_immutable_fields`). Distinct from **value immutability**: most immutable fields are also value-frozen after deployment, while the 6 policy fields (performance_fee_bps / keeper_fee_bps / gov_fee_bps / buffer_target_bps / max_slippage_bps / min_swap_peg_bps) have immutable field references but values adjustable within hardcoded caps via the two-step governance flow (m-of-n QueueAction → timelock → 1-of-n ExecuteAction, with per-action cooldowns). The 4.5% performance fee cap, 40% keeper share cap, 10% gov pool cap, 50% treasury floor, 5% max slippage cap, and the [93.00%, 99.50%] peg-floor window are all enforced on-chain and cannot be exceeded. R55 moved `vault_nft_policy` out of datum entirely — it is now a compile-time parameter on vault_proxy / vusdcx / order, anchored at deploy time and cannot be changed without a full redeploy.

### Share Token Economics

- **Share price** = `total_deposited / total_shares` (integer division, 1,000,000× multiplier for precision)
- As yield compounds, `total_deposited` increases → share price rises → all holders benefit proportionally.
- **Share multiplier:** 1,000,000× (prevents inflation attack on first deposit)
- **First-deposit cap:** `vUSDCx` mint capped at 10^18 constant (R68 fix — prevents near-full-drain deposit deadlock)
- **Minimum deposit:** 10 USDCx (enforced on-chain in vault_user Deposit)
- **No dilution:** new depositors receive fewer shares at the higher price, ensuring fair distribution.
- **Performance fee:** 4.5% on yield only, never on principal (enforced on-chain at Compound via on-chain yield formula)
- **3-way fee split:** keeper portion → keeper_output_idx (with `extra_signatories[keeper_pkh]` check), gov portion → multisig_gov via ReceiveCompoundShare (R72 F-1 cross-validator binding), remaining → treasury script address (floor 50%)
- **Direct withdraw fee:** 0.1% — physically retained in the vault as share-price yield for remaining holders (deferred yield). Waived after 7-day keeper inactivity.
- **Queue withdraw:** free (processed by keeper in the next batch, ~5 min operational target, not contract SLA)

### Yield Strategy

- **30% Buffer:** USDCx idle in vault for instant withdrawals (0% yield by design — `buffer_target_bps` adjustable via UpdateStrategy)
- **45% Liqwid DJED:** supplied to Liqwid DJED market, ~11.84% APY reference
- **25% Liqwid USDM:** supplied to Liqwid USDM market, ~5.33% APY reference
- **Swap path:** USDCx → DJED/USDM via Minswap V2 multi-hop routes (sim-based route picker with live-pool amountOut comparison, ref-script SwapAdapter dispatch)
- **§5.4 on-chain slippage enforcement** (Phase 1+2 landed, P3-P5 pending 6-12 weeks): Tier-1 oracle fair-price bound (`max_slippage_bps ≤ 500 bps`) and Tier-2 peg-floor bound (`min_swap_peg_bps ∈ [9300, 9950]`)
- **Risk Engine (10 rules):** protocol cap, IL limit, TVL threshold, algo stablecoin cap, APY anomaly, rebalance throttle, buffer reserve, pool depth, dilution penalty, dynamic depth
- **Depeg protection:** CoinGecko + DeFi Llama real price feeds; sustained −5% threshold (15 min) → staged withdrawal; recovery requires $0.98+ sustained for 24h; governance can freeze (`frozen=1`) via EmergencyWithdraw
- **Minimum swap:** $30 (breakeven ≤ 30 days, aligned with Liqwid 30 DJED/USDM min)
- **Dynamic pool depth:** TVL < $500K → 5%, < $1M → 10%, < $3M → 15%, > $3M → 20%

### Phase 1 Three-Layer Governance Safety

V1 launch ships a layered safety design that bounds depositor loss under single-signer governance failure even when SPO co-signers become unavailable:

- **Layer 1 — EmergencyWithdraw freeze-only**: `vault_gov_emergency` redeemer at 0d timelock. Hardened to PRESERVE `total_deposited` + `liqwid_positions`; only flips `frozen` flag. Cannot drain user funds.
- **Layer 2 — Frozen-state USDCx swap-out**: `vault_protocol.DeployToProtocol` allows USDCx-out swaps via SwapAdapter dispatch under frozen state. Lets governance unwind protocol positions to USDCx without unfreezing the vault.
- **Layer 3 — `vault_user.CommunitySunset` 90-day permissionless dead-man-switch**: any vUSDCx holder may invoke after 90 days of `last_compound_time` staleness (R75 L-1 hardened: ignores `last_realloc_time` so keeper zero-yield-Compound spam cannot brick this path). Setting `community_sunset_triggered = 1` opens a permissionless DeployToProtocol path so any actor can complete the swap-out + 1:1 USDCx exit, even if all governance signers are unavailable.

### Security Model

1. **Vault Identity NFT (+ compile-time anchor):** One-shot NFT proves the real vault. Compile-time baked into vault_proxy / vusdcx / order, so attackers cannot inject a fake VaultDatum at the proxy address — the validator verifies the NFT policy matches the compile-time anchor before trusting anything else.
2. **Withdraw-Zero Forwarding Pattern (10-route):** Proxy verifies `withdrawal_count == 1` + continuing output + no foreign VaultDatum; correct staking validator is invoked per route; all accounting happens in the staking validator.
3. **15 Immutable Fields:** Enforced by `check_immutable_fields` helper on every redeemer producing a continuing output.
4. **Anti-Double-Satisfaction:** `receiver_output_idx` hard binding on Withdraw, `fee_output_idx` on Compound, `dest_output_idx` on DeployToProtocol, `payout_output_index` on Order Process (per-order aggregate invariant), R75 M-2 `tip_output_idx ≠ payout_output_index` non-aliasing.
5. **Deferred Early Withdraw Fee:** Withdraw deducts `withdraw_amount` (net of early fee) from both `idle_buffer` and `total_deposited`, so the physical fee raises share price for remaining holders rather than being collected separately.
6. **MultisigGov:** m-of-n QueueAction → 7-21d timelock (action-dependent) → 1-of-n ExecuteAction; 1-of-n CancelAction veto; GovernanceNFT == 1 check; target script must be a spent input; 37d action TTL cap; signer set floor ≥ 3.
7. **Emergency TX-Hash Binding:** `emergency=true` QueueAction requires non-empty `target_tx_hash`, preventing a single m-of-n signature from authorizing arbitrary VaultAdmin operations.
8. **Governance Empty-Hash Delegation (R40 C-1 / R50):** Non-emergency empty `target_tx_hash` allowed with 14-day minimum timelock to handle unavoidable circular dependency. Operator obligations: public broadcast within 1 hour, ≥1 honest signer monitoring, CancelAction veto available throughout 14–30 day window. Signer set must include ≥2 non-colluding parties.
9. **R72 F-1 Cross-Validator Binding:** `vault_keeper_hot.Compound`'s gov_share path verifies the gov input's spend redeemer is exactly `ReceiveCompoundShare`, preventing pairing with any other GovRedeemer that would orphan funds in the gov UTxO.
10. **R72 F-3 Oracle Upper-Bound Caps:** `registry.asset_oracles` entries enforce `max_disagreement_bps ≤ 1000` (10%) and `max_staleness_ms ≤ 3_600_000` (1 hour) — prevents governance from committing degenerate Tier-1 oracle config.
11. **R73 F-1 MergeUtxo Admissibility Guard:** donations that would break `valid_allocs` invariant (`alloc_sum + idle_buffer ≤ total_deposited + non_deposit_value + Σ liqwid_principal`) are rejected at MergeUtxo, so EmergencyWithdraw and AdminDeployNonDeposit cannot be bricked by adversarial donations.
12. **R74 F-1 Minswap V2 hop_chain:** SwapAdapter redeemer commits to `hop_chain` (List<(policy, name)>); adapter verifies each routing hop's LP name = `compute_lp_asset_name(chain[i], chain[i+1])` via canonical Minswap sha3_256-of-sha3_256 formula. Verified byte-for-byte against Minswap's own test vector + 3 mainnet LP names. **Pre-mainnet blocker (closed)**: original draft assumed `lp_asset = (target_asset_policy, target_asset_name)` 2-tuple but Minswap's actual format is single `Constr(0, [LP_policy, LP_name])` — every real Minswap V2 order would have been rejected.
13. **R75 C-1 vUSDCx Asset-Name Fix:** `vault_user.CommunitySunset` caller-holds-vUSDCx check now uses canonical `vusdcx_token_name = #"765553444378"` (was empty asset name → permanent False → dead-man-switch un-invokable).
14. **R75 L-1 Sunset Trigger-Time:** `validate_community_sunset_trigger_time` reads ONLY `last_compound_time`, not `max(last_compound_time, last_realloc_time)`. Prevents compromised keeper from spamming zero-yield Compound TXs to keep `last_realloc_time` fresh and brick the dead-man-switch.
15. **R75 L-4 NoDatum Branch Hardening:** vault_proxy NoDatum branch enforces `withdrawal_count == 1` inline, second line of defense beyond the primary VaultDatum branch fold.
16. **On-Chain Yield Computation:** `yield = idle_buffer + non_deposit_value + Σ liqwid_positions.supplied_value − total_deposited`. Keeper cannot fake yield; formula is derived entirely from on-chain state.
17. **Liqwid Position Tracking (R35):** per-market `LiqwidPosition { market_id, qtokens_held, supplied_value }` prevents qToken rate inflation attacks. Subset invariant on EmergencyWithdraw clear (R42 B1-M1).
18. **NDV Stable-Token Allowlist (R40):** `DeployToProtocol` and `RecallFromProtocol` only modify `non_deposit_value` for tokens in `registry.stable_tokens`.
19. **MergeUtxo Secondary Token Allowlist (R56 M-1):** Only accepts NoDatum UTXOs containing {ADA, deposit_token, registry.stable_tokens}; blocks garbage-token donation attacks.
20. **Buffer / NDV Floors (R56 M-2):** `idle_buffer >= 0` and `non_deposit_value >= 0` enforced on every redeemer that mutates them.
21. **Symmetric Token Preservation (R57 F-1):** `verify_all_tokens_preserved` includes `no_garbage_tokens` fold, symmetric with `verify_other_tokens_preserved` — blocks rogue-policy-grind attacks on RebalanceBuffer / UpdateStrategy / UpdateFee.
22. **Validity-Range Width Caps (R58 F-1):** Every time-writing redeemer (Compound / UpdateFee / UpdateRegistry / RotateSigners / governance) enforces `upper - now <= 1h` width cap — blocks keeper far-future time-writing attack.
23. **Compound Cooldown:** minimum interval + zero-yield allocation-only compound (R29) + buffer-funded Compound with `liqwid_positions == []` guard (R52 M-1) + loss compound support (R33, negative yield with fee=0).
24. **Role Separation:** Governance (m-of-n SPO signers), Keeper, Fee-collector, Ref-deployer — strictly separated keys and on-chain permission boundaries (6 distinct identities at mainnet launch).
25. **Keeper Cannot Touch Governance:** only Compound, RebalanceBuffer, BatchProcess, MergeUtxo, SupplyToLiqwid, RecallFromLiqwid (keeper-path), DeployToProtocol, RecallFromProtocol, SwapAda.
26. **Governance Cannot Drain USDCx or ADA:** only stranded non-deposit tokens via AdminDeployNonDeposit, gated by 7-day keeper inactivity + 21-day Registry stable + whitelist check (R30).
27. **Fee Hard Caps:** `performance_fee_bps <= 450` (4.5%) + `keeper_fee_bps <= 4000` (40%) + `gov_fee_bps <= 1000` (10%) + `keeper + gov <= 5000` (50%, treasury floor ≥ 50%) + `max_slippage_bps <= 500` (5%) — all enforced on-chain.
28. **Emergency Escape:** 7-day keeper inactivity triggers automatic fee waiver on direct Withdraw + permissionless RecallFromProtocol path.
29. **90-Day Permissionless Dead-Man-Switch:** `vault_user.CommunitySunset` (Phase 87) — any vUSDCx holder may trigger after 90d staleness, opens permissionless USDCx exit even if all governance signers are unavailable.
30. **Registry Auth NFT:** prevents fake registry UTXO injection at the registry script address.
31. **Registry Timelocks:** 7d governance timelock + 1h per-update cooldown; keeper can KeeperToggleMarket unilaterally (1h) for emergency market pause; governance FastUpdateMarkets (1h) for Liqwid pool migrations.
32. **Slippage Protection:** token-specific `min_receive` enforced on-chain in Order Process; BatchProcess mint/burn ratio exact-match (R53 M-1/M-2 — no ±1 surplus MEV); §5.4 on-chain caps in VaultDatum.
33. **Full Drain Safety:** vault destruction path requires `allocs_empty && NDV==0 && liqwid_positions==[] && no_continuing_output + Vault NFT burn (R56 L-2)` — prevents phantom-vault shell after drain.

### V1-Specific Features (beyond internal verification heritage)

- **3-way Compound fee split:** launch 40% keeper / 0% gov / 60% treasury; caps keeper ≤ 40% / gov ≤ 10% / combined ≤ 50% / treasury floor ≥ 50%. Keeper share at validator hard cap to support open-source third-party keeper viability under public-goods positioning. keeper_fee_bps portion → keeper_output_idx (with `extra_signatories[keeper_pkh]` check), gov_fee_bps portion → multisig_gov via R72 F-1 cross-validator binding, remaining → treasury script address.
- **UpdateFeeSplit 21-day timelock:** longest of any governance action; self-dealing protection (prevents gov signers from raising gov_fee_bps faster than depositors can exit)
- **UpdateSlippagePolicy 48-hour timelock:** balances depeg-response agility with depositor exit window; 1-of-n cancel preserved; 1-hour validity-range width cap
- **Three-way governance partition (vault_gov_policy / vault_gov_emergency / vault_admin_deploy):** response-latency boundary partition isolates immediate-action emergency path from policy-change queue and from admin-only operations. Future policy feature additions cannot inadvertently expand emergency-path attack surface.
- **Phase 1 three-layer governance safety:** Layer 1 EmergencyWithdraw freeze-only / Layer 2 frozen-state USDCx swap-out via DeployToProtocol / Layer 3 `vault_user.CommunitySunset` 90-day permissionless dead-man-switch.
- **Weekly keeper rotation:** time-derived modular arithmetic over signer list, 7d period, 30-min failover window; bond-weighted activates at Phase 3+ when RegistrationMode flips to Mixed/Permissionless
- **A-Plain keeper authorization:** every keeper TX spends keeper_auth UTXO + bumps nonce + updates `last_successful_tx_at`; keeper_stake_script allows fallback to governance after 7d keeper inactivity
- **Quarterly governance compensation:** signer_compensation_pool accumulates per Compound, distributed via DistributeSignerCompensation (1-of-n) every 90 days
- **X3 hybrid qualification:** signer qualifies if full-quarter tenure AND (signed ≥1 gov TX OR Heartbeat)
- **Y1 forfeit flow:** unqualified signer share → Treasury audit_reserve (via ReceiveGovForfeit cross-validator binding)
- **Soul-bound Gov Signer NFT:** reputation-only, tied to Governance NFT policy, burnt on rotation-out; carries no financial claim
- **Treasury on-chain:** 4-category budget. Of the 60% treasury share at launch, sub-allocation **40% audit reserve / 25% operations / 25% R&D / 10% buffer** (audit-reserve accumulation rate = 24% of total fee). 24h spend cooldown, monthly cap, audit-floor, invoice-ref discipline, UpdateParams 180d cooldown.
- **SwapAda closed-loop ADA replenishment:** vault.lovelace < 15 ADA triggers oracle-priced ADA-for-USDCx barter; vault receives 10-50 ADA; 1h cooldown + width cap; avoids founder/keeper out-of-pocket top-ups that happened during internal verification. Inactive at V1 launch until governance populates `registry.asset_oracles` ADA entry.
- **B@launch=1 SwapAdapter architecture:** ref-script dispatched DEX adapters (`registry.swap_adapter_hashes` cap 10). Post-launch new DEX additions go via UpdateRegistry 14d timelock — no V1 vault redeploy. Launch ships `minswap_v2_adapter` only.

### Testing & Auditing

- **235 Aiken unit + property tests / 730 randomized checks** pass per `aiken check` run (8 property tests × up to 100 iterations + deterministic cases including R72 + R73 + R74 regression coverage; R74 alone adds 24 inline tests in `minswap_v2_adapter` plus 10 structural tests in `tests/r74_test.ak`)
- **Keeper test suite** — vitest: compound, batch, deploy, recall, rebalance, depeg, settlement, governance, self-healing auto-recovery (lives in `optivaults-reference` operator repo)
- **API test suite** — vitest: auth, security, endpoints, CBOR validation
- **Frontend test suite** — vitest: UI / slippage protection / CBOR blind-sign defense
- **Preprod ceremony executed end-to-end** — 38 TX per ceremony: 3 NFT mints + 18 ref scripts + 12 stake-credential registrations + 5 state UTxOs all confirmed on-chain. Two ceremonies live: `v1-postphase77d-preprod` (2026-04-22) and `v1-preprod-p3` (2026-04-23). Both built with shortened timelocks for iteration speed; constants subsequently restored to production values for the mainnet candidate.
- **A2 gov-gated stake deregister Preprod E2E verified** — Queue → timelock → Execute with on-chain Deregister cert; all 12 stake-credential deposits reclaimable at sunset via governance-gated Deregister.
- **Preprod on-chain E2E coverage** — Deposit, Compound (zero-yield + buffer-funded), Withdraw (deferred-yield share-price accrual), MergeUtxo (positive paths + 2 negative-path rejection), Donation (ADA / deposit token / multi-secondary), DeployToProtocol, SupplyToLiqwid, RecallFromLiqwid, KeeperToggleMarket, FastUpdateMarkets, governance Queue/Execute/Cancel/Rotate flows, A2 gov-gated stake deregister — all verified on-chain via Blockfrost-only mode
- **Multi-round internal audit review** — internal findings addressed; recent rounds R72 (cross-validator binding) + R73 (MergeUtxo admissibility) + R74 (Minswap V2 LP-name format, HIGH) + R75 (CommunitySunset asset-name + sunset trigger-time + tip aliasing + NoDatum hardening) all closed; V1-specific internal audit (coverage areas A-F, not round numbers) + Q2-Q3 2027 third-party audit pending before public launch
- **Audit cost range:** $50K-$150K (sourced to 2025-2026 public pricing indications from Anastasia Labs / MLabs / Certik-Cardano / TxPipe Plutus V3 engagements)
- **Attack vectors tested:** inflation, flash loan, sandwich, double-satisfaction, datum manipulation, unauthorized mint/burn, staking credential redirect, ADA/token confusion, phantom buffer, phantom vault (closed by compile-time NFT anchor), phantom vUSDCx via self-referential datum NFT (closed by compile-time anchor), allocation wipeout, compound time tampering, idle_buffer bricking, NDV griefing, keeper timer reset, governance bypass, qToken rate inflation, Registry `keeper_pkh` de-sync, DeployToProtocol dust-drain, vUSDCx leak via same-owner multi-orders, BatchProcess rounding surplus MEV, value-range width exploit, Compound gov-share orphaning (R72 F-1), MergeUtxo donation admissibility break (R73 F-1), Minswap V2 LP-name format mismatch (R74 F-1), CommunitySunset asset-name brick (R75 C-1), zero-yield Compound spam to brick sunset (R75 L-1)

### Technical Stack

- **Smart Contracts:** Aiken (PlutusV3) v1.1.x + stdlib v3.0.0 + fuzz v2.2.0
- **Backend/Keeper:** Node.js, TypeScript, CML TX Builder (bypasses Lucid Evolution mint bugs + Conway ref-script fee bug). Lives in `optivaults-reference` (operator repo).
- **API:** Express + vitest, Blockfrost-only mode (with optional Ogmios/Kupo fallback), 5-key Blockfrost rotation + session script cache
- **Frontend:** React 19, TypeScript, Vite 8, Tailwind CSS v4
- **Wallet Integration:** CIP-30 (client-side signing only, server-side TX building — no Lucid/WASM in browser)
- **Deployment:** Cloudflare Pages (frontend + landing)

### DEX Integrations

- **Liqwid Finance** — stablecoin lending, per-market action validators for DJED / USDM / USDCx (min 30 DJED / USDM); pool-shard migration handled via FastUpdateMarkets (1h) — no 7-14 day waits for governance to update action_addr_hash
- **Minswap V2** (`c3e28c36...`) — multi-hop stablecoin swaps (USDCx ↔ DJED, USDCx ↔ USDM); routed via `minswap_v2_adapter` ref-script SwapAdapter (R74 F-1 hop_chain commitment + canonical LP-name re-hash); asset-pair-based pool lookup is immune to pool migration / parallel pool variants
- **Post-launch DEX additions** — governance UpdateRegistry adds new SwapAdapter hash to `registry.swap_adapter_hashes`; 14d timelock; no V1 vault redeploy

## License

**Apache License 2.0** (permissive open-source, OSI-approved). Allows fork, commercial use, competitive offerings, with minimal restrictions (attribution + license notice preserved).

## Deployment Status

### V1 Public Launch
**Status:** pre-launch. Design + Aiken implementation complete; keeper TypeScript reference + Preprod E2E TS scripts (16 scripts published in `optivaults-reference`) + V1-specific internal audit coverage areas A-F + external audit engagement all pending before mainnet ceremony. External audit target Q2-Q3 2027; public launch gated on audit pass. Pre-audit 100K USDCx TVL cap will be operator-enforced at public launch.

### Preprod
- V1 Preprod ceremonies executed end-to-end: Vault NFT + Governance NFT + Registry Auth NFT mints + 18 ref scripts + 12 stake-credential registrations + 5 state UTxOs all confirmed on-chain. Two live ceremonies: `v1-postphase77d-preprod` (2026-04-22) and `v1-preprod-p3` (2026-04-23).
- A2 gov-gated stake deregister Preprod E2E verified: Queue → timelock → Execute with on-chain Deregister cert; all 12 stake-credential deposits reclaimable at sunset via governance.

## Hosted Services

- Landing: https://optivaults.app
- App + emergency-withdraw launch with V1 public launch (post external audit).

## Languages

This protocol supports English, Traditional Chinese (繁體中文), and Japanese (日本語).

- English: https://optivaults.app/?lang=en
- 繁體中文: https://optivaults.app/?lang=zh
- 日本語: https://optivaults.app/?lang=ja
- Chinese LLM reference: https://optivaults.app/llms-zh.txt
- Japanese LLM reference: https://optivaults.app/llms-ja.txt
- Short English LLM reference: https://optivaults.app/llms.txt

## Links

- Website: https://optivaults.app
- Source: https://github.com/OptiVaults/optivaults-protocol
- Whitepaper EN: https://github.com/OptiVaults/optivaults-protocol/blob/v1/whitepaper/whitepaper.md
- Whitepaper 繁中: https://github.com/OptiVaults/optivaults-protocol/blob/v1/whitepaper/whitepaper-zh-TW.md
- V1 Design Tree: https://github.com/OptiVaults/optivaults-protocol (branch `v1`)
- Security Policy: https://github.com/OptiVaults/optivaults-protocol/blob/v1/SECURITY.md
- Email: optivaults@gmail.com
- License: Apache License 2.0 (permissive open-source, OSI-approved)