Merge pull request #53 from mpcp-protocol/docs/phase-6-adoption-acceleration

naory · web-flow · commit 7e5a4d5f1465 · 2026-04-04T19:31:00.000+03:00
docs: complete Phase 6 — Adoption Acceleration (PR21–PR25)
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -78,15 +78,15 @@ Implements: protocol verification engine, artifact schemas, cryptographic signin
 
 ---
 
-## Phase 6 — Adoption Acceleration
+## Phase 6 — Adoption Acceleration ✓
 
 | PR | Title | Status |
 |----|-------|--------|
-| PR21 | Payment profiles expansion (XRPL Stablecoin, RLUSD) | pending |
-| PR22 | Layer-1 ecosystem evaluation (XRPL, Hedera, Stellar, EVM) | pending |
-| PR23 | Machine wallet guardrails documentation | pending |
-| PR24 | Automated fleet payment demo (visual end-to-end) | pending |
-| PR25 | MPCP conformance badge | pending |
+| PR21 | Payment profiles expansion (XRPL Stablecoin, RLUSD) | ✓ |
+| PR22 | Layer-1 ecosystem evaluation (XRPL, Hedera, Stellar, EVM) | ✓ |
+| PR23 | Machine wallet guardrails documentation | ✓ |
+| PR24 | Automated fleet payment demo (visual end-to-end) | ✓ |
+| PR25 | MPCP conformance badge | ✓ |
 | PR26 | Human-to-Agent Delegation Profile (`revocationEndpoint`, `allowedPurposes`, TRIP scope, `checkRevocation()`) | ✓ |
 | PR27 | On-Chain Policy Anchoring (`anchorRef`, `resolveXrplDid`, `hederaHcsAnchorPolicyDocument`, `checkXrplNftRevocation`) | ✓ |
 | PR28 | Encrypted Policy Anchoring (`submitMode`, AES-256-GCM via `crypto.subtle`, `PolicyDocumentCustody`, XRPL IPFS prep) | ✓ |
@@ -154,65 +154,57 @@ All three functions flat-exported from `src/sdk/index.ts`, consistent with exist
 
 ---
 
-## PR21 — Payment Profiles Expansion
+## PR21 — Payment Profiles Expansion ✓
 
-Expand reference profiles so MPCP is immediately usable for real payment ecosystems.
+XRPL Stablecoin profile — RLUSD / issued-asset payment constraints, wallet and verifier expectations.
 
-Initial focus:
-- XRPL Stablecoin Profile — RLUSD / issued-asset payment constraints
-- Wallet and verifier expectations for stablecoin settlement
-
-Future candidates: Stellar, Hedera, EVM stablecoin.
-
-Deliverables:
-- Profile document(s)
-- Example artifact bundles
-- Verification guidance per profile
+Delivered:
+- `docs/implementation/xrpl-stablecoin-profile.md` — full profile doc (asset constraints, policy shape, wallet/verifier expectations, Trust Gateway integration)
+- `profiles/xrpl-stablecoin.json` — machine-readable profile definition
+- `examples/xrpl-stablecoin/` — example artifact bundle + README
+- `docs/implementation/reference-profiles.md` updated with XRPL Stablecoin entry
 
 ---
 
-## PR22 — Layer-1 Ecosystem Evaluation
-
-Research and document which L1/payment ecosystem to prioritize next for MPCP deployment profiles.
+## PR22 — Layer-1 Ecosystem Evaluation ✓
 
-Evaluation criteria: stablecoin support, settlement finality, fees, compliance features, offline/verifier friendliness, developer tooling.
+Research document comparing XRPL, Stellar, Hedera, and EVM (L2) against MPCP settlement requirements: stablecoin maturity, budget reservation, finality, fees, identity, offline friendliness, tooling.
 
-Deliverables:
-- Research document comparing candidates
-- Recommended next profile target with rationale
+Delivered:
+- `docs/implementation/l1-ecosystem-evaluation.md` — full comparison matrix and recommendation
+- **Recommendation:** Stellar (USDC + Claimable Balances) as next rail; EVM L2 second; Hedera continues as anchoring layer
 
 ---
 
-## PR23 — Machine Wallet Guardrails
+## PR23 — Machine Wallet Guardrails ✓
 
-Document and demonstrate how MPCP acts as a machine wallet guardrail layer: a machine wallet may not send funds unless the payment satisfies the full PolicyGrant → SBA → SPA constraint chain.
+How MPCP acts as a machine wallet guardrail layer: PolicyGrant constraints, SBA session limits, Trust Gateway verification.
 
-Deliverables:
-- Guide describing the guardrail model
-- Wallet integration example
-- Threat-model notes for overspend and misuse prevention
+Delivered:
+- `docs/implementation/machine-wallet-guardrails.md` — guardrail model, Layer 1/2/3 enforcement, threat model, XRPL memo integration
+- `docs/examples/machine-wallet-guardrails.md` — example walkthrough
+- `examples/machine-wallet-guardrails/wallet-integration.mjs` — runnable script with allowed/rejected scenarios
 
 ---
 
-## PR24 — Automated Fleet Payment Demo
+## PR24 — Automated Fleet Payment Demo ✓
 
-Visual end-to-end demonstration of an MPCP-controlled fleet payment (vehicle → parking/charging facility → verifier → settlement).
+End-to-end fleet payment demonstrations with architecture diagrams and runnable scripts.
 
-Deliverables:
-- Runnable demo script
-- Architecture diagram
-- Companion documentation
+Delivered:
+- `examples/fleet-trip/` — multi-stop robotaxi demo (toll, charging, parking, tamper detection); `demo-fleet-trip.mjs`
+- `examples/machine-commerce/` — fleet spend simulator (`simulate.mjs`), fleet demo (`demo-fleet.mjs`), scenarios + policy JSON
+- `docs/examples/fleet.md` — architecture diagram (Vehicle Agent → Verifier → Trust Gateway → XRPL), run instructions, key behaviors
 
 ---
 
-## PR25 — MPCP Conformance Badge
+## PR25 — MPCP Conformance Badge ✓
 
-Lightweight conformance process: implementations that pass the golden vectors and required verification checks may claim compatibility.
+Formal conformance tiers (L0–L3), Shields.io badge, `package.json` claim format, implementer checklist.
 
-Deliverables:
-- Conformance criteria
-- Badge / claim format
-- Documentation for external implementers
+Delivered:
+- `docs/implementation/conformance.md` — expanded with L0 Hash / L1 Structural / L2 Full-chain / L3 Profile tiers; badge format; `package.json` claim schema; per-tier implementer checklist
+- Aligns with `mpcp-spec/test-vectors/CONFORMANCE.md` (L0/L1/L2 definitions)
 
 ---
 
diff --git a/docs/implementation/conformance.md b/docs/implementation/conformance.md
@@ -1,15 +1,147 @@
 # Conformance
 
-MPCP implementations can be verified for conformance to the protocol specification.
+MPCP implementations can be verified for conformance to the protocol specification. This page defines **conformance tiers**, the **verification vectors** used to test them, the **MPCP Conformance Badge** for external implementers, and a **self-assessment checklist**.
 
-## Conformance Levels
+---
 
-| Level | Scope | Description |
-|-------|-------|-------------|
-| **Artifact** | Single artifact | Produces valid PolicyGrant and SBA per spec |
-| **Chain** | Full authorization chain | Links artifacts correctly (policyHash, sessionId, constraints) |
-| **Verification** | Settlement verification | Passes all verification checks for valid bundles |
-| **Profile** | Deployment profile | Matches a reference profile (parking, charging, fleet-offline, hosted-rail) |
+## Conformance Tiers
+
+Tiers are cumulative — each level assumes all lower levels pass.
+
+| Tier | Name | Scope | What it proves |
+|------|------|-------|----------------|
+| **L0** | Hash | Canonical JSON + domain-separated hashing | Your serialization is deterministic and hashes match the reference |
+| **L1** | Structural | Artifact shape + constraint propagation | Your artifacts contain all required fields and SBA ⊆ PolicyGrant holds |
+| **L2** | Full-chain verification | Signatures, linkage, budget, expiry, XRPL conformance | Your verifier accepts valid chains and rejects invalid ones identically to the reference implementation |
+| **L3** | Profile | Deployment profile conformance | Your implementation matches a named reference profile (parking, charging, fleet-offline, xrpl-stablecoin, hosted-rail) |
+
+### L0 — Canonical Hash Reproduction
+
+Recompute `SHA-256(UTF-8(prefix) || canonical_json(payload))` for each entry in [`test-vectors/expected-hashes.json`](https://github.com/mpcp-protocol/mpcp-spec/blob/main/test-vectors/expected-hashes.json) and obtain the documented hex digest.
+
+Tooling: [`verify_test_vectors.py`](https://github.com/mpcp-protocol/mpcp-spec/blob/main/test-vectors/verify_test_vectors.py) (exit code 0 on success).
+
+### L1 — Structural Sanity
+
+Parse all `*-v1-minimal.json` fixtures in `test-vectors/` and confirm required fields are present with correct types. This does not replace normative schema definitions — it catches structural regressions.
+
+### L2 — Full-Chain Verification
+
+Verify golden vectors end-to-end using your verifier:
+
+| Vector | Expected result |
+|--------|----------------|
+| `valid-settlement.json` | Pass — full chain valid |
+| `expired-grant.json` | Fail — `policy_grant_expired` |
+| `budget-exceeded.json` | Fail — `budget_exceeded` |
+| `settlement-mismatch.json` | Fail — settlement does not match SBA constraints |
+
+Run against the reference:
+
+```bash
+npx mpcp verify test/vectors/valid-settlement.json --explain
+npx mpcp verify test/vectors/expired-grant.json --explain
+```
+
+L2 also requires signature verification (Ed25519 or P-256) and Trust Bundle key resolution.
+
+### L3 — Profile Conformance
+
+Validate that your deployment matches a named profile from [Reference Profiles](reference-profiles.md):
+
+```bash
+mpcp policy-summary your-policy.json --profile parking
+```
+
+Profile conformance checks: `allowedRails` subset, asset constraints, and profile-specific fields.
+
+---
+
+## MPCP Conformance Badge
+
+External implementations that pass conformance testing may claim an MPCP conformance badge.
+
+### Badge Format
+
+Use a [Shields.io](https://shields.io) badge in your README:
+
+```markdown
+![MPCP Conformance](https://img.shields.io/badge/MPCP-L2%20Conformant-blue)
+```
+
+Rendered: ![MPCP Conformance](https://img.shields.io/badge/MPCP-L2%20Conformant-blue)
+
+Replace `L2` with the highest tier your implementation passes (`L0`, `L1`, `L2`, or `L3`).
+
+### package.json Claim
+
+Add a structured conformance claim to your `package.json`:
+
+```json
+{
+  "mpcp": {
+    "conformance": "L2",
+    "specVersion": "1.0",
+    "testedWith": "mpcp-service@0.1.0",
+    "profiles": ["xrpl-stablecoin"]
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `conformance` | Yes | Highest tier passed: `L0`, `L1`, `L2`, or `L3` |
+| `specVersion` | Yes | MPCP spec version tested against |
+| `testedWith` | Recommended | Reference implementation package and version used for verification |
+| `profiles` | L3 only | Array of profile names the implementation conforms to |
+
+### Claim Rules
+
+1. **Self-assessed** — conformance is self-declared; there is no central certification authority
+2. **Reproducible** — the implementation must include instructions for running the conformance vectors
+3. **Versioned** — claims are tied to a specific `specVersion`; a new spec revision requires re-testing
+4. **Honest** — do not claim a tier unless all lower tiers also pass
+
+---
+
+## Implementer Checklist
+
+Use this checklist when preparing a conformance claim:
+
+### L0 (Hash)
+
+- [ ] `canonicalJson(obj)` produces identical output to the reference for all test payloads
+- [ ] Domain-separated hash: `SHA-256("MPCP:TrustBundle:1.0:" + canonical)` matches for Trust Bundle vectors
+- [ ] Domain-separated hash: `SHA-256("MPCP:PolicyGrant:1.0:" + canonical)` matches for PolicyGrant vectors
+- [ ] Domain-separated hash: `SHA-256("MPCP:BudgetAuthorization:1.0:" + canonical)` matches for SBA vectors
+- [ ] `verify_test_vectors.py` exits with code 0
+
+### L1 (Structural)
+
+- [ ] All minimal JSON fixtures parse without error
+- [ ] Required fields present on PolicyGrant: `grantId`, `issuer`, `subject`, `purposes`, `allowedRails`, `budgetMinor`, `currency`, `expiresAt`
+- [ ] Required fields present on SBA: `sessionId`, `grantId`, `policyHash`, `maxAmountMinor`, `currency`, `expiresAt`
+- [ ] Constraint propagation: SBA `maxAmountMinor` ≤ PolicyGrant `budgetMinor`; SBA `expiresAt` ≤ PolicyGrant `expiresAt`
+
+### L2 (Full-chain)
+
+- [ ] `valid-settlement.json` passes full verification
+- [ ] `expired-grant.json` fails with reason `policy_grant_expired`
+- [ ] `budget-exceeded.json` fails with reason `budget_exceeded`
+- [ ] `settlement-mismatch.json` fails with settlement constraint mismatch
+- [ ] Ed25519 signature verification succeeds for valid artifacts
+- [ ] Ed25519 signature verification fails for tampered artifacts
+- [ ] Trust Bundle key resolution works (`resolveFromTrustBundle`)
+- [ ] Expired Trust Bundles are rejected
+
+### L3 (Profile)
+
+- [ ] `allowedRails` in policy is a subset of the profile's permitted rails
+- [ ] Asset constraints match profile definition (e.g., XRPL stablecoin: `kind: IOU`, valid `issuer`)
+- [ ] Profile-specific checks pass (e.g., `offlineMaxSinglePayment` for fleet-offline)
+- [ ] `mpcp policy-summary` with `--profile` flag reports no violations
+
+---
 
 ## Verification Vectors
 
@@ -20,25 +152,17 @@ The reference implementation includes golden vectors in `test/vectors/` for conf
 - `budget-exceeded.json` — Amount exceeds budget, must fail
 - `settlement-mismatch.json` — Settlement does not match SBA constraints, must fail
 
-Run the conformance tests:
-
-```bash
-npm test
-npx mpcp verify test/vectors/valid-settlement.json --explain
-```
-
-## Self-Assessment
+Additional hash vectors are in [`mpcp-spec/test-vectors/`](https://github.com/mpcp-protocol/mpcp-spec/tree/main/test-vectors):
 
-Implementers should verify:
+- `expected-hashes.json` — canonical hash reference for L0
+- `*-v1-minimal.json` — structural fixtures for L1
 
-1. **Artifact structure** — All required fields present, types correct
-2. **Canonical JSON** — Deterministic serialization for hashing
-3. **Domain-separated hashing** — Correct prefix per artifact type
-4. **Signature verification** — Valid key resolution and signature check
-5. **Constraint propagation** — SBA ⊆ PolicyGrant
+---
 
 ## See Also
 
+- [Test Vectors — Conformance Levels](https://github.com/mpcp-protocol/mpcp-spec/blob/main/test-vectors/CONFORMANCE.md) — L0 / L1 / L2 definitions in the spec repo
 - [MPCP Reference Flow](https://github.com/mpcp-protocol/mpcp-spec/blob/main/docs/architecture/reference-flow.md) — Canonical flow for EV charging
 - [Verifier](verifier.md) — Verification pipeline
+- [Reference Profiles](reference-profiles.md) — Named deployment profiles for L3
 - [Protocol: mpcp](https://github.com/mpcp-protocol/mpcp-spec/blob/main/docs/protocol/mpcp.md) — Full specification
diff --git a/docs/implementation/l1-ecosystem-evaluation.md b/docs/implementation/l1-ecosystem-evaluation.md
