Skip to content

Commit ef07eb7

Browse files
naorynaory
authored
Merge pull request #27 from mpcp-protocol/docs/reorganize-structure
docs: reorganize structure with conceptual bridge
2 parents c1c5dd7 + c662541 commit ef07eb7

33 files changed

Lines changed: 4143 additions & 92 deletions

‎doc/architecture/MPCP_IMPLEMENTATION_ROADMAP.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -837,6 +837,42 @@ Implemented: `docs/` with overview (what-is-mpcp, problem, comparison-with-agent
837837

838838
⸻
839839

840+
### PR18A — Protocol Chain Hero Diagram
841+
842+
Add a canonical **MPCP Authorization Chain diagram** to the documentation homepage and architecture section.
843+
844+
Diagram structure:
845+
846+
PolicyGrant
847+
→ SignedBudgetAuthorization
848+
→ SignedPaymentAuthorization
849+
→ Settlement
850+
851+
Each layer visually represents how MPCP **progressively constrains machine spending authority**.
852+
853+
Recommended labeling:
854+
855+
• PolicyGrant — defines where and how a machine may pay
856+
• SignedBudgetAuthorization — enforces session spending limits
857+
• SignedPaymentAuthorization — authorizes a specific payment
858+
• Settlement — records what actually happened
859+
860+
Purpose:
861+
862+
• give developers an immediate mental model of MPCP
863+
• visually communicate the protocol’s constrained authorization chain
864+
• establish a recognizable visual identity for MPCP documentation
865+
866+
Deliverables:
867+
868+
• SVG diagram included in docs/diagrams/
869+
• diagram embedded on the docs homepage
870+
• diagram referenced in protocol overview pages
871+
872+
This diagram becomes the **primary visual explanation of the MPCP protocol** and should appear early in the documentation to help new readers understand the authorization model quickly.
873+
874+
⸻
875+
840876
PR19 — Documentation Site Deployment ✓
841877

842878
Deploy the docs site so it is publicly accessible (e.g., GitHub Pages). Implemented: `mkdocs.yml`, `docs-requirements.txt`, `.github/workflows/deploy-docs.yml`. Enable GitHub Pages (Settings → Pages → Source: GitHub Actions) to publish.
@@ -848,6 +884,24 @@ Purpose:
848884

849885
⸻
850886

887+
PR20 — Golden Protocol Vectors ✓
888+
889+
Freeze a set of canonical MPCP test vectors for interoperability and regression testing. Implemented: `vectors/` (manifest.json, valid-settlement.json, expired-grant.json, budget-exceeded.json, intent-hash-mismatch.json, settlement-mismatch.json), `test/vectors/goldenVectors.test.ts`.
890+
891+
Vectors:
892+
• valid settlement (with intent hash)
893+
• expired grant
894+
• budget exceeded
895+
• intent hash mismatch
896+
• settlement mismatch (payment auth)
897+
898+
Purpose:
899+
• let other implementations validate compatibility
900+
• prevent regressions
901+
• create a real interoperability target
902+
903+
⸻
904+
851905
---
852906

853907
# Phase 6 — Adoption Acceleration
@@ -1001,6 +1055,7 @@ Deliverables:
10011055
• basic badge / claim format
10021056
• documentation for how external implementations validate compatibility
10031057

1058+
⸻
10041059

10051060
# Expected Outcome
10061061

‎doc/protocol/FleetPolicyAuthorization.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ Fleet operators must ensure that vehicles only spend funds **within fleet‑defi
2929

3030
FPA enables this capability by allowing fleets to issue **signed policy artifacts** that constrain all MPCP spending decisions.
3131

32+
> **Optional extension:** FleetPolicyAuthorization (FPA) is an optional MPCP artifact used by fleet operators to express higher-level fleet governance constraints. Base MPCP flows do not require FPA.
33+
3234
---
3335

3436
# 2. Problem Statement

‎docs/animation/MPCP_ANIMATION_PACK.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,15 @@ Narration:
2727
## Scene 3 — Introducing MPCP
2828
Visual stack:
2929

30+
Fleet Policy
31+
↓
3032
PolicyGrant
3133
↓
32-
BudgetAuthorization
34+
SignedBudgetAuthorization (SBA)
35+
↓
36+
SignedPaymentAuthorization (SPA)
3337
↓
34-
PaymentAuthorization
38+
SettlementIntent
3539
↓
3640
Settlement
3741

@@ -46,8 +50,8 @@ Narration:
4650
Visual sequence:
4751
1. Autonomous vehicle enters parking garage
4852
2. PolicyGrant appears
49-
3. BudgetAuthorization appears
50-
4. PaymentAuthorization triggers
53+
3. SignedBudgetAuthorization (SBA) appears
54+
4. SignedPaymentAuthorization (SPA) triggers
5155
5. Settlement confirmation
5256

5357
Narration:
@@ -130,7 +134,7 @@ Protocol comparison diagram
130134
"clean animated diagram showing protocols MCP A2A ACP communicating between agents and tools, arrows moving between nodes, modern developer diagram style"
131135

132136
## Prompt 3 — MPCP Authorization Chain
133-
"layered protocol diagram animation PolicyGrant BudgetAuthorization PaymentAuthorization Settlement blocks stacking vertically with glowing arrows"
137+
"layered protocol diagram animation PolicyGrant SignedBudgetAuthorization SignedPaymentAuthorization SettlementIntent Settlement blocks stacking vertically with glowing arrows"
134138

135139
## Prompt 4 — Autonomous Parking Payment
136140
"autonomous car entering smart parking garage, digital authorization layers appearing around vehicle, futuristic payment confirmation animation"
@@ -153,9 +157,11 @@ Icons
153157
- blockchain ledger
154158

155159
Protocol blocks
160+
- Fleet Policy
156161
- PolicyGrant
157-
- BudgetAuthorization
158-
- PaymentAuthorization
162+
- SignedBudgetAuthorization (SBA)
163+
- SignedPaymentAuthorization (SPA)
164+
- SettlementIntent
159165
- Settlement
160166

161167
Animation style

‎docs/architecture/actors.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Actors
2+
3+
MPCP defines several actor types that participate in machine payment flows.
4+
5+
## Fleet Operator
6+
7+
Owns and manages the autonomous fleet (vehicles, robots, agents).
8+
9+
**Responsibilities:**
10+
11+
- Defines vehicle payment policies
12+
- Sets spending limits
13+
- Restricts allowed vendors and locations
14+
- Issues PolicyGrant artifacts
15+
16+
**Examples:** Robotaxi fleet, delivery fleet, autonomous logistics fleet.
17+
18+
## Vehicle Wallet (Machine Wallet)
19+
20+
Resides in each machine (EV, robot, IoT device) and enforces MPCP constraints.
21+
22+
**Responsibilities:**
23+
24+
- Enforces policy constraints
25+
- Manages charging/payment budgets
26+
- Issues SignedBudgetAuthorization and SignedPaymentAuthorization
27+
- Executes settlement transactions
28+
29+
The wallet is the MPCP actor that signs SignedBudgetAuthorization and SignedPaymentAuthorization.
30+
31+
## Service Provider
32+
33+
The entity that receives payment for a service (parking, charging, tolls).
34+
35+
**Responsibilities:**
36+
37+
- Requests payment authorization
38+
- Verifies MPCP artifact chain
39+
- Provides or denies service based on verification
40+
41+
**Examples:** Charging network operator, parking operator, toll system.
42+
43+
## Route / Dispatch System
44+
45+
(Optional) Determines routing and service requirements.
46+
47+
**Responsibilities:**
48+
49+
- Determines charging/parking locations along route
50+
- Identifies approved service networks
51+
- Provides trip metadata to the vehicle
52+
53+
May influence PolicyGrant constraints.
54+
55+
## MPCP Verifier
56+
57+
Validates the full authorization chain.
58+
59+
**Verification may occur:**
60+
61+
- Inside the service provider backend
62+
- Inside a dedicated MPCP verification service
63+
- During post-transaction auditing
64+
65+
## Settlement Rail
66+
67+
Executes the actual payment.
68+
69+
**Examples:** XRPL + RLUSD, EVM stablecoins, Stripe, hosted providers.
70+
71+
MPCP does not replace settlement systems—it **controls authorization above them**.
72+
73+
## See Also
74+
75+
- [Reference Flow](reference-flow.md) — Full actor interaction in EV charging scenario
76+
- [System Model](system-model.md)

‎docs/architecture/artifact-lifecycle.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Artifact Lifecycle
2+
3+
MPCP artifacts flow through a defined lifecycle from policy evaluation to settlement verification.
4+
5+
## Pipeline
6+
7+
```
8+
Fleet Policy
9+
↓
10+
PolicyGrant
11+
↓
12+
SignedBudgetAuthorization
13+
↓
14+
SignedPaymentAuthorization
15+
↓
16+
SettlementIntent
17+
↓
18+
Settlement
19+
```
20+
21+
Each artifact constrains the next. Downstream artifacts must be subsets of upstream constraints.
22+
23+
## Artifact Roles
24+
25+
| Artifact | Issued By | Purpose |
26+
|----------|-----------|---------|
27+
| **PolicyGrant** | Fleet/service policy | Initial permission envelope; rails, assets, caps |
28+
| **SBA** | Vehicle wallet | Session-level spending envelope |
29+
| **SPA** | Vehicle wallet | Binds specific payment to quote and policy |
30+
| **SettlementIntent** | Vehicle wallet | Canonical settlement description (optional hash in SPA) |
31+
| **Settlement Result** | Settlement rail | Confirms execution |
32+
33+
## Typical Lifecycle
34+
35+
1. **Pre-session** — PolicyGrant issued and stored (fleet backend, vehicle wallet)
36+
2. **Session entry** — Vehicle loads PolicyGrant, may issue SBA
37+
3. **Payment request** — Service requests payment; vehicle validates policy and budget
38+
4. **Authorization** — Vehicle creates SettlementIntent, signs SPA
39+
5. **Verification** — Service verifies MPCP chain
40+
6. **Settlement** — Payment executes on rail
41+
7. **Reconciliation** — Settlement verified against authorization
42+
43+
## Storage
44+
45+
Artifacts may be stored in:
46+
47+
- **Fleet backend** — Authoritative PolicyGrant; audit logs
48+
- **Vehicle wallet** — Operational PolicyGrant, SBA, SPA, receipts
49+
- **Service provider** — Received authorizations, verification results, receipts
50+
- **Settlement rail** — Transaction record (authoritative)
51+
52+
## See Also
53+
54+
- [Reference Flow](reference-flow.md) — End-to-end EV charging scenario with timeline
55+
- [Protocol specs](protocol/mpcp.md) — Full artifact specifications

‎docs/architecture/authorization-chain.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# MPCP Authorization Chain
2+
3+
The **authorization chain** is the core visual model for MPCP. Each step produces a verifiable artifact that constrains the next. Machines spend within bounds established upstream—no per-transaction approval required.
4+
5+
```
6+
PolicyGrant
7+
↓
8+
SignedBudgetAuthorization
9+
↓
10+
SignedPaymentAuthorization
11+
↓
12+
SettlementIntent
13+
↓
14+
Settlement
15+
```
16+
17+
In fleet deployments, an optional FleetPolicyAuthorization (FPA) layer may sit above PolicyGrant.
18+
19+
```
20+
Fleet Policy
21+
↓
22+
PolicyGrant
23+
↓
24+
SignedBudgetAuthorization
25+
↓
26+
SignedPaymentAuthorization
27+
↓
28+
SettlementIntent
29+
↓
30+
Settlement
31+
```
32+
33+
## What Each Step Does
34+
35+
| Step | Artifact | Purpose |
36+
|------|-----------|---------|
37+
| **Fleet Policy** | Policy definition | Rules: rails, assets, vendors, caps |
38+
| **PolicyGrant** | Session entry | "This machine may initiate payment under these constraints" |
39+
| **SignedBudgetAuthorization** | Spending envelope | "Up to X, on these rails, to these destinations" |
40+
| **SignedPaymentAuthorization** | Payment binding | "This exact payment was authorized" |
41+
| **SettlementIntent** | Canonical description | Deterministic settlement parameters (optional hash binding) |
42+
| **Settlement** | Executed transaction | Rail executes payment; verifier checks chain |
43+
44+
## Key Idea
45+
46+
Approval moves **upstream**. The human or policy administrator grants a **session** and **budget**. The machine spends within that budget using pre-authorized intents. Settlement becomes a background operation.
47+
48+
## See Also
49+
50+
- [System Model](system-model.md) — How the chain fits in the overall architecture
51+
- [Artifact Lifecycle](artifact-lifecycle.md) — When each artifact is created
52+
- [Reference Flow](reference-flow.md) — Full EV charging walkthrough
53+
- [Protocol: Artifacts](protocol/artifacts.md) — Detailed artifact specs

0 commit comments

Comments
 (0)