Skip to content

Commit 12821a9

Browse files
CMCDragonkaiCMCDragonkai
committed
feat: added trust operating system ecosystem flywheel and receipt rails operational flow
1 parent 23b0e4d commit 12821a9

File tree

6 files changed

+2231
-339
lines changed

6 files changed

+2231
-339
lines changed

‎docs/theory/receipt-rails-operational-flow.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Receipt Rails Operational Flow
2+
3+
This document outlines the fundamental operational flow of the Polykey
4+
ecosystem, which we call the Receipt Rails. It illustrates the complete
5+
lifecycle of a verifiable event, from the initial grant of authority to the
6+
final acceptance of a cryptographic receipt by a third party.
7+
8+
The core principle of the Receipt Rails is to create a standardized, secure, and
9+
auditable process for proving that a specific action was performed or a specific
10+
outcome was achieved. This is accomplished through a sequence of interactions
11+
between four key actors: the Principal (who grants authority), the Subject (who
12+
performs the action), the Resource (the target of the action), and the Verifier
13+
(who accepts the proof).
14+
15+
Below are two diagrams. The first provides a high-level, summary view of the
16+
entire flow. The second diagram is a detailed, technical zoom-in on the most
17+
critical and complex step: the Enforcement of a capability. Understanding both
18+
is key to grasping the full power and flexibility of the system.
19+
20+
## Core Operational Flow (Summary View)
21+
22+
This diagram shows the end-to-end lifecycle. It begins with a Principal issuing
23+
a Grant, which authorizes a Subject to perform an action. The Subject then
24+
presents this authority to an Enforcement Point, which results in the minting of
25+
verifiable receipts. These receipts are then assembled into a View for a
26+
Verifier, who can accept them for settlement, compliance, or payment.
27+
28+
```mermaid
29+
---
30+
title: The Receipt Rails - Core Operational Flow
31+
config:
32+
theme: redux-color
33+
---
34+
sequenceDiagram
35+
participant P as Principal (P)<br>- Sigchain (P)<br>- Vault (leases/policy)
36+
participant S as Subject (S)<br>- Sigchain (S)
37+
participant R as Resource / ToA / SoA<br>(e.g., API, Power Grid, Door Lock)
38+
participant V as Verifier / Auditor / Escrow<br>(TAP/RAM acceptance)
39+
40+
autonumber
41+
Note over P: Issue Grant G<br>[write G to P’s Sigchain]
42+
P ->> S: notify/ref (push or pull) for G
43+
44+
rect rgba(0,0,0,0.04)
45+
note left of P: Enforcement Variants
46+
alt Principal-side CEP (placement=P, bridging=true) [PS-BA]
47+
S ->> P: Present capability (Presentation)
48+
Note over P: Enforce at P CEP (mediate / derive / reveal)<br>Write Access PoAR on P's sigchain<br>Deliver PoAR to S
49+
else Resource-side CEP (placement=R, bridging=false) [native]
50+
S ->> R: Present capability (Presentation)
51+
Note over S,R: Enforce at Resource CEP<br>Write Access PoAR on R's sigchain<br>Deliver PoAR to S
52+
else Subject-side CEP (placement=S, bridging=false) [SSA wallet/session]
53+
S ->> S: Present capability (internal Presentation)
54+
S ->> S: Derive short-scope token
55+
S ->> R: ToA API call (using token)
56+
Note over S: Write Access PoAR on S's sigchain
57+
else Subject-side CEP (placement=S, bridging=true) [SS-BA, rare]
58+
S ->> S: Present capability (internal Presentation)
59+
S ->> S: Derive or reveal using S-owned lease
60+
S ->> R: ToA API call
61+
Note over S: Write Access PoAR on S's sigchain
62+
end
63+
end
64+
65+
opt UseReceipt (optional, TAP may require)
66+
S ->> S: Write UseReceipt (ref G & PoAR P)
67+
end
68+
69+
opt Outcome measurable
70+
Note over S,R: Measuring agent writes VOR where observed
71+
alt Subject-side measurer
72+
S ->> S: Write VOR
73+
else Resource-native measurer
74+
R ->> R: Write VOR
75+
end
76+
end
77+
78+
par Either P or S assembles View
79+
P ->> V: ViewReceipt {G, PoAR, Use?, VOR?} (with lens & tapProfile)
80+
S ->> V: ViewReceipt {G, PoAR, Use?, VOR?} (with lens & tapProfile)
81+
end
82+
83+
V ->> V: Accept/Settle (per TAP/RAM)
84+
Note right of V: Accept / Pay / Comply
85+
86+
Note over P,S: Storage/Durability:<br>- Hot: recent envelopes + index<br>- Seal: Merkle segments + SegmentReceipt<br>- Cold: Custody (S3/MinIO/IPFS, E2E enc)<br>- Escrow: PinningReceipt<br>- Anchors: AnchorReceipt (hash-only)
87+
```
88+
89+
### How to Read This Diagram
90+
91+
- Participants:
92+
- P (Principal): The entity granting authority (e.g., a DevOps lead, a
93+
homeowner).
94+
- S (Subject): The entity performing the action (e.g., a CI/CD runner, a smart
95+
lock app).
96+
- R (Resource): The target of the action (e.g., a Kubernetes API, a Power
97+
Grid, a Door Lock).
98+
- V (Verifier): The entity that needs proof (e.g., an Auditor, an Insurer, an
99+
Escrow agent).
100+
- The Happy Path: The numbered steps show the ideal flow from Issue Grant G to
101+
Accept/Settle.
102+
- Enforcement Variants (The `alt` block): This block is a high-level summary of
103+
the four ways that authority can be enforced, depending on where the
104+
"gatekeeper" (the CEP) is located. This is the most complex part of the
105+
system, and it is expanded in full detail in the second diagram.
106+
- Receipts (`opt` blocks): The flow generates several types of receipts. The
107+
Access PoAR (Proof of Action) is the primary receipt proving the action was
108+
authorized. The UseReceipt is an optional acknowledgment from the Subject, and
109+
the VOR (Verifiable Outcome Receipt) is a separate proof of the result.
110+
- Durability (Bottom Note): This note shows the layered approach to storage,
111+
ensuring receipts are both readily available ("Hot") and securely archived for
112+
the long term ("Cold"), with options for independent verification
113+
("Escrow/Anchors").
114+
115+
## Enforcement Variants - Detailed View
116+
117+
This diagram is a detailed zoom-in of the "Enforcement Variants" block from the
118+
first diagram. It shows the precise mechanics of how a capability is verified
119+
and enforced in each of the four possible architectural patterns. The choice of
120+
pattern depends on whether the Resource is a modern, PK-native system or a
121+
legacy one, and on the security requirements of the transaction.
122+
123+
```mermaid
124+
---
125+
title: Enforcement Variants - Detailed View of CEP Placements and Modes
126+
config:
127+
theme: redux-color
128+
---
129+
sequenceDiagram
130+
participant P as Principal (P)<br>- Sigchain (P)<br>- Vault (leases/policy)
131+
participant S as Subject (S)<br>- Sigchain (S)
132+
participant R as Resource / ToA / SoA<br>(e.g., API, Power Grid, Door Lock)
133+
participant V as Verifier / Auditor / Escrow<br>(TAP/RAM acceptance)
134+
135+
autonumber
136+
137+
alt Principal-side CEP (placement=P, bridging=true) [PS-BA]
138+
Note over P: If P and R are the same trust boundary<br>this is effectively native (colocated)<br>bridging=false, PoAR still on P's sigchain
139+
S ->> P: Present capability (Presentation)
140+
break Verification fails at P
141+
Note over P: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
142+
Note over P: Write DenyReceipt on P's sigchain
143+
P ->> S: Deliver DenyReceipt
144+
end
145+
alt Mediate at P
146+
Note over P: Verify Presentation + Bind + fresh LeaseRef<br>Record requestDigest vs Allowed-Surface
147+
P ->> R: ToA API call
148+
R -->> P: Result
149+
P -->> S: Result (if requester expects data)
150+
else Derive at P
151+
Note over P: Verify Presentation + Bind + fresh LeaseRef
152+
P ->> S: Short-scope token (session-bound)
153+
S ->> R: ToA API call (using token)
154+
R -->> S: Result
155+
else Reveal at P (last resort)
156+
Note over P: Break-glass<br>dual-control, tiny ttl/scope, audit correlation, immediate revoke
157+
P ->> S: Raw secret
158+
S ->> R: ToA API call (bearer)
159+
R -->> S: Result
160+
end
161+
Note over P: Write Access PoAR on P's sigchain<br>exposureMode = mediate/derive/reveal
162+
P ->> S: Deliver PoAR
163+
164+
else Resource-side CEP (placement=R, bridging=false) [native]
165+
S ->> R: Present capability (Presentation)
166+
break Verification fails at R
167+
Note over R: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
168+
Note over R: Write DenyReceipt on R's sigchain
169+
R ->> S: Deliver DenyReceipt
170+
end
171+
Note over R: Enforce at Resource CEP
172+
R -->> S: Result (if requester expects data)
173+
Note over R: Write Access PoAR on R's sigchain
174+
R ->> S: Deliver PoAR
175+
176+
else Subject-side CEP (placement=S, bridging=false) [SSA wallet/session]
177+
Note over S: S does not hold long-lived upstream lease.
178+
S ->> S: Present capability (internal Presentation)
179+
break Verification fails at S
180+
Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
181+
Note over S: Write DenyReceipt on S's sigchain
182+
%% Optional notify P for audit
183+
S -->> P: Notify DenyReceipt (policy-dependent)
184+
end
185+
S ->> S: Derive short-scope token (federated/workload identity)
186+
S ->> R: ToA API call (using token)
187+
R -->> S: Result
188+
Note over S: Write Access PoAR on S's sigchain
189+
190+
else Subject-side CEP (placement=S, bridging=true) [SS-BA, rare]
191+
S ->> S: Present capability (internal Presentation)
192+
break Verification fails at S
193+
Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
194+
Note over S: Write DenyReceipt on S's sigchain
195+
%% Optional notify P for audit
196+
S -->> P: Notify DenyReceipt (policy-dependent)
197+
end
198+
alt Mediate at S (no token egress)
199+
Note over S: Mediate only when S wants to ensure that no token ever leaves the CEP
200+
S ->> R: ToA API call using S-held lease (or short-scope token retained at S)
201+
R -->> S: Result
202+
else Derive at S (preferred)
203+
S ->> S: Derive short-scope token from S-held lease
204+
S ->> R: ToA API call (using token)
205+
R -->> S: Result
206+
else Reveal at S (last resort)
207+
Note over S: Break-glass only when S owns upstream<br>tiny ttl/scope, dual-control, audit correlation, immediate revoke
208+
S ->> S: Reveal raw secret to caller
209+
S ->> R: ToA API call (bearer)
210+
R -->> S: Result
211+
end
212+
Note over S: Write Access PoAR on S's sigchain
213+
end
214+
```
215+
216+
### How to Read This Diagram
217+
218+
- The Four Variants (`alt` blocks):
219+
- Principal-side CEP [PS-BA]: This is the default pattern for bridging to
220+
legacy systems. The Principal's agent acts as a secure "butler" (a Bridge
221+
Adapter), holding the master key and interacting with the legacy Resource on
222+
the Subject's behalf. It details the three modes: Mediate, Derive, and
223+
Reveal.
224+
- Resource-side CEP [native]: This is the ideal, end-state pattern for modern,
225+
PK-native systems. The Resource itself has a built-in enforcement point. It
226+
can verify the Subject's capability directly, without an intermediary.
227+
- Subject-side CEP [SSA wallet/session]: This pattern is for federated
228+
identity scenarios. The Subject's agent uses its own strong identity (e.g.,
229+
a cloud workload identity) to Derive a temporary credential directly from
230+
the Resource.
231+
- Subject-side CEP [SS-BA, rare]: This is a rare pattern used only when the
232+
Subject itself owns the master key to a legacy system it needs to bridge.
233+
- The Deny Path (`break` blocks): Each variant includes an explicit flow for
234+
what happens when verification fails. The enforcing CEP mints a DenyReceipt
235+
with a reason code, providing a verifiable audit trail of failed attempts.
236+
- PoAR Provenance: Crucially, this diagram shows who mints the Access PoAR in
237+
each case. The rule is simple: the enforcer mints the proof. This means the
238+
PoAR is written to the sigchain of P, R, or S, depending on the variant used.
239+
This is fundamental to the system's distributed and verifiable nature.

‎docs/theory/trust-operating-system.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Trust Operating System
2+
3+
In today's interconnected world, trust is fracturing. Opaque, centralized
4+
systems are struggling to keep pace with the complexity of global trade, AI
5+
agency, and the need for digital sovereignty. A new foundation is needed.
6+
7+
Polykey is building the open, interoperable infrastructure that allows diverse,
8+
sovereign actors to transact with cryptographic certainty. We turn real-world
9+
actions into settlement-grade receipts, enabling a new era of secure, efficient,
10+
and trustworthy collaboration. We believe the future is not about closed,
11+
competing stacks, but about shared, open protocols that create value for
12+
everyone.
13+
14+
## Ecosystem Flywheel Map
15+
16+
This single diagram provides the complete, top-level map of Polykey's ecosystem
17+
virtuous cycle, showing how each layer and component logically enables the next,
18+
from the deepest "why" to the most practical "where."
19+
20+
```mermaid
21+
---
22+
title: "Polykey Ecosystem Flywheel Map: From Verifiable Security to a Verifiable Economy"
23+
config:
24+
layout: elk
25+
htmlLabels: true
26+
---
27+
flowchart TB
28+
subgraph GRN["<span style='white-space: nowrap'>THE GRAND NARRATIVE (The 'Why')</span>"]
29+
GRN1["Trust Operating System:<br>From Sovereign Stacks to The Interoperability Regime (Federated Model)"]
30+
GRN2["Our Mission: Build the 'Receipt Rails' - a neutral, verifiable utility for the cyber-physical economy."]
31+
end
32+
subgraph AF["<span style='white-space: nowrap'>THE ACCEPTANCE FRAMEWORK (The 'So What?')</span>"]
33+
direction LR
34+
TAP["TAP (Threat & Acceptance Policy)<br> - The Rulebook"]
35+
RAM["RAM <br>(Receipt Acceptance Memo)<br> - The Social Contract"]
36+
ATN["Accredited Trust Network (ATN)<br>- The Governance Body"]
37+
end
38+
subgraph RE["<span style='white-space: nowrap'>THE RECEIPT ENGINE (The 'What')</span>"]
39+
direction LR
40+
PoAR["PoAR (Proof of Action)"]
41+
VOR["VOR (Verifiable Outcome Record)"]
42+
ViewRec["ViewReceipt & E-Pack<br>(Settlement-Grade Evidence)"]
43+
end
44+
subgraph AFAB["<span style='white-space: nowrap'>THE AUTHORITY FABRIC (The 'How')</span>"]
45+
direction LR
46+
Ident["Identity (Gestalts)"]
47+
Capab["Capabilities<br>(Identity- & Secret-Bound)"]
48+
Sigchain["Sigchain (The Verifiable Ledger)"]
49+
end
50+
subgraph RW["<span style='white-space: nowrap'>THE REAL WORLD (The 'Where' - Wedges & Primitives)</span>"]
51+
direction LR
52+
Polykey["The Polykey Vault<br>(Cold Storage for Authority Assets)"]
53+
CEP["The CEP / Bridge Adapter<br>(The Enforcement Point / The Legacy Bridge)"]
54+
Wedge["The Wedge Portfolio<br>(DevOps, Identity, Energy, Supply Chain, etc.)"]
55+
end
56+
TAP --> RAM
57+
RAM --> ATN
58+
PoAR --> VOR
59+
VOR --> ViewRec
60+
Ident --> Capab
61+
Capab --> Sigchain
62+
Polykey --> CEP
63+
CEP --> Wedge
64+
GRN -- Informs & Justifies --> AF
65+
AF -- Governs & Validates --> RE
66+
RE -- Is Enabled By & Built On --> AFAB
67+
AFAB -- Manages & Secures --> RW
68+
```
69+
70+
### How to Read This Diagram
71+
72+
1. **The Grand Narrative (Top):** This is the mission. It's the big story about
73+
the global shift towards a new way of organizing trust.
74+
2. **The Acceptance Framework (Layer 2):** This is the crucial socio-technical
75+
layer that translates the vision into something the real world can accept.
76+
The TAP is a set of rules, the RAM is the proof that powerful entities
77+
(insurers, regulators) agree to the rules, and the ATN is the resulting
78+
network of trusted actors.
79+
3. **The Receipt Engine (Layer 3):** This is the core "product" of the system.
80+
It's the engine that runs on the authority fabric to produce the valuable
81+
artifacts (PoARs, VORs, and ViewReceipts) that are governed by the Acceptance
82+
Framework.
83+
4. **The Authority Fabric (Layer 4):** This is the foundational technology, the
84+
"how." It's the deep, non-consensus innovation of Polykey: the combination of
85+
sovereign Identity, a rich Capability model, and the immutable Sigchain
86+
ledger.
87+
5. **The Real World (Bottom):** This is where the rubber meets the road.
88+
- The **Polykey Vault** is the essential primitive for securely storing the
89+
"cold" assets of the Authority Fabric.
90+
- The **CEP / Bridge Adapter** is the enforcement point that connects the
91+
Authority Fabric to the real world, allowing it to mint receipts.
92+
- The **Wedge Portfolio** is the strategic application of this entire stack
93+
to solve specific, high-value problems in the market.
94+
95+
### The Flywheel Effect
96+
97+
- Success in the Wedges proves the value of the entire stack.
98+
- This drives adoption of the Primitives (Vaults, CEPs).
99+
- Which generates more activity in the Authority Fabric and the Receipt Engine.
100+
- Which creates more demand for a robust Acceptance Framework (more TAPs and
101+
RAMs).
102+
- Which, in turn, validates and strengthens the Grand Narrative, attracting more
103+
partners and capital to launch new Wedges.

‎docusaurus.config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,11 +240,15 @@ const config: Config = {
240240
defaultLocale: 'en',
241241
locales: ['en'],
242242
},
243+
markdown: {
244+
mermaid: true
245+
},
243246
// This ensures that `/x.md` is generated as `/x/index.html` and not `/x.html`.
244247
// Which is the expected directory layout for most web servers.
245248
trailingSlash: undefined,
246249
staticDirectories: ['static'],
247250
plugins: [pluginSVGR, pluginDocs, pluginTheme, pluginGTag, pluginTailwind],
251+
themes: ['@docusaurus/theme-mermaid'],
248252
themeConfig,
249253
};
250254

0 commit comments

Comments
 (0)