diff --git a/README.md b/README.md index 3c3fdfb..b9a0293 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,18 @@ pnpm --filter @reineira-os/escrow test # Test escrow only pnpm --filter @reineira-os/recourse test # Test recourse only ``` +## Documentation + +| Document | Description | +| ------------------------------------------------------ | ------------------------------------------------------------------ | +| [Whitepaper](docs/ReineiraOS-Whitepaper.pdf) | Protocol design and primitive definitions (cited as `§X` in code). | +| [Litepaper](docs/ReineiraOS-Litepaper.pdf) | Condensed overview. | +| [Implementation Status](docs/IMPLEMENTATION-STATUS.md) | What is shipped, partial, and planned vs. the whitepaper. | + +The protocol is **testnet · pre-audit · upgradeable** and not yet +feature-complete — see [Implementation Status](docs/IMPLEMENTATION-STATUS.md) +before relying on any whitepaper section. Full docs: [docs.reineira.xyz](https://docs.reineira.xyz). + ## License This repository is multi-licensed by layer — see [LICENSE](LICENSE) and [NOTICE](NOTICE): diff --git a/docs/IMPLEMENTATION-STATUS.md b/docs/IMPLEMENTATION-STATUS.md new file mode 100644 index 0000000..d027749 --- /dev/null +++ b/docs/IMPLEMENTATION-STATUS.md @@ -0,0 +1,93 @@ +# Implementation Status + +> **Maturity: testnet · pre-audit · upgradeable.** The protocol is under active +> development and is **not yet feature-complete**. This document is the +> authoritative record of what is implemented, what is partial, and what is +> still planned, mapped to the whitepaper. It exists so that the relationship +> between the specification and the deployed code is explicit rather than +> assumed. Where this document and the whitepaper disagree, **this document +> describes the code; the whitepaper describes the design intent.** + +**Last reviewed:** 2026-06-15 + +## How to read this + +| Status | Meaning | +| -------------- | ------------------------------------------------------------------------------ | +| ✅ Implemented | Contracts/services exist and carry test coverage. Pre-audit; not yet hardened. | +| 🟡 Partial | The interface and wiring exist, but the production logic is a stub or mock. | +| ⏳ Planned | Specified in the whitepaper; not yet started in this repo. | + +"Pre-audit" applies to **everything** below: no contract in this repository has +completed an external security audit, and all core contracts are UUPS-upgradeable +on testnet. Treat every line as subject to change. + +## By package + +| Package | Status | Notes | +| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ | +| `@reineira-os/shared` | ✅ Implemented | Base contracts, interfaces, and mocks shared across packages. | +| `@reineira-os/escrow` | ✅ Implemented | Confidential FHE escrow + CCTP V2 cross-chain USDC. Core settlement paths covered by tests. | +| `@reineira-os/recourse` | 🟡 Partial | Pools, factory, registry, coverage manager, and router ship; underwriter policy and LP rewards do not (see below). | +| `@reineira-os/orchestration` | 🟡 Partial | Operator registration, staking, tasks, fees, and slashing are in progress — not yet finished. | +| `@reineira-os/operators` | 🟡 Partial | Off-chain operator infrastructure (NestJS) — in progress, not yet finished. | +| `@reineira-os/sdk` | ✅ Implemented | TypeScript client for the protocol. | + +## By whitepaper section + +| § | Area | Status | Notes | +| ----- | ---------------------------- | -------------- | ------------------------------------------------------------------------------ | +| §5 | Reineira Settlement Standard | ✅ Implemented | Open RSS interfaces present. | +| §6 | Escrow engine | ✅ Implemented | Confidential escrow + cross-chain settlement. | +| §7.2 | Recourse pool roles | ✅ Implemented | Pool Creator / Manager / LP roles enforced in plain and confidential pools. | +| §7.10 | Underwriter policy | 🟡 Partial | `IUnderwriterPolicy` is pluggable; only mocks ship. No production risk model. | +| §7.x | LP reward accounting | 🟡 Partial | `pendingRewards()` / `claimRewards()` are stubs (see Known gaps). | +| §8 | Operator network | 🟡 Partial | On-chain staking/tasks/fees/slashing and off-chain services both in progress. | +| §9 | Cross-chain (L2/L3) | 🟡 Partial | CCTP V2 USDC paths ship; full L3 graduation path is roadmap. | +| §10 | Security | 🟡 Partial | ReentrancyGuard, access control, replay protection in place; **no audit yet.** | +| §11 | Governance | ⏳ Planned | Ownable/UUPS today; decentralized governance is future work. | +| §12 | Tokenomics | ⏳ Planned | No token. Described as design intent only. | +| §13 | Licensing | ✅ Implemented | Per-layer licensing live — see [LICENSE](../LICENSE) / [NOTICE](../NOTICE). | + +## Known gaps + +These are the items most likely to surprise a reviewer reading the code against +the whitepaper. They are disclosed deliberately. + +1. **Underwriter policy is pluggable but not yet filled in (§7.10).** + The `recourse` package ships the `IUnderwriterPolicy` interface and mocks + (`MockUnderwriterPolicy`, `MockConfidentialUnderwriterPolicy`) that return a + stored constant for `evaluateRisk()` / `judge()`. There is **no production + risk-scoring or dispute policy** in this repository yet. Pools accept any + `IUnderwriterPolicy`-conforming contract; supplying a real one is the work + that remains. + +2. **LP reward accounting is a stub (§7.x).** + `pendingRewards()` returns `0` (`_encryptedZero` in the confidential pool) and + `claimRewards()` validates ownership and emits `RewardsClaimed` **without + transferring any value**. Premium distribution to LPs is not yet implemented. + Manager premium withdrawal (`claimPremiums`) is implemented. + +3. **Capital model is a single flat pool.** + Pools hold one undifferentiated capital bucket. Tranching / waterfall + seniority described as design intent is not implemented. + +4. **Operator network is still in progress (§8).** + Both the on-chain `orchestration` package (registration, staking, tasks, + fees, slashing) and the off-chain `operators` services are under active + development and are not yet feature-complete. + +5. **No external audit.** + No contract here has been audited. All core contracts are upgradeable on + testnet. Do not treat any deployment as production-grade. + +## How this is published + +This file is the engineering-level record that travels with the code. The same +readiness picture is intended to be reflected, in product language, in: + +- the **whitepaper** (an Implementation Status / roadmap note), and +- **[docs.reineira.xyz](https://docs.reineira.xyz)** (a public status page). + +If you find a discrepancy between the code and any of these surfaces, that is a +bug in the documentation — please open an issue. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..40d6448 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# Documentation + +Canonical specification and reference documents for the ReineiraOS protocol. + +## Papers + +| Document | In this repo | Canonical (hosted) | +| ---------- | -------------------------------------------------------- | ---------------------------------------------- | +| Whitepaper | [ReineiraOS-Whitepaper.pdf](./ReineiraOS-Whitepaper.pdf) | https://reineira.xyz/ReineiraOS-Whitepaper.pdf | +| Litepaper | [ReineiraOS-Litepaper.pdf](./ReineiraOS-Litepaper.pdf) | https://reineira.xyz/ReineiraOS-Litepaper.pdf | + +The whitepaper is the document referenced throughout the contract NatSpec (e.g. +`whitepaper §7.2`, `§7.10`). The in-repo copy is the snapshot that the code in +this commit was written against; the hosted copy at +[reineira.xyz](https://reineira.xyz) is the latest published version. + +## Status + +- [IMPLEMENTATION-STATUS.md](./IMPLEMENTATION-STATUS.md) — what is shipped, + what is partial, and what is still on the roadmap, mapped to whitepaper + sections. **Read this before assuming any whitepaper section is fully + implemented.** + +Full developer documentation is published at +[docs.reineira.xyz](https://docs.reineira.xyz). diff --git a/docs/ReineiraOS-Litepaper.pdf b/docs/ReineiraOS-Litepaper.pdf new file mode 100644 index 0000000..957080b Binary files /dev/null and b/docs/ReineiraOS-Litepaper.pdf differ diff --git a/docs/ReineiraOS-Whitepaper.pdf b/docs/ReineiraOS-Whitepaper.pdf new file mode 100644 index 0000000..4756932 Binary files /dev/null and b/docs/ReineiraOS-Whitepaper.pdf differ