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

docs(milestone): complete OpenYield v0.3 (Bearers & Documentation)

Browse Source 
Milestone v0.3 complete. Feature type, tags v0.2.x. Two work-streams
shipped under one feature milestone:

(A) Bearers skeleton + tests (D-020 pattern, 7 x/* packages, zero ext deps):
- x/bridge (NEW): BridgeStatus enum (4), BridgeRoute by-ID-string refs
- x/exit (NEW): ExitStatus enum (5), ExitRoute, DEXSwap (opaque venue)
- x/bearers (EXT): OYSATLink surveillance-resistant LOCKED, OYQRCode idempotent
- x/partner (EXT): AnchorCredential (custody-provider-id empty in skeleton)
- x/hub (NEW): HubService enum (3), LendingCouponCapBps=800 LOCAL const (A-304)
- x/services (NEW): ServiceKind enum (4), window-id by-ID-string ref (A-307)
- x/bond (EXT): GrowthBond, ClampGrowth G-012 underflow guard, secondary market
All packages >=93.3% coverage. Both lexicon firewalls green. G-003 intact.

(B) Documentation deliverable (REQ-027 complete, 26-page MkDocs Material site):
- README.md + mkdocs.yml + docs/index.md
- docs/shared/ (7 pages): Six Principles, Bread Scale, Storage Pools, Watchers/Mirror, Lexicon, Vision
- docs/nomads/ (8 pages): Reach, Stash, Bearers, Maps-Pay, Pacts, Standing, Window
- docs/freeholders/ (8 pages): Signals, Standing, Stands-Guilds, Councils-Voice, Bonds, Partner Spectrum, Anchor Preview
- docs/reference/ (2 pages): Architecture, Components
- REQ-028: lexicon firewall extended to docs/ + README.md (lexicon_meta_docs_test.go, 5 tests incl G-013 walk-coverage + G-014 shared self-test)

Phases: P0 -> v0.2.0, P1 -> v0.2.1, P2 -> v0.2.2, P3 -> v0.2.3, P4 -> v0.2.4, P5 -> v0.2.5, P6 -> v0.2.6 (milestone release).

Requirements covered: REQ-010, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026 (skeleton), REQ-027, REQ-028 (complete).
IDEATE-01..08 ratified and delivered.

---ci---
project: oy
phase: 6
milestone: v0.3
status: complete
tag_base: v0.2.x
phase_role: final
milestone_complete: true
requirements:
  covered: [REQ-010, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026, REQ-027, REQ-028]
  partial: []
---/ci---
This commit is contained in:
cloudinit-bot
2026-08-17 22:35:36 +00:00
parent 47fa79148c
commit 82ae6cf5a2
58 changed files with 7115 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/shared/bread-scale.md
+35
View File
@@ -0,0 +1,35 @@
# Bread scale
The unit of value in OpenYield is **Bread** (REQ-013). Bread is scaled in 11
tiers, each 1,000× the previous, so a Holder can reason about a Crumb and a
Granary in the same mental model:
| Tier | Name | Multiple |
|---|---|---|
| 1 | **Grain** | 1 |
| 2 | **Crumb** | 1,000 Grain |
| 3 | **Bread** | 1,000 Crumb |
| 4 | **Loaf** | 1,000 Bread |
| 5 | **Batch** | 1,000 Loaf |
| 6 | **Cake** | 1,000 Batch |
| 7 | **Bakery** | 1,000 Cake |
| 8 | **Granary** | 1,000 Bakery |
| 9 | **Mill** | 1,000 Granary |
| 10 | **Harvest** | 1,000 Mill |
| 11 | **Earth** | 1,000 Harvest |
## Why 11 tiers
The 11-tier scale gives the mesh a single unit for everything from a
1-Grain internal minimum (the Fee Covenant floor) to the Earth-tier totals
held in the Root-Pool. There is no separate "small unit" and "large unit":
the Bread scale is the unit. The 1-Grain minimum prevents dust games; the
tier names keep human-readable values at every scale.
## Where Bread lives
Bread is held in the three [Storage Pools](storage-pools.md): the Stash
(Holder-level), the Vault (Stand-level), and the Root-Pool (treasury). The
Watchers attest to the state of the pools daily; the Mirror mirrors the
canonical state to the bearers. See [Watchers & Mirror](watchers-mirror.md)
for the attestation layer.
docs/shared/index.md
+16
View File
@@ -0,0 +1,16 @@
# Shared concepts
The Shared section holds the concepts common to every OpenYield audience —
Nomads and Freeholders alike. These are the covenant-level ideas that make
OpenYield a public-good mesh rather than a custodial platform.
- [Six Principles](six-principles.md) — the immutable covenant (REQ-001).
- [Bread Scale](bread-scale.md) — the unit of value and its 11 tiers (REQ-013).
- [Storage Pools](storage-pools.md) — the three pools (Stash, Vault, Root-Pool) (REQ-014).
- [Watchers & Mirror](watchers-mirror.md) — the 9 Watchers, 6-of-9 quorum, the Mirror (REQ-004).
- [Lexicon](lexicon.md) — why 10 terms are banned, and what to say instead (REQ-012).
- [Vision](vision.md) — the OpenYield covenant in brief.
See the [README](../index.md) for build instructions, or the
[Nomads](../nomads/index.md) and [Freeholders](../freeholders/index.md)
sections for audience-specific docs.
docs/shared/lexicon.md
+148
View File
@@ -0,0 +1,148 @@
# Lexicon
OpenYield bans 10 financial terms as standalone words (REQ-012). The firewall
scans every Go file under `x/` and every Markdown file under `README.md` +
`docs/`, and fails the build on any standalone occurrence. This page documents
**why** the terms are banned and **what to say instead** — the replacements,
not the banned literals.
## Why a lexicon
The words a legacy financial institution uses carry the shapes of that
institution: custodial positions, jurisdiction-bound units, and
speculation-language. OpenYield is a jurisdiction-light, public-good mesh for
real production; using the old words would import the old shapes. The
lexicon firewall keeps the mesh's language aligned with its covenant. The
firewall is enforced in code by two sibling Go tests
(`lexicon_meta_test.go` for `x/**/*.go`;
`lexicon_meta_docs/lexicon_meta_docs_test.go` for `README.md` +
`docs/**/*.md`), both using `lexicon.FindBannedTerm` (word-boundary,
case-insensitive). Word-boundary matching means "OpenYield" is safe — the
firewall bans standalone words, not substrings.
## The 10 banned terms and their safe replacements
The firewall bans 10 standalone words. This page does not write the banned
words as literals (the firewall scans this page); it describes them by the
concept each belongs to, and gives the safe replacement.
### 1. The custodial-position word
A legacy institution holds your value in a custodial position. OpenYield
does not: a Holder owns their **Stash**, a Stand owns its **Vault**, the mesh
owns the **Root-Pool**. The Holder's identity is a **Reach**, and the Holder
themselves is a **Holder** — never the banned custodial-position word.
- Banned: the word for a custodial position.
- Safe: **Holder**, **Reach**, **Stash**, **Vault**, **Root-Pool**.
### 2. The legacy-institution word
The legacy financial institution itself is banned as a concept. OpenYield is
a **mesh**, a **public good**, a **protocol** — not that word.
- Banned: the word for a legacy financial institution.
- Safe: **mesh**, **protocol**, **public good**.
### 3. The place-value word
The word for a place to hold value under custody is banned. Use the
**Stash** (Holder-level), the **Vault** (Stand-level), or the **Root-Pool**
(treasury).
- Banned: the word for a place value is held.
- Safe: **Stash**, **Vault**, **Root-Pool**, **Storage Pools**.
### 4. The put-in word
The verb for putting value into a custodial position is banned. Use **hold**,
**store**, **move**, or **transfer**.
- Banned: the verb for placing value under custody.
- Safe: **hold**, **store**, **move**, **transfer**, **Pass-Act**.
### 5. The passive-value word
The word for value earned passively on a custodial position is banned. For
bonds, use **coupon**. For the mesh's metric, use **real production** or
**real return**.
- Banned: the word for passive value on a custodial position.
- Safe: **coupon**, **real production**, **real return**.
### 6. The standalone metric word
The standalone word for a return metric is banned (it is the same concept as
#5 in verb form). Use **real production**, **real return**, or **coupon**
(for bonds). "OpenYield" is safe — word-boundary matching does not flag the
banned term inside an identifier.
- Banned: the standalone return-metric word.
- Safe: **real production**, **real return**, **coupon**. **OpenYield** is safe.
### 7. The medium-of-exchange word
The word for a national medium of exchange is banned. The mesh's unit is
**Bread** (see [Bread scale](bread-scale.md)). For a foreign-exchange pair,
use **Forex** (allowed) with **base-asset** / **quote-asset** labels, or
**Bread / Asset**.
- Banned: the word for a national medium of exchange.
- Safe: **Bread**, **asset**, **Forex**, **base-asset**, **quote-asset**.
### 8. The first national-unit word
The word for the first major national unit is banned. Use **Bread** or
opaque chain names (e.g., "Polygon", "OY-Chain").
- Banned: the first national-unit word.
- Safe: **Bread**, **asset**, chain names.
### 9. The second national-unit word
The word for the second major national unit is banned (the firewall bans it
as a standalone word; "european" is safe by word-boundary). Use **Bread** or
opaque chain names.
- Banned: the second national-unit word.
- Safe: **Bread**, **asset**, chain names. **European** is safe (word-boundary).
### 10. The set-aside word
The word for value set aside under custody is banned. Use **Stash**,
**Vault**, or **Root-Pool**.
- Banned: the word for value set aside.
- Safe: **Stash**, **Vault**, **Root-Pool**.
### 11. The holder-of-value word
The word for the person who holds value under custody at a legacy
institution is banned. Use **Holder**, **Freeholder**, or **Nomad**.
- Banned: the word for a custodial-position holder.
- Safe: **Holder**, **Freeholder**, **Nomad**, **Reach**.
> **Note**: the firewall bans 10 standalone words; this page lists 11
> replacements because two of the banned words (the passive-value word and
> the standalone metric word) share a concept and get the same replacement
> family (**coupon** / **real production** / **real return**).
## How the firewall works
The firewall uses `lexicon.FindBannedTerm` — a word-boundary, case-insensitive
regex match — so:
- "OpenYield" is **safe**: the standalone banned term inside an identifier
does not match (word-boundary).
- "european" is **safe**: the standalone national-unit word inside a larger
word does not match.
- The standalone banned word in prose **is** matched and fails the build.
The firewall's own source (`lexicon/lexicon.go`) assembles the banned terms
at runtime from two-character fragments, so the firewall's own code does not
contain any banned term as a literal substring. The two sibling meta-tests
(`lexicon_meta_test.go` and `lexicon_meta_docs/lexicon_meta_docs_test.go`)
each include a self-test table that verifies detection of all 10 banned
terms from the single source `lexicon.BannedTerms()` (G-014 drift
prevention).
docs/shared/six-principles.md
+54
View File
@@ -0,0 +1,54 @@
# Six Principles
The Six Principles are the immutable covenant of OpenYield (REQ-001). They
are **Mission-locked**: no Council can amend them, and the fee covenant is
locked alongside them. The mesh exists to hold real production, not
speculation; everything else follows from that.
## 1. Real value
The mesh holds **real production**. The Bread unit is the unit of real value
held in the Storage Pools; the bond market caps coupons so the mesh cannot
become a speculation engine. "Real return" is the metric, not a nominal rate.
## 2. Sustainability
Fees are floored and capped. The fee covenant fixes a ceiling and a floor
(see the Fee Covenant module), and the 1-Grain internal minimum prevents dust
games. The protocol cannot drain its users, and it cannot starve its
Watchers.
## 3. Mission-lock
The Six Principles and the fee covenant are immutable. No Council — Mesh,
Guild, or Stand — can amend them. Mission Lock is a `const` in the council
module, and an invariant test asserts it can never be set to amendable. The
coupon cap on bonds is a mission-locked ceiling, not a parameter a Council
can tune.
## 4. Openness
Anyone may join. The mesh is a public good. A Holder needs only a Reach (an
identity) and a Stash (a storage pool) to begin; there is no gatekeeper and
no custodian.
## 5. Ownership
Holders own their Stash and their Reach. Custody is theirs: the Stash is the
Holder-level storage pool, the Vault is the Stand-level pool, and the
Root-Pool is the treasury. The protocol does not custody user value; it
holds the canonical state that records who owns what.
## 6. Self-service
A Holder can act without a custodian. The Window primitive lets a Holder
delegate a scope-bounded, time-limited, revocable capability to a partner or
a service; the bearers (OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, OY-QR) let a
Holder reach the mesh without a phone plan or a custodial on-ramp. The mesh
is jurisdiction-light by design.
---
See the [Vision](vision.md) for the covenant in brief, or the
[Lexicon](lexicon.md) for why the docs say "real production" and "Holder"
rather than the words a legacy financial institution would use.
docs/shared/storage-pools.md
+48
View File
@@ -0,0 +1,48 @@
# Storage Pools
OpenYield has three Storage Pools (REQ-014). Each is a layer of custody
responsibility, and none of them is a custodial position — the protocol holds
the canonical state that records who owns what; the Holder, the Stand, and
the mesh treasury each hold their own pool.
| Pool | Level | Held by | Purpose |
|---|---|---|---|
| **Stash** | Holder | a single Holder | the personal storage pool; the unit of self-service |
| **Vault** | Stand | a Stand (a governed group) | the Stand-level pool; the unit of shared ownership |
| **Root-Pool** | Mesh | the mesh treasury | the canonical treasury; the unit of the public good |
## The Stash
The Stash is the Holder-level storage pool. A Holder needs only a Reach (an
identity) and a Stash to begin. The Stash is the unit of self-service: the
Holder owns it, controls it, and can delegate a scoped, time-limited,
revocable Window to a partner or a service without giving up custody. See
[Watchers & Mirror](watchers-mirror.md) for the attestation layer that
records Stash state.
## The Vault
The Vault is the Stand-level storage pool. A Stand is a governed group
(one of the nine Stand types: Household, Crew, Entity, Co-op, Circle,
Trust, Foundation, Confederation, Shadow) that holds a Vault in common. The
Stand's decision policy (threshold or weighted, mirroring the Cosmos SDK
`x/group` shape) governs how the Vault is used. See the Freeholders section
for Stands & Guilds.
## The Root-Pool
The Root-Pool is the mesh treasury. It holds the canonical state of the
Bread unit, the Watcher bonds, and the Root Basket. The Root-Pool is the
unit of the public good: the Watchers attest to its state daily, and the
Mirror mirrors it to the bearers so a Holder can verify the mesh's real
return without trusting a single custodian.
## Custody, not custody
The three pools are storage layers, not custodial positions. The protocol
does not custody user value; it holds the canonical state that records who
owns what. A Holder's Stash is theirs; a Stand's Vault is the Stand's; the
Root-Pool is the mesh's. The Window primitive lets a Holder delegate a
capability without delegating custody. See the [Lexicon](lexicon.md) for
why the docs say "Stash", "Vault", and "Root-Pool" rather than the words a
legacy financial institution would use.
docs/shared/vision.md
+64
View File
@@ -0,0 +1,64 @@
# Vision
OpenYield is a jurisdiction-light, public-good mesh for **real production**.
The vision is a covenant, not a product: the mesh holds real value, the Six
Principles are immutable, and the protocol cannot become a custodial
platform. This page is the brief overview; the full vision source lives in
`.ciagent/oy/PROJECT.md`.
## The covenant
OpenYield exists to hold **real production** — the real return of real work,
held in the Bread unit, in the three Storage Pools, attested by the Watchers,
mirrored by the Mirror. The covenant is anti-greed by construction:
- **Mission Lock** fixes the Six Principles and the fee covenant. No Council
— Mesh, Guild, or Stand — can amend them. The coupon cap on bonds is a
mission-locked ceiling, not a parameter.
- **Jurisdiction-light** — the bearers (OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT,
OY-QR) let a Holder reach the mesh without a phone plan or a custodial
on-ramp. A Holder needs only a Reach and a Stash to begin.
- **Public good** — the mesh is open to all. The Watchers attest daily; the
Mirror mirrors the state; anyone can verify the mesh's real return without
trusting a single custodian.
## The layers
1. **OY Chain** (Layer 1) — the canonical state: the Bread unit, the
Storage Pools, Standing, Watcher attestations, the Pact / Council /
Partner surface.
2. **Satellites** (Layer 2) — wrapped Bread propagates to satellite chains
(Polygon active; Base, Arbitrum, Optimism, Solana as enum placeholders)
via IBC.
3. **Bearers** — the surveillance-resistant transport layer: OY-LR (LoRa,
long-range), OY-BLE (Bluetooth), OY-WiFi-Direct, OY-SAT (satellite),
OY-QR (paper / QR code). The Mirror mirrors canonical state to them.
4. **Exits** — the Layer 3 exit layer: Holder-initiated DEX swaps and
off-mesh service exits, with bridge routes for cross-chain exits.
## The actors
- **Holders** (Nomads) — the everyday participants, each with a Reach and a
Stash.
- **Freeholders** — the active participants who run Stands, Guilds, and
Councils.
- **Partners** — the four-tier spectrum (Op, MasterOp, Pier, Anchor) that
processes Pass-Acts and provides credentials and institutional backing.
- **Watchers** — the 9 attesters with 6-of-9 quorum and 100,000 Bread bonds.
## The units
- **Bread** — the unit of real value (see [Bread scale](bread-scale.md)).
- **Standing** — the reputation layer (the four signals, Bayesian Standing).
- **Voice** — the governance input (multi-source: Stash, Standing, Vouch,
Freeholder, Guild).
- **Coupon** — the bond-market term (capped at 8% / floored at 0%, mission-locked).
## Where to go next
- [Six Principles](six-principles.md) — the immutable covenant.
- [Storage Pools](storage-pools.md) — the three pools.
- [Watchers & Mirror](watchers-mirror.md) — the attestation layer.
- [Lexicon](lexicon.md) — why the docs say "real production" and "Holder".
- [README](../../README.md) — build & test instructions.
- `.ciagent/oy/PROJECT.md` — the full vision source.
docs/shared/watchers-mirror.md
+42
View File
@@ -0,0 +1,42 @@
# Watchers & Mirror
OpenYield is attested by **9 Watchers** with a **6-of-9 quorum** (REQ-004).
The Watchers make daily attestations to the canonical state, and each posts
a 100,000 Bread bond. The **Mirror** mirrors the canonical state to the
bearers so a Holder can verify the mesh's state without trusting a single
Watcher.
## The 9 Watchers
The Watchers are the attestation layer of the mesh. There are exactly 9, and
the quorum is 6-of-9: any 6 Watchers can attest to a state transition, but no
5 can. Each Watcher posts a 100,000 Bread bond, which is at risk if the
Watcher attests to a false state. The 9/6 split is a mission-locked
parameter — no Council can lower the quorum or the bond.
## Daily attestations
The Watchers attest to the state of the three [Storage Pools](storage-pools.md)
daily: the Stash totals, the Vault totals, and the Root-Pool. The
attestation is a signed statement that the canonical state recorded by OY
Chain matches the state the Watcher observed. A Holder who wants to verify
the mesh's real return can read the attestations and check that the
Watchers agree.
## The Mirror
The Mirror mirrors the canonical state to the bearers (OY-LR, OY-BLE,
OY-WiFi-Direct, OY-SAT, OY-QR). A Holder on a surveillance-resistant bearer
can read the mirrored state without an internet connection to OY Chain; the
Mirror is the read-side of the bearer layer. The Mirror is read-only: it
mirrors state, it does not author it. Authoritative state lives on OY Chain
and is attested by the Watchers.
## Why 6-of-9
The 9/6 split is a balance: 9 is large enough that no single adversary can
easily capture a quorum, and 6 is large enough that no small cabal can
attest to a false state. The 100,000 Bread bond per Watcher makes
capturing a quorum expensive. The split is locked by Mission Lock — no
Council can change it. See [Six Principles](six-principles.md) for the
mission-lock covenant.