From d09c6132b10af622bd79fc20860242696dfc7bc4 Mon Sep 17 00:00:00 2001 From: cloudinit-bot Date: Mon, 17 Aug 2026 22:14:53 +0000 Subject: [PATCH] docs(P02): complete nomads docs phase P2 complete. 8 docs/nomads/ pages: index, reach, stash, bearers, maps-pay, pacts, standing, window. Docs firewall green (scans new nomads pages), no regression. All pages cross-reference docs/shared/. ---ci--- project: oy phase: 2 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [] partial: [REQ-027] ---/ci--- --- docs/nomads/bearers.md | 46 +++++++++++++++++++++++++++++++++++++++ docs/nomads/index.md | 42 ++++++++++++++++++++++++++++++++++++ docs/nomads/maps-pay.md | 46 +++++++++++++++++++++++++++++++++++++++ docs/nomads/pacts.md | 41 +++++++++++++++++++++++++++++++++++ docs/nomads/reach.md | 48 +++++++++++++++++++++++++++++++++++++++++ docs/nomads/standing.md | 44 +++++++++++++++++++++++++++++++++++++ docs/nomads/stash.md | 48 +++++++++++++++++++++++++++++++++++++++++ docs/nomads/window.md | 45 ++++++++++++++++++++++++++++++++++++++ 8 files changed, 360 insertions(+) create mode 100644 docs/nomads/bearers.md create mode 100644 docs/nomads/index.md create mode 100644 docs/nomads/maps-pay.md create mode 100644 docs/nomads/pacts.md create mode 100644 docs/nomads/reach.md create mode 100644 docs/nomads/standing.md create mode 100644 docs/nomads/stash.md create mode 100644 docs/nomads/window.md diff --git a/docs/nomads/bearers.md b/docs/nomads/bearers.md new file mode 100644 index 0000000..7367e20 --- /dev/null +++ b/docs/nomads/bearers.md @@ -0,0 +1,46 @@ +# Bearers + +The **bearers** (REQ-019) are how a Nomad reaches the mesh. OpenYield ships +six bearers through a single **Unified Bearer Layer**: the mesh does not +care which bearer a Holder uses — first-to-deliver-wins, and a Nomad can +switch bearers without switching identity. The [Mirror](../shared/watchers-mirror.md) +mirrors the canonical state to every bearer so a Nomad can read the mesh's +real return on any of them. + +## The six bearers + +| Bearer | Live in v0.2 | What it is | +|---|---|---| +| **Internet** | yes | the default bearer; OY Chain over the open internet. | +| **OY-BLE** | yes | Bluetooth Low Energy; short-range, peer-to-peer, no phone plan. | +| **OY-WiFi-Direct** | yes | WiFi Direct; local mesh without an access point. | +| **OY-LR** | yes | Long Range radio (LoRa-class); long-distance, low-bandwidth, surveillance-resistant. | +| **OY-SAT** | coming (v0.3 P4) | satellite; offline coverage via a satellite constellation. | +| **OY-QR** | coming (v0.3 P4) | signed QR code; one-shot offline transfer scanned by a peer. | + +## What this means for a Nomad + +A Nomad does not pick "the right bearer". The four already-live bearers +(Internet, OY-BLE, OY-WiFi-Direct, OY-LR) cover the everyday situations: +on the open internet, in a room with another Holder, in a local group with +no router, or kilometers away with no infrastructure. OY-SAT and OY-QR +extend that to true-offline paths and are coming in the next phase. + +## Surveillance resistance + +OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, and OY-QR are designed to be +surveillance-resistant: a Nomad can send or receive value without a +phone plan, a SIM, or a custodial on-ramp. The bearer is the transport; the +[Reach](reach.md) is the identity; the [Stash](stash.md) is the storage. None +of them depends on a custodial position. + +## First-to-deliver-wins + +The Unified Bearer Layer is first-to-deliver-wins: if a Nomad sends a +transfer over two bearers at once, the mesh accepts the first one that +arrives and drops the duplicate. This is why a Nomad can switch bearers +mid-transfer without double-spending. + +See [Watchers & Mirror](../shared/watchers-mirror.md) for how the canonical +state is mirrored to every bearer, and [Maps & Pay](maps-pay.md) for how a +Nomad uses a bearer to find and pay for services. \ No newline at end of file diff --git a/docs/nomads/index.md b/docs/nomads/index.md new file mode 100644 index 0000000..4ffa404 --- /dev/null +++ b/docs/nomads/index.md @@ -0,0 +1,42 @@ +# Nomads + +A **Nomad** is a person using the OpenYield mesh through a **Reach** — the +protocol-level identity a Holder uses to act on the mesh without a +custodian, a gatekeeper, or a legacy financial position. The Nomad path +is the entry path: a Nomad is a Holder who has a Reach and a [Stash](stash.md) +and is on the way to earning the four Freeholder signals, but has not yet +earned all four. + +## The Nomad path + +The pages here cover what a Nomad does day-to-day on the mesh: + +- [Reach](reach.md) — the identity; the first Freeholder signal (REQ-005). +- [Stash](stash.md) — the personal [Storage Pool](../shared/storage-pools.md) + where a Nomad holds Bread (REQ-014). +- [Bearers](bearers.md) — how a Nomad reaches the mesh (REQ-019): Internet, + OY-BLE, OY-WiFi-Direct, OY-LR live now; OY-SAT and OY-QR coming. +- [Maps & Pay](maps-pay.md) — finding services and paying for them. +- [Pacts](pacts.md) — the six contract shapes a Nomad encounters + (REQ-020): Pause, Ground, Stance, Cover, Stand Registry, Hub API. +- [Standing](standing.md) — the Bayesian anti-gaming metric (REQ-006), + and why the mesh cannot be gamed. +- [Window](window.md) — the delegation primitive (REQ-015): scope, + duration, rate-limit, audit-log, revoke. + +## Where a Nomad starts + +A Nomad starts with a Reach and a Stash — that is enough to begin. From +there the bearers carry value to the Stash, Maps finds services, Pay and +the Window let a Nomad use them without giving up custody, and Standing +accrues as the Nomad acts. A Nomad who earns the 90-day Stash signal, the +Standing threshold, the Capital signal, and the Vouch signal becomes a +Freeholder (see the Freeholders section). + +## Shared concepts + +The Nomad path rests on the [shared concepts](../shared/index.md): the +[Six Principles](../shared/six-principles.md), the [Bread scale](../shared/bread-scale.md), +the [Storage Pools](../shared/storage-pools.md), the [Watchers & Mirror](../shared/watchers-mirror.md), +and the [Lexicon](../shared/lexicon.md). The covenant is the same for +every audience; the Nomad pages describe how it shows up in everyday use. \ No newline at end of file diff --git a/docs/nomads/maps-pay.md b/docs/nomads/maps-pay.md new file mode 100644 index 0000000..7b9be1b --- /dev/null +++ b/docs/nomads/maps-pay.md @@ -0,0 +1,46 @@ +# Maps & Pay + +**Maps** and **Pay** are the day-to-day Mesh Experience a Nomad uses on the +mesh. Maps finds services; Pay settles them. Both run over the +[bearers](bearers.md) and read the [Mirror](../shared/watchers-mirror.md) so a +Nomad can find and pay for a service on a surveillance-resistant bearer +without an internet connection to OY Chain. + +## Maps + +Maps is the directory of services a Nomad can reach. A service is anything +a Partner or a Stand exposes to the mesh: a Care service, a SIM, a Vault, +a Mailbox (preview of v0.3 P5 — see [Pacts](pacts.md) for the Hub API). Maps +is sorted by geographic proximity (REQ-007): a Nomad physically closer to a +service or its operator is shown that service first. There is no paid +ranking; the order is proximity, not promotion. + +## Pay + +Pay is how a Nomad settles a service. A payment is a transfer of Bread +from the Nomad's [Stash](stash.md) to the service operator's Stash, signed +by the Nomad's [Reach](reach.md). The fee covenant floors and caps the fee; +inside a Guild, a Hand-Pass is free at the protocol level (REQ-017). Pay +runs over any bearer, first-to-deliver-wins. + +## Authorize, don't hand over + +For recurring services a Nomad does not re-sign every payment. Instead +the Nomad opens a [Window](window.md) to the service: a scoped, +time-limited, rate-limited, revocable capability that lets the service pull +value from the Stash within bounds the Nomad set. The Window is audited; +the Nomad can revoke it at any time. This is the self-service principle in +practice: the Nomad delegates a capability, not custody. + +## Find, pay, verify + +A Nomad's loop is: + +1. **Find** a service on Maps. +2. **Pay** once, or **authorize** a [Window](window.md) for recurring use. +3. **Verify** the service against the Watcher attestations on the Mirror + (see [Watchers & Mirror](../shared/watchers-mirror.md)). + +See [Stash](stash.md) for where the Bread comes from, [Window](window.md) +for the delegation primitive, and [Standing](standing.md) for how a +service operator's history is measured. \ No newline at end of file diff --git a/docs/nomads/pacts.md b/docs/nomads/pacts.md new file mode 100644 index 0000000..08c0fe0 --- /dev/null +++ b/docs/nomads/pacts.md @@ -0,0 +1,41 @@ +# Pacts + +The **six Pacts** (REQ-020) are the contract shapes a Nomad encounters on +the mesh. A Pact is a typed, mission-locked agreement between parties; the +core terms of the Pause, Ground, and Stance Pacts are **non-amendable** — +no Council can rewrite them after the fact. A Nomad mostly interacts with +Pacts through [Maps & Pay](maps-pay.md) and the [Window](window.md) +primitive, but it helps to know what each one is. + +## The six Pacts + +| Pact | What it does for a Nomad | +|---|---| +| **Pause** | A temporary hold. A Nomad can pause a recurring payment or a Window without voiding it; the Pause core terms are non-amendable. | +| **Ground** | A baseline obligation the mesh enforces by default — the "ground rules" between a Nomad and a service operator. Non-amendable. | +| **Stance** | A stated position a party commits to (e.g., a service operator's Stance on jurisdiction-light operation). Non-amendable. | +| **Cover** | A flat commitment a Stand or a Partner offers to cover a Nomad against a defined failure; a Nomad reads Cover when choosing a service. | +| **Stand Registry** | The registry of the nine [Stand](../shared/storage-pools.md) types (Household, Crew, Entity, Co-op, Circle, Trust, Foundation, Confederation, Shadow) a Nomad can join. | +| **Hub API** | The B2B backbone (preview of v0.3 P5) — the Hub Pact exposes custody, a lending primitive, and compliance to service operators. A Nomad sees the Hub through Maps, not directly. | + +## What a Nomad actually does with Pacts + +A Nomad does not draft Pacts by hand. The flow is: + +1. **Find** a service on [Maps & Pay](maps-pay.md). +2. The service's terms are backed by one or more Pacts (e.g., a recurring + payment is a Pause-able Window; a Stand's service is registered in the + Stand Registry). +3. The Nomad **authorizes** a [Window](window.md) scoped to those terms. + +## Mission Lock + +The Pause, Ground, and Stance core terms are mission-locked: a `const` +flag in the Pact module marks them non-amendable, and an invariant test +asserts that flag can never flip. A Nomad can rely on the ground rules +not changing. See [Six Principles](../shared/six-principles.md) for the +mission-lock covenant. + +See [Window](window.md) for the delegation primitive the Pacts are +delivered through, and [Standing](standing.md) for how a service +operator's history is measured. \ No newline at end of file diff --git a/docs/nomads/reach.md b/docs/nomads/reach.md new file mode 100644 index 0000000..af70054 --- /dev/null +++ b/docs/nomads/reach.md @@ -0,0 +1,48 @@ +# Reach + +A **Nomad** is a person using the OpenYield mesh through a **Reach** — the +protocol-level identity that lets a Holder act on the mesh without a +custodian, a gatekeeper, or a legacy financial position. The Reach is the +first of the four Freeholder signals (REQ-005), and it is the baseline every +Nomad starts from: a Nomad is a Holder who has a Reach and a Stash but has not +yet earned all four Freeholder signals. + +## What a Reach is + +A Reach is an identity, not a custodial position. It is the by-ID-string a +Holder uses to receive value, open a [Window](window.md), join a Stand, or +pay for a service. The protocol does not require KYC at the protocol layer; +the Reach is the unit of self-service (see [Six +Principles](../shared/six-principles.md)). + +## How a Nomad starts + +A Nomad starts with two things: + +1. **A Reach** — the identity. +2. **A [Stash](stash.md)** — the personal [Storage Pool](../shared/storage-pools.md) + where the Holder holds Bread. + +That pair is enough to begin. From there a Nomad can use the [bearers](bearers.md) +to reach the mesh, find services on [Maps & Pay](maps-pay.md), authorize a +[Window](window.md) to a partner, and accrue [Standing](standing.md). + +## Geographic proximity + +The mesh processes actions first-come, first-served with a +geographic-proximity preference (REQ-007) — a Nomad physically closer to a +service or a Stand's region is served first. The Reach is how the mesh +identifies the Nomad for that ordering; there is no separate tier to buy into. + +## The four Freeholder signals + +The Reach is the first Freeholder signal. The four signals (REQ-005) are +earned over time: the 90-day [Stash](stash.md) signal, the Standing +threshold, the Capital signal, and the Vouch signal. A Nomad who earns all +four becomes a Freeholder (see the Freeholders section). The pages here cover +the Nomad path — everything up to that point. + +See [Stash](stash.md) for the Storage Pool a Reach holds Bread in, +[Bearers](bearers.md) for how to reach the mesh, and +[Standing](standing.md) for the anti-gaming metric that accrues as a Nomad +acts on the mesh. \ No newline at end of file diff --git a/docs/nomads/standing.md b/docs/nomads/standing.md new file mode 100644 index 0000000..ce2e741 --- /dev/null +++ b/docs/nomads/standing.md @@ -0,0 +1,44 @@ +# Standing + +**Standing** (REQ-006) is a Holder's measured history on the mesh. It is +the anti-gaming metric: a Bayesian score with time-decay, diversity +weighting, and voucher-weighting, minus slashes for bad behavior. For a +Nomad, the headline is that the mesh **cannot be gamed** — Standing +rewards real production and resists the obvious attacks (volume spam, +self-dealing, fake vouches). + +## What Standing is, in plain language + +Standing is not a count of transactions. It is a Bayesian score: the mesh +starts with a prior, updates it from each observed action, and decays +old evidence so a Holder cannot rest on a burst of activity from years +ago. Diversity weighting means a Nomad who acts across many services, +many Stands, and many bearers accrues more Standing than a Nomad who +repeats the same action with the same counterparty. Voucher-weighting +means a vouch from a Holder with high Standing counts for more. + +## Why it matters to a Nomad + +A Nomad mostly reads Standing, not computes it. Two places it shows up: + +- **Choosing a service.** Maps shows a service operator's Standing so a + Nomad can pick an operator with a real history over a freshly-spun-up + alternative (see [Maps & Pay](maps-pay.md)). +- **The Freeholder path.** Earning a Standing threshold in 3 categories + is one of the four Freeholder signals (REQ-005). A Nomad who accrues + Standing over time is on the path to becoming a Freeholder. + +## What Standing is not + +Standing is not a custodial position, a tier you buy, or a reputation +score you can farm. It is not legacy custodial history. The +Bayesian + time-decay + diversity design is exactly what makes it hard to +game: there is no single input a Holder can pump. + +## The math, deferred + +The full Bayesian formula (priors, decay rates, diversity sub-tables, +slash conditions) is documented in the Freeholders section — a Nomad does +not need the math to use the mesh. See +[Six Principles](../shared/six-principles.md) for the covenant Standing +enforces, and [Reach](reach.md) for the identity a Standing accrues to. \ No newline at end of file diff --git a/docs/nomads/stash.md b/docs/nomads/stash.md new file mode 100644 index 0000000..c829749 --- /dev/null +++ b/docs/nomads/stash.md @@ -0,0 +1,48 @@ +# Stash + +A **Stash** is a Holder's personal [Storage Pool](../shared/storage-pools.md) +(REQ-014). It is the place a Nomad holds Bread, and it is the second thing a +Nomad needs after a [Reach](reach.md) 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](window.md) to a partner or a service +without giving up custody. + +## What a Stash is + +The Stash is the Holder-level layer of the three Storage Pools (Stash, +Vault, Root-Pool). It is a storage layer, not a custodial position: the +protocol holds the canonical state that records who owns what; the Holder +holds the value. There is no custodian between a Nomad and their Stash. + +## How a Nomad uses a Stash + +A Nomad moves Bread into a Stash through the [bearers](bearers.md) — a +Holder on a surveillance-resistant bearer can receive value without an +internet connection to OY Chain. From the Stash a Nomad can: + +- **Hold** Bread (the unit of value — see [Bread scale](../shared/bread-scale.md)). +- **Pass** value to another Reach (the Hand-Pass, free at the protocol + level inside a Guild). +- **Pay** for a service via [Maps & Pay](maps-pay.md). +- **Authorize** a [Window](window.md) so a partner or service can read the + Stash within bounds the Holder set. + +## The 90-day Freeholder signal + +Holding a Stash continuously for 90 days is the first of the four +Freeholder signals (REQ-005). The Stash does not need to hold a large +amount — the signal is about continuity, not size. A Nomad who keeps a +Stash for 90 days and earns the other three signals (Standing, Capital, +Vouch) becomes a Freeholder. + +## Delegation, not custody + +The Stash stays the Holder's. When a Nomad opens a Window to a service, +the service gets a scoped capability (e.g., "read Stash balance for the +next hour", "spend up to N Grain on this service this week") — it does not +get custody. The Window is revocable, rate-limited, and audited. See +[Window](window.md) for the primitive. + +See [Storage Pools](../shared/storage-pools.md) for the full three-pool +model, and [Bearers](bearers.md) for how value reaches a Stash over a +surveillance-resistant bearer. \ No newline at end of file diff --git a/docs/nomads/window.md b/docs/nomads/window.md new file mode 100644 index 0000000..cc6e999 --- /dev/null +++ b/docs/nomads/window.md @@ -0,0 +1,45 @@ +# Window + +A **Window** (REQ-015) is the primitive a Nomad uses to delegate a +capability without delegating custody. It is scoped, time-limited, +rate-limited, audited, and revocable. A Nomad opens a Window so a partner +or a service can act on the Nomad's [Stash](stash.md) within bounds the +Nomad set — the partner never gets custody, and the Nomad can close the +Window at any time. + +## The five parts of a Window + +| Part | What it bounds | +|---|---| +| **Scope** | what the grantee can do (e.g., read Stash balance, spend up to N Grain on a specific service). | +| **Duration** | when the Window starts and ends (a start time and an end time). | +| **Rate limit** | how many actions per duration window (e.g., at most 10 reads per hour). | +| **Audit log** | an append-only log of every action the grantee took under the Window. | +| **Revoke** | the Nomad can revoke the Window at any time; revoke after expiry is a no-op. | + +## Why a Nomad opens one + +A Nomad opens a Window for the same reason a Nomad uses [Maps & Pay](maps-pay.md): +to let a service do something on the Nomad's behalf without handing over +the Stash. Common examples: + +- A recurring service (e.g., a Care service) pulls a capped amount of + Bread from the Stash each week, within a rate limit the Nomad set. +- A partner reads the Stash balance for a compliance check, scoped to + read-only, time-limited to one hour. +- A Stand operator processes a Pass-Act on the Nomad's behalf inside a + scoped, audited Window. + +## Lifecycle + +A Window moves through a fixed lifecycle: **Open → Active → Revoked** or +**Expired**. A Nomad can revoke at any point; revoking after expiry is a +no-op (idempotent). The lifecycle is mission-locked: a partner cannot +extend a Window past its end time — the Nomad must open a new one. + +## Self-service, by design + +The Window is the self-service principle in code. The protocol records +the Window on OY Chain; the partner holds only the capability, never the +value. See [Six Principles](../shared/six-principles.md) for the covenant, +and [Pacts](pacts.md) for the contract shapes delivered through Windows. \ No newline at end of file