@algovoi/substrate 0.3.0 → 0.4.0

package/README.md

@@ -66,8 +66,11 @@ verifyAuditChain([row0, row1]);
 
 ## Substrate discipline
 
-This package enforces the AlgoVoi-discipline rules formalised in PR #2436
-(`x402-foundation/x402`, three-voice coalition co-signed):
+This package enforces the AlgoVoi-authored substrate-discipline rules
+formalised in [IETF Internet-Draft `draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/)
+(Independent Submission, Informational; sole AlgoVoi authorship) and
+proposed for inclusion in `x402-foundation/x402` via [PR #2453](https://github.com/x402-foundation/x402/pull/2453)
+(replaces closed [#2436](https://github.com/x402-foundation/x402/pull/2436)):
 
 - **Rule 1.** `timestamp_ms` is an epoch-millisecond integer. Floats, ISO
   8601 strings, and negative values are rejected at the source-side.
@@ -115,10 +118,21 @@ The reference exhibit for this substrate is AlgoVoi's
 
 ## Spec references
 
-- [PR #2436](https://github.com/x402-foundation/x402/pull/2436) -- canonicalisation discipline
-- [PR #2440](https://github.com/x402-foundation/x402/pull/2440) -- composite trust-query
-- [PR #2434](https://github.com/x402-foundation/x402/pull/2434) -- compliance-receipt-fixture
-- [draft-vauban-x402-stark-receipts](https://datatracker.ietf.org/doc/draft-vauban-x402-stark-receipts/)
+- [draft-hopley-x402-canonicalisation-jcs-v1](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/) -- IETF I-D (Independent Submission, Informational, sole AlgoVoi authorship). Specifies `urn:x402:canonicalisation:jcs-rfc8785-v1`.
+- [docs.algovoi.co.uk/canonicalisation-substrate](https://docs.algovoi.co.uk/canonicalisation-substrate) -- v1 discipline reference page.
+- [docs.algovoi.co.uk/canonicalisation-substrate-v2](https://docs.algovoi.co.uk/canonicalisation-substrate-v2) -- v2 (PQC-aware) additive successor.
+- [PR #2453](https://github.com/x402-foundation/x402/pull/2453) -- live upstream spec PR for the canonicalisation discipline (sole AlgoVoi authorship; replaces closed #2436).
+- [draft-vauban-x402-stark-receipts](https://datatracker.ietf.org/doc/draft-vauban-x402-stark-receipts/) -- third-party adopter-authored receipt format that anchors to the AlgoVoi canonicalisation discipline.
+
+## Conformance to the canonicalisation discipline
+
+This package emits receipts pinned to `canon_version: jcs-rfc8785-v1` in-band. Downstream verifiers (`algovoi-audit-verifier` and any conformant third-party verifier) read the pin to select the canonicalisation rule applied at emission.
+
+The pin is the load-bearing primitive for the [Substrate Adopters Registry](https://docs.algovoi.co.uk/adopters): adopters anchoring to this discipline pin the same `canon_version` value in their own publicly-citable artefacts. AlgoVoi maintains the registry as a neutral observer; this package is recorded there as the AlgoVoi reference implementation.
+
+## Substrate adopters
+
+AlgoVoi is recorded in the [Substrate Adopters Registry](https://docs.algovoi.co.uk/adopters) as the substrate author (v1 and v2). Parties anchoring their own services or specifications to `canon_version: jcs-rfc8785-v1` are recorded in the registry via the [submission process](https://docs.algovoi.co.uk/adopters#how-to-submit-an-adoption-entry). AlgoVoi validates submissions against the artefact's canonical bytes and adds qualifying entries.
 
 ## Licence
 

package/dist/index.d.ts

@@ -22,4 +22,5 @@ export { CompositeTrustQueryError, type EmitterRow, compositeTrustQueryHash, } f
 export { SCREEN_RESULTS, type ScreenResult, ComplianceReceiptError, type ComplianceReceipt, type BuildComplianceReceiptInput, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, type AuditChainRow, appendToChain, verifyAuditChain, } from './audit-chain.js';
 export { TransactionalError, type TransitionPreimage, type TransitionInput, type TransitionRecord, type TransactionalChain, type TransactionalChainInput, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
+export { SettlementBindingError, type SettlementBindingPreimage, settlementBindingPreimage, settlementActionBinding, } from './settlement-binding.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -22,4 +22,5 @@ export { CompositeTrustQueryError, compositeTrustQueryHash, } from './composite-
 export { SCREEN_RESULTS, ComplianceReceiptError, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, appendToChain, verifyAuditChain, } from './audit-chain.js';
 export { TransactionalError, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
+export { SettlementBindingError, settlementBindingPreimage, settlementActionBinding, } from './settlement-binding.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAMlB,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAMlB,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,sBAAsB,EAEtB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/settlement-binding.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+export declare class SettlementBindingError extends Error {
+    constructor(message: string);
+}
+export interface SettlementBindingPreimage {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export declare function settlementBindingPreimage(input: {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}): SettlementBindingPreimage;
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export declare function settlementActionBinding(input: {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}): string;
+//# sourceMappingURL=settlement-binding.d.ts.map

package/dist/settlement-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-binding.d.ts","sourceRoot":"","sources":["../src/settlement-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AA8BD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,yBAAyB,CAO5B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,MAAM,CAGT"}

package/dist/settlement-binding.js

@@ -0,0 +1,79 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+import { sha256Jcs } from './canonicalize.js';
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const SHA256_REF_RE = /^sha256:[0-9a-f]{64}$/;
+export class SettlementBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SettlementBindingError';
+    }
+}
+function requireHex64(field, value) {
+    if (typeof value !== 'string') {
+        throw new SettlementBindingError(`${field} must be string, got ${typeof value}`);
+    }
+    if (!HEX64_RE.test(value)) {
+        throw new SettlementBindingError(`${field} must be a lowercase 64-character SHA-256 hex string`);
+    }
+    return value;
+}
+function requireChainRef(value) {
+    if (typeof value !== 'string') {
+        throw new SettlementBindingError(`retention_chain_ref must be string, got ${typeof value}`);
+    }
+    if (!SHA256_REF_RE.test(value)) {
+        throw new SettlementBindingError("retention_chain_ref must be of the form 'sha256:<lowercase 64-char hex>'");
+    }
+    return value;
+}
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export function settlementBindingPreimage(input) {
+    return {
+        action_ref: requireHex64('action_ref', input.action_ref),
+        transition_hash: requireHex64('transition_hash', input.transition_hash),
+        settlement_ref: requireHex64('settlement_ref', input.settlement_ref),
+        retention_chain_ref: requireChainRef(input.retention_chain_ref),
+    };
+}
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export function settlementActionBinding(input) {
+    const obj = settlementBindingPreimage(input);
+    return `sha256:${sha256Jcs(obj)}`;
+}
+//# sourceMappingURL=settlement-binding.js.map

package/dist/settlement-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-binding.js","sourceRoot":"","sources":["../src/settlement-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAClC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAE9C,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AASD,SAAS,YAAY,CAAC,KAAa,EAAE,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,wBAAwB,OAAO,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,sDAAsD,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,sBAAsB,CAC9B,2CAA2C,OAAO,KAAK,EAAE,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,sBAAsB,CAC9B,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAKzC;IACC,OAAO;QACL,UAAU,EAAE,YAAY,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC;QACxD,eAAe,EAAE,YAAY,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC;QACvE,cAAc,EAAE,YAAY,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC;QACpE,mBAAmB,EAAE,eAAe,CAAC,KAAK,CAAC,mBAAmB,CAAC;KAChE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAKvC;IACC,MAAM,GAAG,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@algovoi/substrate",
-  "version": "0.3.0",
-  "description": "AlgoVoi agentic-payments substrate -- JCS canonicalisation, action_ref, composite trust-query, compliance receipts, audit chain",
+  "version": "0.4.0",
+  "description": "AlgoVoi agentic-payments substrate -- JCS canonicalisation, action_ref, composite trust-query, compliance receipts, audit chain, settlement-action binding",
   "keywords": [
     "x402",
     "ap2",

package/src/index.ts

@@ -66,3 +66,10 @@ export {
   transitionHash,
   buildTransactionalActionChain,
 } from './transactional.js';
+
+export {
+  SettlementBindingError,
+  type SettlementBindingPreimage,
+  settlementBindingPreimage,
+  settlementActionBinding,
+} from './settlement-binding.js';

package/src/settlement-binding.ts

@@ -0,0 +1,110 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+
+import { sha256Jcs } from './canonicalize.js';
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const SHA256_REF_RE = /^sha256:[0-9a-f]{64}$/;
+
+export class SettlementBindingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SettlementBindingError';
+  }
+}
+
+export interface SettlementBindingPreimage {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}
+
+function requireHex64(field: string, value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new SettlementBindingError(
+      `${field} must be string, got ${typeof value}`,
+    );
+  }
+  if (!HEX64_RE.test(value)) {
+    throw new SettlementBindingError(
+      `${field} must be a lowercase 64-character SHA-256 hex string`,
+    );
+  }
+  return value;
+}
+
+function requireChainRef(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new SettlementBindingError(
+      `retention_chain_ref must be string, got ${typeof value}`,
+    );
+  }
+  if (!SHA256_REF_RE.test(value)) {
+    throw new SettlementBindingError(
+      "retention_chain_ref must be of the form 'sha256:<lowercase 64-char hex>'",
+    );
+  }
+  return value;
+}
+
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export function settlementBindingPreimage(input: {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}): SettlementBindingPreimage {
+  return {
+    action_ref: requireHex64('action_ref', input.action_ref),
+    transition_hash: requireHex64('transition_hash', input.transition_hash),
+    settlement_ref: requireHex64('settlement_ref', input.settlement_ref),
+    retention_chain_ref: requireChainRef(input.retention_chain_ref),
+  };
+}
+
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export function settlementActionBinding(input: {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}): string {
+  const obj = settlementBindingPreimage(input);
+  return `sha256:${sha256Jcs(obj)}`;
+}