oy/openyield
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 42 Wiki Activity

docs(P03): complete freeholders docs + reference phase — REQ-027 complete

Browse Source 
P3 complete. 8 docs/freeholders/ pages (signals, standing, stands-guilds,
councils-voice, bonds, partner-spectrum, anchor-preview, index) + 2
docs/reference/ pages (architecture, components). Docs firewall green
across all 26 docs pages. Full docs deliverable (README + mkdocs.yml +
26-page site) complete — REQ-027 complete.

---ci---
project: oy
phase: 3
milestone: v0.3
status: complete
tag_base: v0.2.x
phase_role: execution
requirements:
  covered: [REQ-027]
  partial: []
---/ci---
This commit is contained in:
cloudinit-bot
2026-08-17 22:17:07 +00:00
parent e493216b8a
commit 2ef3f2e39f
10 changed files with 476 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/architecture.md
+51
View File
@@ -0,0 +1,51 @@
# Architecture
This is the architecture index for OpenYield. The mesh is built from 14
modular components and 6 cross-component interfaces, with a critical blocker
chain that fixes the build order. The full governance source lives in
`.ciagent/oy/ARCHITECTURE.md`; this page is the user-facing rewrite, kept
lexicon-clean by the [docs firewall](../shared/lexicon.md).
## The 14 modular components
| # | Component | Vision § | Phase |
|---|---|---|---|
| 1 | OY Chain & Mirror | §7 | P1 |
| 2 | Cross-Chain & Exit | §7 | P3 |
| 3 | Bread Unit & Root Basket | §6, §16 | P1 |
| 4 | Bloom Engine | §6 | P1 |
| 5 | Storage Substrate | §5 | P1 |
| 6 | Identity, Standing & Citizenship | §8, §9 | P1 |
| 7 | Window Primitive | §10 | P2 |
| 8 | Pacts Suite (Pause, Ground, Stance, Cover, Stand Registry, Hub API, Bonds) | §16, §17 | P2 |
| 9 | Mesh Experience (Maps, Pay) | §8 | P1 |
| 10 | Organizational Primitives (Stands, Guilds) | §11, §12 | P2 |
| 11 | Partner Spectrum & Forex | §13 | P2 |
| 12 | Bearers & Processing Mesh | §14, §15 | P1 |
| 13 | Fee Covenant | §18 | P1 |
| 14 | Governance (Mesh/Guild/Stand Councils) | §19 | P2 |
## The 6 cross-component interfaces
1. **Standing API** — consumed by Identity, Window, Pacts, Orgs, Partners,
and Governance. See [Standing](../freeholders/standing.md).
2. **Forge / Fold Interface** — mints [Bread](../shared/bread-scale.md)
against Root Basket assets only. See the Bloom Engine.
3. **Watcher Attestation Interface (the Mirror)** — 9 Watchers, 6-of-9
quorum. See [Watchers & Mirror](../shared/watchers-mirror.md).
4. **Window Lifecycle Interface** — Holder-authorized, scope-bounded,
revocable. See [Window](../nomads/window.md).
5. **Fee Covenant Interface** — auto-decline, ceiling/floor enforced.
See [Six Principles](../shared/six-principles.md).
6. **Voice / Council Interface** — multi-source Voice, Mission Lock enforced.
See [Councils & Voice](../freeholders/councils-voice.md).
## The critical blocker chain
The components build in a fixed order: OY Chain (1) → Bread/Root Basket (3)
→ Storage (5) → Identity/Standing (6), which then unblocks {Window (7),
Pacts (8), Orgs (10), Partners (11), Governance (14)}. The Fee Covenant (13)
blocks Pacts, Orgs, Partners, and Bearers — the fee shape must exist before
any of those can ship. v0.3 adds the Cross-Chain & Exit layer (component 2)
and the Bearers/Partner/Bond extensions; see [Components](components.md) for
the `x/` module map and the v0.3 phase status.
docs/reference/components.md
+62
View File
@@ -0,0 +1,62 @@
# Component Map
This is the `x/` module map for OpenYield. Each module is a Cosmos-SDK-style
`x/<name>/types/` package, zero external Go deps (G-006), referenced by
ID-string across modules (G-003 — no struct imports). The map covers v0.1,
v0.2, and v0.3 (skeleton + tests depth, D-020/D-035).
## v0.1 baseline (pre-MVP skeleton)
| Module | Vision § | REQ | Purpose |
|---|---|---|---|
| `x/mesh` | §7 | REQ-008 | OY Chain (Layer 1) shell |
| `x/mirror` | §7 | REQ-004 | Mirror of canonical state to bearers |
| `x/bread` | §4, §6 | REQ-013 | Bread unit + 11-tier scale |
| `x/bloom` | §6 | REQ-003 | Bloom Engine (real production only) |
| `x/forge` | §4.2 | REQ-003 | Forge/Fold minting against Root Basket |
| `x/rootpool` | §5 | REQ-014 | Root-Pool (mesh treasury) |
| `x/stash` | §5 | REQ-014 | Stash (Holder-level storage pool) |
| `x/vault` | §5 | REQ-014 | Vault (Stand-level storage pool) |
| `x/identity` | §8 | REQ-005 | Reach identity (Holder, no KYC) |
| `x/standing` | §9.2 | REQ-006 | Bayesian Standing |
| `x/processing` | §15 | REQ-007 | FCFS processing mesh |
| `x/watcher` | §7 | REQ-004 | 9 Watchers, 6-of-9 quorum |
| `x/feecovenant` | §18 | REQ-002 | Fee ceiling/floor/minimum |
| `x/still` | §3 | — | Still/Stir pause/resume state |
| `x/bearers` | §14 | REQ-019 | Unified Bearer Layer (6 bearers) |
## v0.2 (The Mesh — skeleton + tests)
| Module | Vision § | REQ | Purpose |
|---|---|---|---|
| `x/window` | §10 | REQ-015 | Window primitive (scope, rate-limit, revoke) |
| `x/stand` | §11 | REQ-016 | Nine Stand types |
| `x/guild` | §12 | REQ-017 | Guilds + Hand-Passes at 0% protocol fee |
| `x/pact` | §16 | REQ-020 | Six Pacts (Pause, Ground, Stance, Cover, Stand Registry, Hub API) |
| `x/partner` | §13 | REQ-018 | Four-tier Partner Spectrum (Op, Master Op, Pier, Anchor) |
| `x/council` | §19 | REQ-011 | Three Councils + Mission Lock (non-amendable) |
| `x/forex` | §13 | Forex v1 | Forex Engine v1 (pair type + oracle interface) |
| `x/bond` | §17 | REQ-021 | Mesh Bond Market (8% cap / 0% floor clamp) |
| `x/satellite` | §7 | REQ-009 | L2 IBC Satellite (Polygon active + 4 stubs) |
## v0.3 (Bearers & Documentation — in progress)
| Module | Vision § | REQ | Status | Purpose |
|---|---|---|---|---|
| `x/bridge` | §7 | REQ-010 | P4 (pending) | L2↔L1 bridge routes |
| `x/exit` | §7 | REQ-010 | P4 (pending) | Exit routes + DEX swaps |
| `x/bearers` (ext) | §14 | REQ-022 | P4 (pending) | OY-SAT + OY-QR transport stubs |
| `x/partner` (ext) | §13 | REQ-023 | P4 (pending) | AnchorCredential (Anchor tier) |
| `x/hub` | §13, §16 | REQ-024 | P5 (pending) | Hub API (Custody, Lending, Compliance) |
| `x/services` | §13 | REQ-025 | P5 (pending) | Services (Care, SIM, Vault, Mail) |
| `x/bond` (ext) | §17 | REQ-026 | P5 (pending) | Growth Bonds + secondary market |
## Notes
- Every module follows the same pattern: `types/types.go` + `types/types_test.go`
(package `types`), zero external deps, by-ID-string inter-module refs (G-003).
- Each new/extended test file includes a lexicon assertion (REQ-012); the
project-wide meta-test (`lexicon_meta_test.go`) scans all `x/**/*.go`.
- The docs firewall (`lexicon_meta_docs_test.go`) scans `README.md` + all
`docs/**/*.md`. See the [architecture index](architecture.md) for the
14-component view and the 6 cross-component interfaces.