Merge pull request #50 from mpcp-protocol/fix/spec-coherence-review

fix: spec coherence review — Trust Bundle pipeline, vendor terminology, docs alignment

Author: naory

README.md

@@ -1,6 +1,6 @@
 # mpcp-reference — Implementation Roadmap
 
-TypeScript reference implementation and canonical protocol SDK for the [Machine Payment Control Protocol (MPCP)](https://mpcp-protocol.github.io/spec/).
+TypeScript reference implementation and canonical protocol SDK for the [Machine Payment Control Protocol (MPCP)](https://github.com/mpcp-protocol/mpcp-spec).
 
 Implements: protocol verification engine, artifact schemas, cryptographic signing, on-chain anchoring adapters, golden test vectors, and the full SDK consumed by `mpcp-policy-authority`, `mpcp-wallet-sdk`, and `mpcp-merchant-sdk`.
 
@@ -96,7 +96,7 @@ Implements: protocol verification engine, artifact schemas, cryptographic signin
 
 ## PR29 — Trust Bundle
 
-Implement the [Trust Bundle](https://mpcp-protocol.github.io/spec/protocol/trust-bundles/) specification as defined in the MPCP spec.
+Implement the Trust Bundle specification as defined in the MPCP spec (see `mpcp-spec/docs/protocol/trust-bundles.md`).
 
 Trust Bundles are pre-distributed signed documents that package trusted issuer public keys for MPCP verifiers operating without network access at verification time.
 

ROADMAP.md

@@ -33,16 +33,14 @@ PolicyGrant
 ↓
 SignedBudgetAuthorization (SBA)
 ↓
-SignedPaymentAuthorization (SPA)
+Trust Gateway
 ↓
-SettlementIntent
-↓
-Settlement
+XRPL Settlement
 
 Narration:
 "MPCP introduces a simple chain of authorization for machine payments."
 
-"Policies define payment rules. Budgets define session limits. Each payment is explicitly authorized and verifiable."
+"Policies define payment rules. Budgets define per-payment limits. The Trust Gateway verifies the chain and executes on XRPL, attaching a grant ID to every transaction for a permanent audit trail."
 
 ---
 
@@ -51,26 +49,26 @@ Visual sequence:
 1. Autonomous vehicle enters parking garage
 2. PolicyGrant appears
 3. SignedBudgetAuthorization (SBA) appears
-4. SignedPaymentAuthorization (SPA) triggers
-5. Settlement confirmation
+4. Trust Gateway verifies chain
+5. XRPL settlement confirmation with mpcp/grant-id memo
 
 Narration:
 "A vehicle receives a policy defining where and how it can pay."
 
-"A session budget allows spending within defined limits."
+"A budget authorization allows spending within defined limits for this payment."
 
-"Each payment request is cryptographically authorized."
+"The Trust Gateway verifies the authorization chain and submits the XRPL transaction."
 
-"The final settlement records the completed transaction."
+"The final settlement records the completed transaction on-chain."
 
 ---
 
-## Scene 5 — Ledger Anchor
+## Scene 5 — Policy Anchoring
 Visual:
-Intent hash flowing into a public ledger.
+Policy document hash flowing into a public ledger (Hedera HCS or XRPL NFT).
 
 Narration:
-"An optional intent hash can be anchored to a public ledger for audit and dispute resolution."
+"An optional anchorRef on the PolicyGrant links it to a public ledger record — providing tamper-evident policy history for audit and dispute resolution."
 
 ---
 
@@ -79,7 +77,7 @@ Visual:
 Verification chain replay.
 
 Narration:
-"Any dispute can be independently verified using the MPCP authorization chain."
+"Any dispute can be independently verified using the MPCP authorization chain and the on-chain XRPL audit trail."
 
 ---
 
@@ -112,10 +110,10 @@ Blocks stacking vertically
 
 Scene 4
 Autonomous parking example
-Vehicle enters → policy → budget → payment → settlement
+Vehicle enters → policy → budget → Trust Gateway → XRPL settlement
 
 Scene 5
-Intent hash anchored to ledger
+Policy document anchored to ledger (Hedera HCS / XRPL NFT)
 
 Scene 6
 Verification replay animation
@@ -134,13 +132,13 @@ Protocol comparison diagram
 "clean animated diagram showing protocols MCP A2A ACP communicating between agents and tools, arrows moving between nodes, modern developer diagram style"
 
 ## Prompt 3 — MPCP Authorization Chain
-"layered protocol diagram animation PolicyGrant SignedBudgetAuthorization SignedPaymentAuthorization SettlementIntent Settlement blocks stacking vertically with glowing arrows"
+"layered protocol diagram animation PolicyGrant SignedBudgetAuthorization Trust Gateway XRPL Settlement blocks stacking vertically with glowing arrows"
 
 ## Prompt 4 — Autonomous Parking Payment
 "autonomous car entering smart parking garage, digital authorization layers appearing around vehicle, futuristic payment confirmation animation"
 
-## Prompt 5 — Ledger Anchoring
-"cryptographic hash transforming into glowing data stream entering blockchain ledger block, modern protocol visualization"
+## Prompt 5 — Policy Anchoring
+"cryptographic policy document transforming into glowing data stream entering blockchain ledger block, modern protocol visualization"
 
 ## Prompt 6 — Dispute Verification
 "digital verification chain lighting up sequentially representing audit verification process"
@@ -160,9 +158,8 @@ Protocol blocks
 - Fleet Policy
 - PolicyGrant
 - SignedBudgetAuthorization (SBA)
-- SignedPaymentAuthorization (SPA)
-- SettlementIntent
-- Settlement
+- Trust Gateway
+- XRPL Settlement
 
 Animation style
 - minimal vector graphics

docs/animation/MPCP_ANIMATION_PACK.md

@@ -4,7 +4,7 @@ MPCP for EV charging: variable session length, multiple kWh, charging operator d
 
 ## Scenario
 
-EV connects to a charging station. The station requests payment authorization. The vehicle (or charging session manager) evaluates policy and budget, signs an SPA for the charging session, and the station verifies the MPCP chain before supplying power.
+EV connects to a charging station. The station requests payment authorization. The vehicle (or charging session manager) evaluates policy and budget, issues an SBA for the charging session, and the station verifies the MPCP chain before supplying power. The Trust Gateway executes the XRPL payment when the session ends.
 
 ## Profile
 
@@ -35,9 +35,9 @@ Similar to parking, but with higher `maxSessionSpend` and charging-specific dest
 
 1. Vehicle (or fleet) obtains PolicyGrant + SBA with charging destinations
 2. Charging station requests payment (amount may be estimated or updated during session)
-3. Vehicle signs SPA for the authorized amount
-4. Station verifies MPCP chain
-5. Power is supplied; settlement executes when session ends
+3. Vehicle issues SBA for the authorized amount
+4. Station verifies MPCP chain locally
+5. Power is supplied; Trust Gateway submits XRPL settlement when session ends
 
 ## Run Parking Example (Same Flow)
 

docs/examples/charging.md

@@ -4,7 +4,7 @@ Machine-to-machine payment loop for autonomous fleet vehicles.
 
 ## Scenario
 
-Robotaxi enters parking facility → parking meter sends payment request → vehicle evaluates fleet policy and session budget → vehicle signs SPA → payment executes on rail → parking system verifies MPCP chain → gate opens.
+Robotaxi enters parking facility → parking meter sends payment request → vehicle evaluates fleet policy and session budget → vehicle issues SBA → Trust Gateway verifies chain and executes XRPL payment → parking system verifies MPCP chain → gate opens.
 
 ## Architecture
 
@@ -15,18 +15,24 @@ Robotaxi enters parking facility → parking meter sends payment request → veh
 │                 │                            │  wallet)        │
 │ • request       │     MPCP artifacts         │                 │
 │ • verify        │ ◄────────────────────────  │ • policy check  │
-└────────┬────────┘     (SBA, SPA, intent)     │ • budget check  │
-         │                                      │ • sign SPA      │
+└────────┬────────┘     (PolicyGrant, SBA)     │ • budget check  │
+         │                                      │ • issue SBA     │
          │ verify                               └────────┬────────┘
          ▼                                                │
-┌─────────────────┐                                      │ execute
+┌─────────────────┐                                      │ SBA to gateway
 │    Verifier     │                                      ▼
 │ (local, no API) │                            ┌─────────────────┐
-└─────────────────┘                            │ Settlement Rail │
-         │                                      │ (mock / XRPL)   │
-         │ PASS                                 └─────────────────┘
-         ▼
-    Gate opens
+└─────────────────┘                            │  Trust Gateway  │
+         │                                      │ verify chain +  │
+         │ PASS                                 │ submit XRPL     │
+         ▼                                      └────────┬────────┘
+    Gate opens                                           │
+                                                         ▼
+                                               ┌─────────────────┐
+                                               │   XRPL Ledger   │
+                                               │ (mpcp/grant-id  │
+                                               │  memo attached) │
+                                               └─────────────────┘
 ```
 
 ## Components
@@ -35,8 +41,8 @@ Robotaxi enters parking facility → parking meter sends payment request → veh
 |-----------|------|
 | **Vehicle Agent** | MPCP SDK, wallet/signing keys, policy + budget enforcement |
 | **Parking Service** | Payment request endpoint, MPCP verification |
-| **Verifier** | Validates PolicyGrant → SBA → SPA → SettlementIntent chain |
-| **Settlement Rail** | Mock rail or XRPL |
+| **Verifier** | Validates PolicyGrant → SBA → Settlement chain |
+| **Trust Gateway** | Verifies SBA chain, submits XRPL payment with `mpcp/grant-id` memo |
 
 ## Run
 
@@ -73,7 +79,7 @@ Uses `examples/machine-commerce/fleet-policy.json` and `simulate.mjs`.
 
 - Autonomous payment authorization within fleet limits
 - Session budget enforcement
-- Deterministic SettlementIntent hashing
+- Trust Gateway handles XRPL execution with on-chain audit trail
 - Verification without centralized payment infrastructure
 
 ## See Also

docs/examples/fleet.md

@@ -4,13 +4,14 @@ Runnable example showing how MPCP acts as a **machine wallet guardrail layer**.
 
 ## Overview
 
-A machine wallet should not send funds unless payment requests satisfy:
+A machine wallet should not authorize payments unless payment requests satisfy:
 
 - **PolicyGrant** constraints (rails, assets, expiration)
 - **SignedBudgetAuthorization** session limits (max amount, destination allowlist)
-- **SignedPaymentAuthorization** approval rules (amount binding, intent hash)
 
-This example shows the integration pattern: check all three layers before signing.
+Once the SBA is issued, the **Trust Gateway** verifies the chain and executes the XRPL payment.
+
+This example shows the integration pattern: check both layers before issuing an SBA.
 
 This example focuses on wallet-side guardrail logic and uses a preloaded SBA-shaped authorization object rather than demonstrating full SBA issuance and signature verification.
 
@@ -29,14 +30,14 @@ node examples/machine-wallet-guardrails/wallet-integration.mjs
 
 ## What It Demonstrates
 
-1. **Allowed request** — $15 to rParking passes all checks; SignedPaymentAuthorization is created
+1. **Allowed request** — $15 to rParking passes all checks; SignedBudgetAuthorization is created
 2. **Wrong destination** — $5 to rAttacker is rejected (not in allowlist)
 3. **Would exceed budget** — $20 to rCharging when session already spent $15 is rejected
 
 ## Guardrail Check Flow
 
 ```
-Payment request → PolicyGrant validation → SignedBudgetAuthorization validation → SignedPaymentAuthorization creation (or reject)
+Payment request → PolicyGrant validation → SignedBudgetAuthorization validation → SBA issued (or reject) → Trust Gateway → XRPL
 ```
 
 See [Machine Wallet Guardrails](../implementation/machine-wallet-guardrails.md) for the full guide and threat model.

docs/examples/machine-wallet-guardrails.md

@@ -4,7 +4,7 @@ A full MPCP settlement flow for a parking payment scenario.
 
 ## Scenario
 
-Vehicle parks at a meter or garage gate. The parking system requests payment. The vehicle evaluates fleet policy and session budget, signs an SPA, and returns the authorization. The parking system verifies the MPCP chain locally and opens the gate.
+Vehicle parks at a meter or garage gate. The parking system requests payment. The vehicle evaluates fleet policy and session budget, issues an SBA, and presents it to the Trust Gateway. The Trust Gateway verifies the MPCP chain and executes the XRPL payment. The parking system verifies the chain locally and opens the gate.
 
 ## Artifacts
 
@@ -13,9 +13,7 @@ Vehicle parks at a meter or garage gate. The parking system requests payment. Th
 | policy-grant.json | Grant derived from policy constraints |
 | budget-auth.json | Unsigned budget authorization |
 | signed-budget-auth.json | Signed budget auth (SBA) |
-| spa.json | Signed payment authorization |
-| settlement-intent.json | Settlement intent |
-| settlement.json | Settlement result |
+| settlement.json | Settlement result (XRPL via Trust Gateway) |
 | settlement-bundle.json | Combined bundle for verification |
 
 ## Run
@@ -55,7 +53,7 @@ npm run example:guardrails
 
 ### Offline Payment
 
-Demonstrates offline machine payments: vehicle holds pre-authorized policy chain, completes payment when network is unavailable.
+Demonstrates offline machine payments: vehicle holds pre-authorized policy chain, authorizes payment when network is unavailable, Trust Gateway settles on XRPL when connectivity returns.
 
 ```bash
 npm run example:offline

docs/examples/parking.md

@@ -6,7 +6,7 @@ MPCP implementations can be verified for conformance to the protocol specificati
 
 | Level | Scope | Description |
 |-------|-------|-------------|
-| **Artifact** | Single artifact | Produces valid PolicyGrant, SBA, SPA, SettlementIntent per spec |
+| **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) |
@@ -18,8 +18,7 @@ The reference implementation includes golden vectors in `test/vectors/` for conf
 - `valid-settlement.json` — Full valid chain, must pass
 - `expired-grant.json` — Expired PolicyGrant, must fail
 - `budget-exceeded.json` — Amount exceeds budget, must fail
-- `intent-hash-mismatch.json` — Intent hash mismatch, must fail
-- `settlement-mismatch.json` — Settlement does not match SPA, must fail
+- `settlement-mismatch.json` — Settlement does not match SBA constraints, must fail
 
 Run the conformance tests:
 
@@ -36,7 +35,7 @@ Implementers should verify:
 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, SPA ⊆ SBA
+5. **Constraint propagation** — SBA ⊆ PolicyGrant
 
 ## See Also
 

docs/implementation/conformance.md

@@ -1,23 +1,28 @@
 # Dispute Verification
 
-Tooling to verify disputed settlements using the full MPCP chain plus optional ledger anchor.
+Tooling to verify disputed settlements using the full MPCP chain plus optional policy anchor.
 
 ## Purpose
 
 When a settlement is disputed, `verifyDisputedSettlement` validates:
 
-1. **MPCP chain** — PolicyGrant → SignedBudgetAuthorization → SignedPaymentAuthorization → SettlementIntent
-2. **Ledger anchor** (optional) — When provided, verifies the anchor is consistent with the settlement intent
+1. **MPCP chain** — PolicyGrant → SignedBudgetAuthorization → Settlement
+2. **Policy anchor** (optional) — When provided, verifies the `anchorRef` on the PolicyGrant is consistent with an on-chain record of the policy document
 
 ## Usage
 
 ```typescript
-import { verifyDisputedSettlement, mockAnchorIntentHash } from "mpcp-service";
-import { computeSettlementIntentHash } from "mpcp-service";
+import { verifyDisputedSettlement } from "mpcp-service";
 
 const result = verifyDisputedSettlement({
   context: settlementVerificationContext,
-  ledgerAnchor: await mockAnchorIntentHash(computeSettlementIntentHash(intent)),
+  // Optional: ledger anchor result from policy document anchoring
+  ledgerAnchor: {
+    anchorRef: grant.anchorRef,  // "hcs:0.0.12345:42" or "xrpl:nft:ABC123..."
+    rail: "hedera-hcs",
+    sequenceNumber: "42",
+    topicId: "0.0.12345",
+  },
 });
 
 if (result.verified) {
@@ -29,8 +34,8 @@ if (result.verified) {
 
 ## Inputs
 
-- **context** — Full `SettlementVerificationContext` (settlement, artifacts, policy grant, SBA, SPA, decision, settlement intent)
-- **ledgerAnchor** — Optional `AnchorResult` from intent anchoring
+- **context** — Full `SettlementVerificationContext` (settlement, policyGrant, signedBudgetAuthorization, decision)
+- **ledgerAnchor** — Optional `PolicyAnchorResult` from policy document anchoring
 
 ## Output
 
@@ -40,10 +45,23 @@ if (result.verified) {
 ## Failure Reasons
 
 - `settlement_verification_failed` — Standard MPCP chain verification failed
-- `anchor_provided_but_settlement_intent_missing` — Anchor provided but context has no settlement intent
-- `anchor_mismatch: ...` — Mock anchor txHash does not match intent hash
-- `anchor_rail_not_supported: ...` — Real ledger anchor verification not yet implemented
+- `anchor_provided_but_anchor_ref_missing` — Anchor provided but PolicyGrant has no `anchorRef`
+- `anchor_mismatch` — PolicyGrant `anchorRef` does not match the provided ledger anchor
+- `anchor_rail_not_supported` — Anchor rail not available for verification
 
-## Mock Anchor
+## Async Verification (Hedera HCS Mirror)
 
-Only mock anchors are supported. Real ledger verification (Hedera HCS, XRPL, EVM) is future work.
+Use `verifyDisputedSettlementAsync` to verify a Hedera HCS anchor by querying the mirror node:
+
+```typescript
+const result = await verifyDisputedSettlementAsync({
+  context: settlementVerificationContext,
+  ledgerAnchor: hcsAnchorResult,
+});
+```
+
+This fetches the anchored policy document from the Hedera mirror node and confirms it matches the PolicyGrant's `policyHash`.
+
+## XRPL Audit Trail
+
+Even without a policy document anchor, every XRPL payment submitted via the Trust Gateway includes an `mpcp/grant-id` memo. Disputes can reference this memo to confirm the on-chain payment was associated with the correct PolicyGrant.