@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,6 +1,9 @@
 export { METAL_NETWORKS, USDZ, formatUsdz, metalNetwork, usdzBaseUnits, accountFactoryFor, rpcUrlFor, } from "./networks.js";
 export { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, registerMetalNetworks, } from "./client.js";
 export { metalUsd, registerMetalScheme, sellerToken, } from "./server.js";
-export * from "./clearing.js";
+export * from "./clearing-codec.js";
+export { clearingAbi } from "./clearing-abi.js";
 export * from "./clearing-client.js";
+export * from "./clearing-x402.js";
 export * from "./clearing-server.js";
+export * from "./clearing-custody.js";

package/dist/mandates/account.d.ts

@@ -70,6 +70,9 @@ export declare const metalAccountAbi: readonly [{
     }, {
         readonly type: "uint256";
         readonly name: "nonce";
+    }, {
+        readonly type: "uint64";
+        readonly name: "validUntil";
     }, {
         readonly type: "bytes";
         readonly name: "signature";
@@ -84,7 +87,9 @@ export declare function assertMetalAccount(client: PublicClient, account: Addres
 /** The gas an executeSigned adds to the call it carries, by the quorum signature's signers. */
 export declare function quorumGas(signature: Hex): bigint;
 /** Self-calls approved by the account's existing ERC-7913 quorum, in one batch
- * that runs whole or not at all. The signing callback may collect mixed keys,
- * weights and passkeys; it returns the normal abi.encode(bytes[] signers,
- * bytes[] signatures) account signature. */
-export declare function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall>;
+ * that runs whole or not at all. The account refuses the signed batch once the
+ * chain's block timestamp passes `validUntil` (unix seconds): pick a deadline
+ * just long enough to collect the signatures and submit. The signing callback
+ * may collect mixed keys, weights and passkeys; it returns the normal
+ * abi.encode(bytes[] signers, bytes[] signatures) account signature. */
+export declare function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], validUntil: bigint, signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall>;

package/dist/mandates/account.js

@@ -6,7 +6,7 @@ export const metalAccountFactoryAbi = parseAbi([
 ]);
 export const metalAccountAbi = parseAbi([
     "function nonces(address owner, uint192 key) view returns (uint256)",
-    "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, bytes signature)",
+    "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, uint64 validUntil, bytes signature)",
 ]);
 export const ACCOUNT_BATCH_MODE = "0x0100000000000000000000000000000000000000000000000000000000000000";
 /** Exact immutable ERC-1167 clone emitted by MetalAccountFactory. */
@@ -56,10 +56,12 @@ export function quorumGas(signature) {
     return gas;
 }
 /** Self-calls approved by the account's existing ERC-7913 quorum, in one batch
- * that runs whole or not at all. The signing callback may collect mixed keys,
- * weights and passkeys; it returns the normal abi.encode(bytes[] signers,
- * bytes[] signatures) account signature. */
-export async function authorizeMandateCall(client, factory, call, signQuorum) {
+ * that runs whole or not at all. The account refuses the signed batch once the
+ * chain's block timestamp passes `validUntil` (unix seconds): pick a deadline
+ * just long enough to collect the signatures and submit. The signing callback
+ * may collect mixed keys, weights and passkeys; it returns the normal
+ * abi.encode(bytes[] signers, bytes[] signatures) account signature. */
+export async function authorizeMandateCall(client, factory, call, validUntil, signQuorum) {
     const chainId = client.chain?.id;
     if (chainId === undefined)
         throw new Error("the RPC client names no chain");
@@ -71,9 +73,11 @@ export async function authorizeMandateCall(client, factory, call, signQuorum) {
     if (calls.some((c) => !isAddressEqual(c.to, account)))
         throw new Error("every call in one batch goes to the same account");
     await assertMetalAccount(client, account, factory);
-    // A fresh 192-bit nonce lane per call: two administration calls in flight,
-    // or one beside the owner's own operations on lane 0, never claim one nonce.
-    const lane = hexToBigInt(bytesToHex(crypto.getRandomValues(new Uint8Array(24))));
+    // A fresh nonce lane per call: two administration calls in flight, or one
+    // beside the owner's own operations on lane 0, never claim one nonce. A
+    // quorum's lane keeps the key's top bit clear; set, it is a lane for
+    // signatures below the threshold, which the account refuses for the quorum.
+    const lane = hexToBigInt(bytesToHex(crypto.getRandomValues(new Uint8Array(24)))) >> 1n;
     const sequence = await client.readContract({ address: account, abi: metalAccountAbi, functionName: "nonces", args: [account, lane] });
     const nonce = (lane << 64n) | sequence;
     const executionData = encodeAbiParameters(parseAbiParameters("(address target, uint256 value, bytes callData)[]"), [calls.map((c) => ({ target: account, value: 0n, callData: c.data }))]);
@@ -81,11 +85,11 @@ export async function authorizeMandateCall(client, factory, call, signQuorum) {
     // it could have the quorum sign a batch of its own choosing.
     const digest = hashTypedData({
         domain: { name: "MetalAccount", version: "1", chainId, verifyingContract: account },
-        types: { Execute: [{ name: "mode", type: "bytes32" }, { name: "executionData", type: "bytes" }, { name: "nonce", type: "uint256" }] },
+        types: { Execute: [{ name: "mode", type: "bytes32" }, { name: "executionData", type: "bytes" }, { name: "nonce", type: "uint256" }, { name: "validUntil", type: "uint64" }] },
         primaryType: "Execute",
-        message: { mode: ACCOUNT_BATCH_MODE, executionData, nonce },
+        message: { mode: ACCOUNT_BATCH_MODE, executionData, nonce, validUntil },
     });
     const signature = await signQuorum(digest);
     const gas = calls.reduce((sum, c) => sum + c.gas, 0n) + quorumGas(signature);
-    return { ...first, gas, data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, signature] }) };
+    return { ...first, gas, data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, validUntil, signature] }) };
 }

package/dist/mandates/binding.d.ts

@@ -2,14 +2,6 @@ import { type Address, type Hex } from "viem";
 /** Domain tag for the payment-only ERC-1271 path on MetalAccount. */
 export declare const MANDATE_SIGNATURE_TAG: Hex;
 export declare const mandateBindingAbi: readonly [{
-    readonly name: "mip20TransferHandler";
-    readonly type: "function";
-    readonly stateMutability: "pure";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly type: "bytes4";
-    }];
-}, {
     readonly name: "mandateReference";
     readonly type: "function";
     readonly stateMutability: "pure";
@@ -402,7 +394,10 @@ export declare const mandateBindingAbi: readonly [{
         }];
         readonly name: "l";
     }];
-    readonly outputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+        readonly name: "paid";
+    }];
 }, {
     readonly name: "MandateBound";
     readonly type: "event";
@@ -503,9 +498,6 @@ export declare const mandateBindingAbi: readonly [{
     }, {
         readonly type: "uint256";
         readonly name: "occurrences";
-    }, {
-        readonly type: "bool";
-        readonly name: "direct";
     }];
 }, {
     readonly name: "MandateRefused";
@@ -619,21 +611,6 @@ export declare const mandateBindingAbi: readonly [{
     readonly name: "RefusalLimitReached";
     readonly type: "error";
     readonly inputs: readonly [];
-}, {
-    readonly name: "NotApproved";
-    readonly type: "error";
-    readonly inputs: readonly [];
-}, {
-    readonly name: "MandateBreach";
-    readonly type: "error";
-    readonly inputs: readonly [{
-        readonly type: "uint8";
-        readonly name: "reason";
-    }];
-}, {
-    readonly name: "UnauthorizedHookCaller";
-    readonly type: "error";
-    readonly inputs: readonly [];
 }];
 /** `MandateTypes.Reason` in declaration order, which is the order Mandate Binding checks them in; `None` is a pass. */
 export declare const REASONS: readonly ["None", "NoMandate", "Revoked", "Expired", "BadSignature", "NonceUsed", "OutsideWindow", "PayeeNotAllowed", "OverPerPaymentCap", "OverBudget", "OutsideRecurrence", "OverOccurrences"];

package/dist/mandates/binding.js

@@ -1,4 +1,4 @@
-// MetalAccount mandate ABI, typed agent keys, references, self-calls and direct pulls.
+// MetalAccount mandate ABI, typed agent keys, references, self-calls and pulls.
 import { concat, encodeFunctionData, encodePacked, keccak256, parseAbi, size, slice } from "viem";
 /** Domain tag for the payment-only ERC-1271 path on MetalAccount. */
 export const MANDATE_SIGNATURE_TAG = "0x4d4e4454";
@@ -10,7 +10,6 @@ export const mandateBindingAbi = parseAbi([
     "struct Terms { string kid; string instrument; string currency; uint256 unitsPerMinor; Payee[] payees; bytes32 openSdHash; }",
     "struct PayeeTerms { bytes32 sdHash; string object; }",
     "struct MandateState { address principal; bool revoked; bytes32 agentX; bytes32 agentY; string kid; bytes32 openSdHash; uint64 boundBlock; uint64 occurrences; uint128 spent; }",
-    "function mip20TransferHandler() pure returns (bytes4)",
     "function mandateReference(address principal, bytes agentKey, bytes32 hashC) pure returns (bytes32)",
     "function mandates(bytes32 ref) view returns (MandateState)",
     "function payee(bytes32 ref, address account) view returns (PayeeTerms)",
@@ -21,9 +20,9 @@ export const mandateBindingAbi = parseAbi([
     "function revoke(bytes32 ref)",
     "function isValidSignature(bytes32 hash, bytes blob) view returns (bytes4)",
     "function check(Pull p, L3a l) view returns (uint8)",
-    "function pull(Pull p, L3a l)",
+    "function pull(Pull p, L3a l) returns (bool paid)",
     "event MandateBound(bytes32 indexed ref, bytes32 hashC, bytes32 issuerKey, bytes agentKey, Constraints constraints, Terms terms)",
-    "event MandatePayment(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint256 spent, uint256 occurrences, bool direct)",
+    "event MandatePayment(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint256 spent, uint256 occurrences)",
     "event MandateRefused(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint8 reason)",
     "event MandateRevoked(bytes32 indexed ref)",
     "event MandateReplaced(bytes32 indexed predecessor, bytes32 indexed successor)",
@@ -44,9 +43,6 @@ export const mandateBindingAbi = parseAbi([
     "error NonceAlreadyUsed()",
     "error NotYetValid()",
     "error RefusalLimitReached()",
-    "error NotApproved()",
-    "error MandateBreach(uint8 reason)",
-    "error UnauthorizedHookCaller()",
 ]);
 /** `MandateTypes.Reason` in declaration order, which is the order Mandate Binding checks them in; `None` is a pass. */
 export const REASONS = [
@@ -74,13 +70,13 @@ export const REFUSALS = {
     NoMandate: { reason: "mandate_not_bound", meaning: "no such mandate is bound on the account" },
     Revoked: { reason: "mandate_revoked", meaning: "the mandate is revoked, or replaced: the agent pays under the credential that replaced it" },
     Expired: { reason: "mandate_expired", meaning: "the mandate has expired" },
-    BadSignature: { reason: "mandate_bad_signature", meaning: "the payment is not signed by the mandate's agent key" },
+    BadSignature: { reason: "mandate_bad_signature", meaning: "the payment is not signed by the mandate key" },
     NonceUsed: { reason: "mandate_nonce_used", meaning: "this payment was already made or refused" },
     OutsideWindow: { reason: "mandate_outside_window", meaning: "the payment's validity window is not open" },
     PayeeNotAllowed: { reason: "mandate_payee_not_listed", meaning: "the payee is not one the mandate allows" },
     OverPerPaymentCap: { reason: "mandate_cap_exceeded", meaning: "the amount is above the mandate's per-payment cap" },
     OverBudget: { reason: "mandate_budget_spent", meaning: "the amount would take the mandate past its budget" },
-    OutsideRecurrence: { reason: "mandate_outside_recurrence", meaning: "today is outside the mandate's dates" },
+    OutsideRecurrence: { reason: "mandate_outside_recurrence", meaning: "the mandate has not started yet, or its dates have ended" },
     OverOccurrences: { reason: "mandate_occurrences_used", meaning: "the mandate's payment count is used up" },
 };
 /** `mandate_cap_exceeded (the amount is above the mandate's per-payment cap)`: a refusal as a person reads it. */

package/dist/mandates/checkout.js

@@ -61,7 +61,7 @@ export function readCheckoutJwt(jwt) {
     const [h, p, sig] = segments;
     const header = JSON.parse(Buffer.from(fromB64url(h)).toString("utf8"));
     if (header.alg !== "ES256" || header.typ !== "JWT" || typeof header.kid !== "string")
-        throw new Error("a checkout JWT is an ES256 JWT naming the agent key");
+        throw new Error("a checkout JWT is an ES256 JWT naming the mandate key");
     const offer = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8"));
     if (offer === null || typeof offer !== "object" || Array.isArray(offer))
         throw new Error("a checkout JWT's payload is an object");
@@ -126,7 +126,7 @@ export function readL3b(serialized) {
     const payload = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8"));
     const [, final] = JSON.parse(Buffer.from(fromB64url(checkoutDisclosure)).toString("utf8"));
     if (typeof header.kid !== "string")
-        throw new Error("an L3b names the agent key");
+        throw new Error("an L3b names the mandate key");
     if (final.vct !== CHECKOUT_VCT || typeof final.checkout_jwt !== "string")
         throw new Error(`the disclosure is not a ${CHECKOUT_VCT} with a checkout JWT`);
     const signature = fromB64url(sig);
@@ -183,9 +183,9 @@ function checkCheckoutMandate(serialized, expect) {
     if (l3b.typ !== "kb-sd-jwt")
         problems.push("the checkout mandate's typ is not kb-sd-jwt");
     if (l3b.kid !== expect.kid)
-        problems.push("the checkout mandate names another agent key");
+        problems.push("the checkout mandate names another mandate key");
     if (!verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(l3b.signingInput, "ascii")), l3b.r, l3b.s))
-        problems.push("the checkout mandate is not signed by the mandate's agent key");
+        problems.push("the checkout mandate is not signed by the mandate key");
     if (typeof l3b.aud !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(l3b.aud) || !isAddressEqual(l3b.aud, expect.payee))
         problems.push("the checkout mandate is for another payee");
     const now = expect.now ?? Math.floor(Date.now() / 1000);
@@ -215,7 +215,7 @@ function checkCheckoutMandate(serialized, expect) {
     let lineItemId = expect.lineItemId;
     if (jwt !== undefined) {
         if (jwt.kid !== expect.kid || !verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(jwt.signingInput, "ascii")), jwt.r, jwt.s))
-            problems.push("the checkout JWT is not signed by the mandate's agent key");
+            problems.push("the checkout JWT is not signed by the mandate key");
         if (expect.offer !== undefined && jwt.signingInput !== buildCheckoutJwt(expect.kid, expect.offer).signingInput)
             problems.push("the checkout JWT is not over the offer the payee served");
         const offer = expect.offer ?? jwt.offer;

package/dist/mandates/client.js

@@ -5,9 +5,10 @@
 // `TransferWithAuthorization` whose `from` is the principal's account, whose
 // nonce is `bytes12(mandate reference) ‖ bytes20(SHA-256(L3a signing input))`,
 // whose window is the L3a's `iat` and `exp`, and whose signature is
-// `abi.encode(Pull, L3a fields)`, which the account's Mandate Binding accepts
-// or refuses through ERC-1271. Sellers and facilitators see an ordinary
-// `exact` payment; a seller that asks for the agent's signed order gets it in
+// `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull` on the
+// principal's account. Sellers see an ordinary `exact` payment; Metal's
+// facilitator submits it as that `pull`, where Mandate Binding accepts or
+// refuses it. A seller that asks for the agent's signed order gets it in
 // the payload's `extensions`, and the per-payment mandate names its hash.
 //
 // `@x402/evm`'s `exact` client draws its own nonce and signs EIP-712 as

package/dist/mandates/l3a.d.ts

@@ -64,9 +64,9 @@ export declare function signL3a(args: {
     iss: string;
     signDigest: SignDigest;
 }): Promise<SignedL3a>;
-/** The relayed authorisation's signature: `MNDT || abi.encode(Pull, L3a fields)`. */
+/** The x402 payload's signature: `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull`. */
 export declare function encodeMandateBlob(pull: Pull, fields: L3aFields): Hex;
-/** The Pull and L3a fields a relayed authorisation's signature carries, as Mandate Binding's `check` and `pull` take them. */
+/** The Pull and L3a fields an x402 payload's signature carries, as Mandate Binding's `check` and `pull` take them. */
 export declare function decodeMandateBlob(blob: Hex): {
     pull: Pull;
     fields: L3aFields;

package/dist/mandates/l3a.js

@@ -4,8 +4,9 @@
 // verbatim), with `aud` the chain as `eip155:<chainId>`, `iat`/`exp` the
 // ERC-3009 window, and `transaction_id` the SHA-256 of the RFC 8785 form of
 // the seller's x402 payment requirements. The ERC-3009 nonce is
-// `bytes12(mandate reference) ‖ bytes20(SHA-256(signing input))`; the relayed
-// signature is `MNDT || abi.encode(Pull, L3a fields)`.
+// `bytes12(mandate reference) ‖ bytes20(SHA-256(signing input))`; the x402
+// payload's signature is `MNDT || abi.encode(Pull, L3a fields)`, which the
+// facilitator decodes into `pull`'s arguments.
 import { p256 } from "@noble/curves/nist";
 import { bytesToHex, concat, decodeAbiParameters, encodeAbiParameters, getAbiItem, hexToBigInt, hexToBytes, isAddressEqual, numberToHex, size, slice, zeroAddress, } from "viem";
 import { mandateBindingAbi, referencePrefix } from "./binding.js";
@@ -145,11 +146,11 @@ export async function signL3a(args) {
     return { pull, fields: { ...unsigned, r, s }, serialized: serializeL3a(l3a, r, s), digest: l3a.digest };
 }
 const pullInputs = getAbiItem({ abi: mandateBindingAbi, name: "pull" }).inputs;
-/** The relayed authorisation's signature: `MNDT || abi.encode(Pull, L3a fields)`. */
+/** The x402 payload's signature: `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull`. */
 export function encodeMandateBlob(pull, fields) {
     return concat([MANDATE_SIGNATURE_TAG, encodeAbiParameters(pullInputs, [pull, fields])]);
 }
-/** The Pull and L3a fields a relayed authorisation's signature carries, as Mandate Binding's `check` and `pull` take them. */
+/** The Pull and L3a fields an x402 payload's signature carries, as Mandate Binding's `check` and `pull` take them. */
 export function decodeMandateBlob(blob) {
     if (size(blob) < 4 || slice(blob, 0, 4) !== MANDATE_SIGNATURE_TAG)
         throw new Error("not a MetalAccount mandate signature");

package/dist/mandates/seller.d.ts

@@ -17,7 +17,7 @@ export type RequireSignedOfferConfig = {
  * On a route whose offer asks for it (`extra.signedOffer: "required"`), a
  * payment under a mandate must carry the agent's signed order, checked before
  * the facilitator is asked: the payer's account binds the mandate the payment
- * names, and the signed order is that mandate's agent key over the offer the
+ * names, and the signed order is that mandate's key over the offer the
  * server served, for this payee, buying its one line item (`extra.resource`
  * when the route names one, else the payee). A refusal is a 402 whose reason
  * names the check that failed, a payment that names no mandate included. A

package/dist/mandates/seller.js

@@ -1,8 +1,8 @@
 // The seller's side of a signed order: a check, before the facilitator is
 // asked to verify, that a payment under a mandate carries the agent's signed
 // offer for this very offer, under the agent key the payer's account binds.
-import { createPublicClient, getAddress, http, isAddress, isHex, isAddressEqual } from "viem";
-import { accountFactoryFor, metalNetwork } from "../networks.js";
+import { createPublicClient, getAddress, isAddress, isHex, isAddressEqual } from "viem";
+import { accountFactoryFor, metalNetwork, rpcTransport } from "../networks.js";
 import { assertMetalAccount } from "./account.js";
 import { referencePrefix } from "./binding.js";
 import { decodeMandateBlob } from "./l3a.js";
@@ -13,14 +13,14 @@ import { asksSignedOffer, mandateRefOf, signedOfferOf } from "./extension.js";
  * On a route whose offer asks for it (`extra.signedOffer: "required"`), a
  * payment under a mandate must carry the agent's signed order, checked before
  * the facilitator is asked: the payer's account binds the mandate the payment
- * names, and the signed order is that mandate's agent key over the offer the
+ * names, and the signed order is that mandate's key over the offer the
  * server served, for this payee, buying its one line item (`extra.resource`
  * when the route names one, else the payee). A refusal is a 402 whose reason
  * names the check that failed, a payment that names no mandate included. A
  * route that does not ask is left to the facilitator.
  */
 export function requireSignedOffer(server, config) {
-    const publicClient = "publicClient" in config ? config.publicClient : createPublicClient({ transport: http(config.rpcUrl) });
+    const publicClient = "publicClient" in config ? config.publicClient : createPublicClient({ transport: rpcTransport(config.rpcUrl) });
     const refuse = (reason) => ({ abort: true, reason });
     // x402 treats a hook that throws as one that passed, so a check that cannot
     // finish refuses the payment instead. The refusal reaches the payer, so it

package/dist/mandates/verify.d.ts

@@ -14,10 +14,10 @@ export interface VerifyStep {
     detail: string;
 }
 export declare const STEP_TITLES: {
-    readonly 1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the agent key and the issuer key are on chain";
-    readonly 2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and agent key";
+    readonly 1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the mandate key and the issuer key are on chain";
+    readonly 2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and mandate key";
     readonly 3: "The credential's signatures: the issuer's under a trusted key that is the one recorded at binding, the owner's under the key the issuer bound";
-    readonly 4: "Each payment and refusal is the agent key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block";
+    readonly 4: "Each payment and refusal is the mandate key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block";
 };
 /** A mandate as its `MandateBound` event records it. */
 export interface BoundMandate {
@@ -40,11 +40,9 @@ export interface VerifiedPayment {
     kind: "payment" | "refusal";
     txHash: Hash;
     block: bigint;
-    /** Whether `pull` submitted it, with no seller; otherwise a relayer submitted the ERC-3009 authorisation to the token. */
-    direct: boolean;
     to: Address;
     amount: bigint;
-    /** The ERC-3009 nonce the token recorded; a seller's `/settlements` row carries it for a relayed payment. */
+    /** The ERC-3009 nonce the token recorded; a seller's `/settlements` row carries it for a payment the facilitator settled. */
     nonce?: Hex;
     reason?: ReasonName;
     /** The L3a SD-JWT, as the VI reference serialises it, when the transaction carried one. */