You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For the full documentation site (overview, guides, examples, reference), see **[docs/](./docs/)**. When [GitHub Pages](https://docs.github.com/en/pages) is enabled, the site is published automatically from `main`.
15
-
16
-
**To enable the docs site:** go to **Settings → Pages** → Source: **Deploy from a branch** → Branch: **gh-pages** → Save. The workflow pushes the built site to `gh-pages` on each push to `main`.
14
+
For the full documentation site (overview, guides, examples, reference), see **[docs/](./docs/)**.
17
15
18
16
For the full protocol specification, see:
19
17
20
-
[Machine Payment Control Protocol Specification](./doc/protocol/mpcp.md)
18
+
[Machine Payment Control Protocol Specification](https://github.com/mpcp-protocol/mpcp-spec/blob/main/docs/protocol/mpcp.md)
21
19
22
20
This document defines the MPCP artifacts, verification rules, canonical hashing, replay protection, the authorization lifecycle, and the verification algorithm used by MPCP implementations.
23
21
24
-
For compatibility and versioning policy (what is stable, how 1.0/1.1/2.0 evolve), see [Compatibility and Versioning](./doc/architecture/COMPATIBILITY_AND_VERSIONING.md).
25
-
26
22
## Documentation Layout
27
23
28
-
This repository contains two documentation layers:
24
+
This repository contains one documentation layer:
25
+
26
+
-**docs/** — Developer documentation site (guides, examples, reference, API)
29
27
30
-
-**doc/** — Protocol specification and architecture documents (normative)
31
-
-**docs/** — Developer documentation site (guides, examples, reference)
28
+
The canonical protocol specification lives in the [mpcp-spec](https://github.com/mpcp-protocol/mpcp-spec) repository.
32
29
33
30
---
34
31
@@ -205,20 +202,20 @@ These are used to bind authorizations to a specific settlement intent.
205
202
206
203
## Intent Anchoring (optional)
207
204
208
-
Optional support for publishing intent hashes to distributed ledgers (public auditability, dispute protection). **Mock anchor** for development; **Hedera HCS** adapter for real anchoring. See [Intent Anchoring](./doc/architecture/INTENT_ANCHORING.md).
205
+
Optional support for publishing intent hashes to distributed ledgers (public auditability, dispute protection). **Mock anchor** for development; **Hedera HCS** adapter for real anchoring. See [Intent Anchoring](./docs/implementation/intent-anchoring.md).
209
206
210
207
## Dispute Verification (optional)
211
208
212
-
`verifyDisputedSettlement` validates disputed settlements using the full MPCP chain plus optional ledger anchor. See [Dispute Verification](./doc/architecture/DISPUTE_VERIFICATION.md).
209
+
`verifyDisputedSettlement` validates disputed settlements using the full MPCP chain plus optional ledger anchor. See [Dispute Verification](./docs/implementation/dispute-verification.md).
213
210
214
211
## Reference Service API (optional)
215
212
216
-
Backend-friendly facade: `issueBudget`, `verifySettlementService`, `verifyDispute` / `verifyDisputeAsync`, `anchorIntent`. See [REFERENCE_SERVICE_API](./doc/architecture/REFERENCE_SERVICE_API.md). Import from `mpcp-service/service`.
213
+
Backend-friendly facade: `issueBudget`, `verifySettlementService`, `verifyDispute` / `verifyDisputeAsync`, `anchorIntent`. See [Reference Service API](./docs/reference/service-api.md). Import from `mpcp-service/service`.
217
214
218
215
## Fleet Operator Tooling (optional)
219
216
220
217
-**Settlement verification logs** — `mpcp verify <file> --append-log audit.jsonl` appends verification results to a JSONL audit trail
221
-
-**Fleet policy summary** — `mpcp policy-summary <policy.json>` prints policy constraints. Use `--profile <name>` for lightweight reference-profile validation [(parking, charging, fleet-offline, hosted-rail)](./doc/architecture/REFERENCE_PROFILES.md). See [Fleet Operator Tooling](./doc/architecture/FLEET_OPERATOR_TOOLING.md).
218
+
-**Fleet policy summary** — `mpcp policy-summary <policy.json>` prints policy constraints. Use `--profile <name>` for lightweight reference-profile validation [(parking, charging, fleet-offline, hosted-rail)](./docs/implementation/reference-profiles.md). See [Fleet Operator Tooling](./docs/implementation/fleet-operator-tooling.md).
Copy file name to clipboardExpand all lines: docs/implementation/machine-wallet-guardrails.md
+35Lines changed: 35 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,6 +35,41 @@ MPCP provides three layers of enforcement before a machine can pay:
35
35
-**Intent hash** — SPA binds to a canonical SettlementIntent
36
36
-**Tamper resistance** — SettlementIntent and final settlement must match the signed authorization
37
37
38
+
## Vehicle Wallet Roles
39
+
40
+
In an autonomous deployment, the vehicle wallet plays **two distinct roles** in the MPCP authorization pipeline.
41
+
42
+
### Session Authority
43
+
44
+
The wallet creates and signs the **SignedBudgetAuthorization (SBA)** before the session begins. This establishes the session-level spending envelope:
45
+
46
+
- Sets `maxAmountMinor` — the total spend ceiling for the session
47
+
- Sets `destinationAllowlist` — the permitted payees
48
+
- Binds to the PolicyGrant via `grantId`
49
+
50
+
The SBA is signed with the wallet's SBA key (`MPCP_SBA_SIGNING_PRIVATE_KEY_PEM`). Verifiers check this signature to confirm the budget was set by a trusted session authority.
51
+
52
+
### Payment Decision Service
53
+
54
+
For each payment request within the session, the wallet evaluates the request against the loaded policy chain and, if approved, creates and signs a **SignedPaymentAuthorization (SPA)**:
55
+
56
+
- Assigns a unique `decisionId`
57
+
- Commits to the specific amount, destination, and asset
58
+
- Computes and binds an `intentHash` to a canonical SettlementIntent
59
+
- Signs with the wallet's SPA key (`MPCP_SPA_SIGNING_PRIVATE_KEY_PEM`)
60
+
61
+
This decision is made **locally** — no central approval API is contacted. The SPA is a cryptographic proof that the wallet approved this specific payment within the authorized budget.
62
+
63
+
### Why Two Roles?
64
+
65
+
Separating session authority from payment decisions allows fleet operators to:
66
+
67
+
- Pre-authorize a spending envelope (SBA) before the vehicle enters service
68
+
- Let the vehicle make individual payment decisions (SPA) locally within that envelope
69
+
- Give verifiers a complete, self-contained authorization chain to validate
70
+
71
+
---
72
+
38
73
## Wallet Integration
39
74
40
75
A machine wallet integrates MPCP by performing checks *before* signing an SPA.
Validation checks: `allowedRails` in the policy must be a subset of the profile’s allowed rails; if the policy declares `_profile`, it must match the profile name.
Copy file name to clipboardExpand all lines: docs/implementation/verifier.md
+43Lines changed: 43 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,6 +40,49 @@ if (result.valid) {
40
40
41
41
The `context` includes policyGrant, signedBudgetAuthorization, signedPaymentAuthorization, settlement, paymentPolicyDecision, decisionId, and optional settlementIntent.
42
42
43
+
## Key Resolution
44
+
45
+
MPCP signatures include an `issuerKeyId` field that identifies which public key to use for verification. Verifiers resolve the key using one of two mechanisms.
46
+
47
+
### HTTPS Well-Known (Baseline)
48
+
49
+
The issuer publishes their public keys at:
50
+
51
+
```
52
+
https://{issuerDomain}/.well-known/mpcp-keys.json
53
+
```
54
+
55
+
Format:
56
+
57
+
```json
58
+
{
59
+
"keys": [
60
+
{
61
+
"keyId": "mpcp-sba-signing-key-1",
62
+
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
63
+
"use": "sba"
64
+
},
65
+
{
66
+
"keyId": "mpcp-spa-signing-key-1",
67
+
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
68
+
"use": "spa"
69
+
}
70
+
]
71
+
}
72
+
```
73
+
74
+
The `issuerKeyId` in the signed envelope identifies which entry to use.
75
+
76
+
### DID Document (Optional)
77
+
78
+
For issuers using decentralized identifiers, keys may be resolved via a DID document. The `issuerKeyId` corresponds to a `verificationMethod` in the DID document. DID resolution is an optional enhancement over the HTTPS well-known baseline.
79
+
80
+
### Inline Keys (Self-Contained Bundles)
81
+
82
+
Settlement bundles for development and conformance testing may include `sbaPublicKeyPem` and `spaPublicKeyPem` directly. This avoids external resolution and makes bundles self-contained for `mpcp verify`.
83
+
84
+
---
85
+
43
86
## Dispute Verification
44
87
45
88
When a settlement is disputed, `verifyDisputedSettlement` runs full chain verification plus optional ledger anchor verification. If the intent was anchored (e.g., to Hedera HCS), the anchor can be checked against the expected intentHash.
0 commit comments