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/freeholders/anchor-preview.md
+47
View File
@@ -0,0 +1,47 @@
# Anchor Preview
An **Anchor** (REQ-023) is the fourth and highest tier of the
[Partner Spectrum](partner-spectrum.md) (REQ-018) — the first **institutional**
Partner tier. Anchors are coming in v0.3 P4. This page previews what an Anchor
is and what the v0.3 skeleton will deliver; the runtime behavior is deferred
to v0.4+.
## What an Anchor is
An Anchor is a Partner that carries an **AnchorCredential**: a jurisdiction
(e.g., "EU-MiCA"), a custody provider, and a set of attestation references.
The Anchor tier is how the jurisdiction-light mesh interfaces with
jurisdiction-bound institutional actors without becoming them. An Anchor
holds a credential; the [Holder](../nomads/reach.md) still holds their
[Stash](../nomads/stash.md). The mesh says **custody**, **compliance**, and
**jurisdiction** — never the legacy institutional words banned by the
[lexicon](../shared/lexicon.md).
## What is coming in v0.3 P4
v0.3 P4 (REQ-023) extends `x/partner` with the `AnchorCredential` struct and
a `Partner.AnchorCredential()` accessor (returns nil for non-Anchor tiers).
The four-tier `PartnerTier` enum (Op, Master Op, Pier, Anchor) is **unchanged**
— v0.3 adds Anchor-specific fields, not a new tier. The custody-provider-id
field is a by-ID-string reference to `x/hub` (the Hub API, coming in v0.3 P5),
empty in the v0.3 skeleton because the Hub is not live until P5/v0.4. This is
the P4→P5 ordering edge: `x/hub` in P5 references Anchor partner-ids from P4.
## Why Anchors matter to a Freeholder
A Freeholder engaging an Anchor gets a Partner with a verifiable credential
and a custody/compliance relationship — useful for cross-jurisdiction routes
and institutional [bonds](bonds.md). The Anchor's [Standing](standing.md) and
attestations are visible so the Freeholder can verify the Anchor is real
before opening a [Window](../nomads/window.md). See
[Partner Spectrum](partner-spectrum.md) for the other three tiers, and
[Councils & Voice](councils-voice.md) for how the Mesh Council can suspend or
revoke an Anchor.
## What v0.3 does not deliver
The v0.3 skeleton is types + tests only (D-035): the `AnchorCredential`
struct, the accessor, and the `ListAnchors()` keeper alias. Live custody
routing, attestation verification, and the Hub API integration are v0.4+
runtime work. See [Components](../reference/components.md) for the full
module map.
docs/freeholders/bonds.md
+46
View File
@@ -0,0 +1,46 @@
# Bonds
A **Mesh Bond** (REQ-021, vision §17) is a [Stand](stands-guilds.md)-issued
instrument that pays a **coupon** to its holder over a term and returns the
principal at maturity. The coupon is bounded by a **mission-locked cap and
floor**: 8% upper cap, 0% floor (locked `CouponCapBps = 800` and
`CouponFloorBps = 0` in `x/bond`). The cap exists so the mesh cannot become a
speculative market; the floor exists so the coupon cannot go negative.
## The coupon clamp
The coupon is clamped to `[floor, cap]` by the `Clamp` helper in `x/bond`
(same shape as the [Fee Covenant](../shared/six-principles.md) clamp): a
coupon above 8% is reduced to 8%; a coupon below 0% is raised to 0%; a coupon
in range is unchanged. The clamp is a tested invariant: below floor → floor,
above cap → cap, in range → unchanged. This is the Mission Lock's expression
in the capital layer.
## Why a cap
OpenYield is a public-good mesh for **real production**, not a speculation
engine. An uncapped coupon market would let a Stand offer arbitrarily high
coupons to attract Bread, turning the mesh into a speculative race. The 8%
cap bounds the coupon at a level consistent with real production returns, and
the [Mission Lock](councils-voice.md) makes the cap non-amendable — no Council
vote can raise it. The mesh says **coupon** and **real return**, never the
passive-value or standalone-metric words banned by the
[lexicon](../shared/lexicon.md).
## The bond lifecycle
A Bond moves through five states (locked `BondStatus` enum in `x/bond`):
Issued → Active → Matured, with Defaulted and Repaid as terminal paths. The
issuer is a Stand (referenced by stand-id); the principal is denominated in
[Grain](../shared/bread-scale.md). The bond market is governed by the
[Stand Council](councils-voice.md) for the issuing Stand.
## Coming in v0.3 P5
v0.3 P5 (REQ-026) extends the bond market with **Growth Bonds** (a coupon that
grows over the term, still clamped to the 8% cap) and a **secondary market**
(Buy/Sell orders on issued bonds). The 8% / 0% consts are unchanged — the
D-028 regression firewall guarantees v0.3 cannot alter the v0.2 mission-locked
ceiling. See [Partner Spectrum](partner-spectrum.md) for how Partners relate
to the bond market, and [Anchor Preview](anchor-preview.md) for the
institutional tier.
docs/freeholders/councils-voice.md
+48
View File
@@ -0,0 +1,48 @@
# Councils & Voice
OpenYield governs itself through three **Councils** (REQ-011, vision §19):
the Mesh Council, the Guild Council, and the Stand Council. Each Freeholder
participates through the Councils, weighted by **Voice** — a multi-source
weight that combines [Stash](../nomads/stash.md), [Standing](standing.md),
Vouch, Freeholder status, and Guild membership. The **Mission Lock** makes
the covenant non-amendable: no Council can vote to change the
[Six Principles](../shared/six-principles.md) or the fee covenant.
## The three Councils
- **Mesh Council** — the mesh-wide Council. Handles protocol-level proposals
that affect every Holder and every [Stand](stands-guilds.md).
- **Guild Council** — the Council for [Guilds](stands-guilds.md). Handles
Guild-scope proposals, referenced by guild-id.
- **Stand Council** — the Council for a single Stand, referenced by stand-id.
Handles Stand-scope proposals (e.g., Vault use, [Bond](bonds.md) issuance).
The three-tier shape mirrors the three [Storage Pools](../shared/storage-pools.md):
a Council exists at each layer where custody is held.
## Multi-source Voice
Voice is not one number. It is a weighted tally from five sources (locked as
the `VoiceSource` enum in `x/council`): Stash, Standing, Vouch, Freeholder,
and Guild. A Freeholder with high [Standing](standing.md) and a long-held
Stash carries more Voice than a freshly-minted one. The
[TallyResult](../reference/components.md) mirrors the Cosmos SDK `x/gov`
shape so the governance layer can wire to standard tooling. The VoteOption
enum is **Yes / No / Abstain** — there is no "no-with-veto", an anti-greed
design choice.
## Mission Lock
The Mission Lock is a locked `const bool` in `x/council`
(`MissionLockAmendable = false`). The Six Principles, the fee covenant
(ceiling 0.1% / floor 0.01% / 1-Grain minimum), and the bond coupon cap
([8% / 0%](bonds.md)) cannot be amended by any Council vote. This is the
firewall that keeps the mesh a public good: governance can act *within* the
covenant, never *on* the covenant.
## How a Freeholder participates
A Freeholder submits or votes on proposals in the Councils they belong to.
Each vote is weighted by multi-source Voice; the tally follows `x/gov`
semantics. See [Bonds](bonds.md) for the coupon cap the Mission Lock protects,
and [Standing](standing.md) for the metric that weights a Freeholder's Voice.
docs/freeholders/index.md
+39
View File
@@ -0,0 +1,39 @@
# Freeholders
A **Freeholder** is a Holder who has earned all four Freeholder signals (REQ-005):
a 90-day [Stash](../nomads/stash.md), a [Standing](standing.md) threshold of
4.5★ or higher in 3 categories, the Capital signal, and the Vouch signal. A
Freeholder is the active participant in the OpenYield mesh — they sit in
[Stands & Guilds](stands-guilds.md), vote in the three
[Councils & Voice](councils-voice.md), issue [Bonds](bonds.md), and relate to
the four-tier [Partner Spectrum](partner-spectrum.md).
## The four signals
The signals are the gate to Freeholder participation. They are deliberately
heterogeneous — no single input can be pumped — so the path resists gaming:
- [Signals](signals.md) — the four Freeholder signals (REQ-005): 90-day Stash,
4.5★+ in 3 categories, Capital, Vouch.
- [Standing](standing.md) — the Bayesian anti-gaming formula (REQ-006):
Bayesian prior + time-decay + diversity + voucher-weighting − slashes.
- [Stands & Guilds](stands-guilds.md) — the nine Stand types (REQ-016) and
Guilds with free Hand-Passes (REQ-017).
- [Councils & Voice](councils-voice.md) — the three Councils and the
non-amendable Mission Lock (REQ-011).
- [Bonds](bonds.md) — the Mesh Bond Market, the 8% coupon cap / 0% floor
(REQ-021).
- [Partner Spectrum](partner-spectrum.md) — the four Partner tiers (REQ-018):
Op, Master Op, Pier, Anchor.
- [Anchor Preview](anchor-preview.md) — the first institutional Partner tier
(REQ-023), coming in v0.3 P4.
## What a Freeholder does
A Freeholder is a Holder who has crossed the signal gate. From there the mesh
opens: a Freeholder joins a [Stand](stands-guilds.md) (or forms a Guild), votes
in the [Councils](councils-voice.md) with multi-source Voice, issues or holds
[Bonds](bonds.md) under the mission-locked coupon cap, and engages the
[Partner Spectrum](partner-spectrum.md) — including the Anchor tier coming in
v0.3. The covenant is the same for every audience; the Freeholder pages
describe how it shows up in governance and capital.
docs/freeholders/partner-spectrum.md
+42
View File
@@ -0,0 +1,42 @@
# Partner Spectrum
OpenYield defines a four-tier **Partner Spectrum** (REQ-018, vision §13):
**Op**, **Master Op**, **Pier**, and **Anchor**. Partners are the external
actors a [Freeholder](index.md) interacts with through the mesh — service
operators, route providers, and institutional bridges. The four tiers are
locked as the `PartnerTier` enum in `x/partner` (exactly 4, regression-tested).
## The four tiers
- **Op** — a service operator. Runs a service a Holder uses through a
[Window](../nomads/window.md) (e.g., a Maps provider). The lightest tier.
- **Master Op** — a senior operator. Coordinates multiple Ops or runs a
higher-trust service. "Op" is the safe short form; the full word is not
used as a standalone term.
- **Pier** — a routing Partner. Connects the mesh to external venues (e.g.,
a DEX or an off-mesh service) and sources [Forex](../reference/components.md)
rates. Piers route; they do not custody Holder value.
- **Anchor** — the first institutional Partner tier. Carries a credential
(jurisdiction, custody provider, attestations). See
[Anchor Preview](anchor-preview.md) for what is coming in v0.3 P4.
## How Freeholders relate to Partners
A Freeholder authorizes a Partner to act on their behalf through a scoped,
time-limited, revocable [Window](../nomads/window.md) — never by handing over
custody. The Partner holds a credential, not the Holder's [Stash](../nomads/stash.md).
A Partner's [Standing](standing.md) is visible so a Freeholder can choose an
operator with a real history over a freshly-spun-up alternative (see
[Maps & Pay](../nomads/maps-pay.md)).
## Partner status
Each Partner has a status (locked `PartnerStatus` enum in `x/partner`):
Pending → Active, with Suspended and Revoked as the governance paths. The
[Mesh Council](councils-voice.md) can suspend or revoke a Partner. The four
tiers and the status enum are unchanged by v0.3 — v0.3 only *extends*
`x/partner` with the Anchor credential shape (REQ-023), not a new tier.
See [Storage Pools](../shared/storage-pools.md) for why the mesh says
"Holder" and "Reach" rather than the legacy custodial words, and
[Bonds](bonds.md) for the coupon market a Partner may route to.
docs/freeholders/signals.md
+45
View File
@@ -0,0 +1,45 @@
# The Four Freeholder Signals
The four **Freeholder signals** (REQ-005) are the gate to Freeholder
participation. A [Holder](../nomads/reach.md) who earns all four becomes a
[Freeholder](index.md) — eligible to join [Stands & Guilds](stands-guilds.md),
vote in the [Councils](councils-voice.md), and issue [Bonds](bonds.md). The
signals are deliberately heterogeneous: no single input can be pumped, so the
path resists gaming.
## 1. The 90-day Stash
A Holder must hold a [Stash](../nomads/stash.md) continuously for 90 days
(REQ-014). The signal is about **continuity, not size** — a small Stash held
steadily counts. This filters out transient actors who spin up a position to
game a vote and then leave. See [Storage Pools](../shared/storage-pools.md)
for the three-pool model.
## 2. Standing of 4.5★ or higher in 3 categories
A Holder must earn a [Standing](standing.md) of 4.5★ or higher in **three
distinct categories** (REQ-006). The diversity requirement is the anti-gaming
core: a Holder cannot reach Freeholder by repeating the same action with the
same counterparty. Three categories force breadth.
## 3. Capital
The Capital signal requires a Holder to hold a meaningful amount of
[Bread](../shared/bread-scale.md) in their Stash. The threshold is set by the
mesh [Councils](councils-voice.md) and is a stake, not a fee: the Holder keeps
the Bread. Capital aligns the Freeholder's stake with the mesh.
## 4. Vouch
The Vouch signal requires another Freeholder to vouch for the Holder. A
vouch from a high-[Standing](standing.md) Freeholder carries more weight
(voucher-weighting), so a single colluding vouch cannot carry a Holder over
the gate. Vouch is the social signal that ties the other three together.
## Why four, not one
Each signal covers a different attack surface: continuity (90-day Stash),
breadth (3-category Standing), stake (Capital), and social trust (Vouch).
Earning all four is the proof a Holder is a participant, not a transient
gamer. See [Standing](standing.md) for the anti-gaming math, and
[Bonds](bonds.md) for what a Freeholder can do once the signals are earned.
docs/freeholders/standing.md
+49
View File
@@ -0,0 +1,49 @@
# Bayesian Standing
**Standing** (REQ-006) is a Holder's measured history on the mesh — the
anti-gaming metric that gates [Freeholder](index.md) participation and weighs
[Voice](councils-voice.md) in the [Councils](councils-voice.md). Standing is
not a count of transactions and not a reputation score you can farm. It is a
Bayesian score that resists the obvious attacks: volume spam, self-dealing,
fake vouches.
## The formula, at conceptual depth
Standing combines four signals and a penalty:
- **Bayesian prior + updates.** The mesh starts with a prior for each Holder
and updates it from each observed action. A burst of activity cannot
inflate Standing because the prior anchors it.
- **Time-decay.** Old evidence decays, so a Holder cannot rest on a burst
from years ago. Standing reflects *recent, sustained* real production.
- **Diversity weighting.** A Holder who acts across many services, many
[Stands](stands-guilds.md), and many [bearers](../nomads/bearers.md) accrues
more Standing than one who repeats the same action with the same
counterparty. Diversity is the anti-collusion lever.
- **Voucher-weighting.** A vouch from a high-Standing Freeholder counts for
more than a vouch from a low-Standing one. This makes fake vouches expensive:
the voucher must themselves have Standing to lose.
- **Minus slashes.** Bad behavior (failed attestations, broken Pacts) removes
Standing. Slashes are the penalty that bounds the upside of gaming.
> The full sub-tables (priors, decay rates, diversity categories, slash
> conditions) are deferred per PROJECT.md Q2. This page gives the conceptual
> depth; the [nomads Standing page](../nomads/standing.md) gives the plain-
> language version.
## Why it cannot be gamed
There is no single input a Holder can pump. Volume is bounded by the Bayesian
prior; recency is bounded by time-decay; breadth is bounded by diversity;
social trust is bounded by voucher-weighting; and any attempt that misfires
costs Standing via slashes. The four signals (the [90-day Stash](signals.md),
3-category threshold, Capital, Vouch) sit on top of this metric, so the
Freeholder gate inherits the same anti-gaming property.
## What Standing is not
Standing is not a custodial position, a tier you buy, or legacy history. It
is a measured, decayed, diversified Bayesian score. See
[Storage Pools](../shared/storage-pools.md) for why the mesh says "Stash"
rather than the legacy custodial words, and [Councils & Voice](councils-voice.md)
for how Standing weights a Freeholder's vote.
docs/freeholders/stands-guilds.md
+47
View File
@@ -0,0 +1,47 @@
# Stands & Guilds
A **Stand** is a governed group of Holders that holds a [Vault](../shared/storage-pools.md)
in common (REQ-016). A **Guild** is a looser association of Holders that can
pass value among its members for free (REQ-017). Both are the organizational
layer a [Freeholder](index.md) joins after earning the four
[signals](signals.md).
## The nine Stand types
OpenYield defines exactly nine Stand types (REQ-016, vision §11), locked as a
const in `x/stand`:
1. **Household** — a family-scale group.
2. **Crew** — a working team.
3. **Entity** — a single legal actor.
4. **Co-op** — a cooperative.
5. **Circle** — an affinity group.
6. **Trust** — a trust arrangement.
7. **Foundation** — a purpose-bound entity.
8. **Confederation** — a federation of Stands.
9. **Shadow** — a privacy-preserving Stand.
A Stand's decision policy (threshold or weighted, mirroring the Cosmos SDK
`x/group` shape) governs how its Vault is used. A Stand can also issue
[Bonds](bonds.md) — the bond issuer is a Stand, referenced by stand-id.
## Guilds and Hand-Passes
A **Guild** is a looser association: it may affiliate with a Stand or stand
alone. Inside a Guild, a **Hand-Pass** moves [Bread](../shared/bread-scale.md)
between members at a **0% protocol fee** (REQ-017, locked `HandPassFeeBps = 0`
in `x/guild`). The 0% fee is mission-locked: the mesh does not tax the social
transfer of value among a self-organized group. See the
[Fee Covenant](../shared/six-principles.md) for the broader fee shape.
## How a Freeholder joins
A Freeholder joins a Stand by becoming a member (the Stand's policy admits
them) or forms a Guild as a founder. Membership is recorded in `x/stand`
and `x/guild` respectively, by stand-id / guild-id and the member's
[Reach](../nomads/reach.md). From a Stand a Freeholder gains Vault access and
the ability to issue [Bonds](bonds.md); from a Guild a Freeholder gains free
Hand-Passes with other members.
See [Councils & Voice](councils-voice.md) for how Stands and Guilds each get a
Council, and [Storage Pools](../shared/storage-pools.md) for the Vault layer.