Active development branch:
v1. Matches the siblingoptivaults-protocolconvention — nomainbranch.
This repository holds the V1 operator-layer reference implementation — the off-chain code needed to run an OptiVaults V1 instance: keeper, frontend (with in-browser TX building), and self-serve recovery tools.
It is the companion of optivaults-protocol, which holds the Aiken smart contracts, protocol specification, whitepaper, and deploy pipeline.
OptiVaults V1 is deliberately structured as two separable layers:
| Layer | Repo | What it is | Fee |
|---|---|---|---|
| Protocol layer (public good) | optivaults-protocol |
Aiken validators + spec + whitepaper + deploy scripts. Apache 2.0. Anyone may fork and launch their own vault without paying anything. | 0% — pure public good. |
| Operator layer (this repo) | optivaults-reference |
Reference TypeScript implementation of the keeper, frontend, CLI tools. Apache 2.0. Runs a live vault instance on behalf of users via optivaults.app. |
4.5% of realised yield (hard-capped in the contract; at V1 launch 40% to keeper / 0% to gov pool / 60% to treasury; see fee breakdown). |
Why two repos? Because these are two fundamentally different things:
- The protocol layer is a piece of Cardano DeFi commons — auditable, fork-able, Apache 2.0, with zero rent extraction. Any team anywhere may use it.
- The operator layer is a convenience service — a live vault instance users can deposit into without running their own infrastructure. The 4.5% fee funds the cost of keeping it running: keeper compensation, VPS + Blockfrost + monitoring + CDN, future third-party audits, protocol R&D, and a buffer for incidents. No founder dividend; no investor return; no token.
The two layers are connected at the contract level (the operator-run keeper signs transactions that the on-chain vault validates), but they are not the same thing. Forking optivaults-protocol and running your own instance — with your own fee structure, or zero fee — is an explicit design goal.
See the OptiVaults whitepaper for the depositor-facing framing and the product-overview.md for a plain-language walkthrough.
V1 is a pre-launch repo. The operator layer is being adapted from the internal-verification-era codebase. Current state:
| Component | Status | Notes |
|---|---|---|
keeper/ |
🚧 Placeholder | V1 keeper reference implementation coming post keeper-verification milestone. TypeScript, vitest-tested. |
frontend/ |
✅ Published | React 19 + Vite 8 + TailwindCSS v4 SPA. CIP-30 wallet integration, in-browser TX building via Lucid Evolution (no separate API server — the previous api/ component has been folded into the frontend client-side), Blockfrost direct REST, vitest tests. 7 pages with EN / zh-TW / ja i18n. Operator-specific URLs + Cloudflare Pages deploy script flagged in frontend/README.md for forkers. |
withdraw-cli/ |
✅ Published | Node CLI for self-serve Withdraw (no infrastructure dependency). |
emergency-withdraw/ |
✅ Published | Static HTML self-serve emergency-withdraw tool — in-browser, no backend dependency. English / zh-TW / ja i18n. |
Remaining components will be added in batches as each is verified V1-ready against the on-chain contracts.
OptiVaults is designed so that any team can fork the protocol and launch their own vault instance. The flow:
- Fork
optivaults-protocol(or use the published artefacts as-is). - Run the ceremony in
optivaults-protocol/deploy/(see deploy/runbooks/v1-mainnet-ceremony.md) to deploy your own vault address + reference scripts. - Fork this repo (
optivaults-reference), configure the keeper / frontend against your ceremony state, deploy where you want (or don't — you can run entirely locally and skip hosted infrastructure for your own use). - Operate under your own policy: your own fee rate, your own governance signer set, your own depositor base.
Your instance is independent of the OptiVaults-operated instance. The two will never interact except by convention (e.g., both following the same optivaults-protocol hash set).
The operator instance run by OptiVaults (at optivaults.app) is funded by the contract-enforced 4.5% performance fee. V1-launch breakdown (see economics.md for full math):
- 40% of fee → signing keeper (covers operational cost per Compound; set at the validator hard cap to support open-source third-party keeper viability)
- 0% of fee → governance signer pool (disabled at V1 launch; activated in Phase 2+ via
UpdateFeeSplit, capped at 10%) - 60% of fee → on-chain treasury, sub-allocated 40 / 25 / 25 / 10 at launch (governance-adjustable within bounds):
- 40% audit reserve
- 25% operations (platform layer — VPS, Blockfrost, monitoring, CDN; per-keeper infra is funded directly out of the keeper's 40% share)
- 25% R&D (future integrations, contributor bounties, ecosystem grants)
- 10% buffer (unexpected costs, legal, incident response)
Hard caps enforced in the contract: keeper_fee_bps ≤ 4000 (40%), gov_fee_bps ≤ 1000 (10%), keeper + gov ≤ 5000 (treasury floor ≥ 50%); each treasury sub-category bps ∈ [0, 5000] (no single category may exceed 50% of treasury inflow); min_audit_reserve is an absolute USDCx floor set immutably at deploy. The 4.5% performance-fee rate is itself hard-capped in the contract and cannot be raised by governance under any redeemer path.
No founder dividend. No investor return. No token issuance. No SAFE / SAFT. The 4.5% fee is pure cost-recovery + long-term protocol sustainability; the specific split is disclosed on-chain via TreasuryDatum and in the treasury's recent_spend_log.
All protocol-level security findings, contract audits, economics documentation, and whitepaper content live in optivaults-protocol.
This repo's scope is strictly the off-chain operator instance code. Security disclosures specific to operator infrastructure (keeper runtime bugs, frontend XSS / CSP issues, CLI parsing bugs) go to the disclosure channels in this repo's SECURITY.md. Protocol-level security disclosures (contract exploits, datum injection, etc.) go to optivaults-protocol/SECURITY.md.
If you're unsure which layer a finding applies to, default to optivaults-protocol's disclosure channel — the triage process will forward appropriately.
Apache License 2.0. See LICENSE. Forks are welcome and encouraged.
The permissive license is deliberate. One of V1's stated success criteria is "the architecture is forked and specialized by other Cardano teams" — restrictive licensing on an operator reference implementation would contradict that goal.
- Website: optivaults.app
- Protocol repo: github.com/OptiVaults/optivaults-protocol
- Security disclosure: See
SECURITY.mdfor this repo's scope; protocol-layer findings go tooptivaults-protocol/SECURITY.md - General: Discord (invite on optivaults.app)