@ftptech/canton-agent-wallet 0.1.15 → 0.1.17

package/dist/verify-prepared.js

@@ -161,8 +161,12 @@ function decodeMessage(buf) {
         else if (wire === WIRE_64) {
             if (pos + 8 > buf.length)
                 throw new PreparedDecodeError("64-bit field overruns buffer");
+            // Capture the 8 little-endian bytes: Daml `Value.timestamp` (Time µs) is a
+            // protobuf SFIXED64 (wire type 1), so a deadline/expiry leaf lives HERE, not
+            // as a varint. (Previously these bytes were discarded, which is why the
+            // allocation deadline read back as absent on the live wire.)
+            out.push({ field, wire, fixed64Bytes: buf.subarray(pos, pos + 8) });
             pos += 8;
-            out.push({ field, wire });
         }
         else if (wire === WIRE_32) {
             if (pos + 4 > buf.length)
@@ -227,6 +231,53 @@ function varintFields(fields, field) {
 function countVarintField(fields, field) {
     return varintFields(fields, field).length;
 }
+/** All WIRE_64 (fixed64) occurrences of a field number, in order. */
+function fixed64Fields(fields, field) {
+    return fields.filter((f) => f.field === field && f.wire === WIRE_64 && f.fixed64Bytes !== undefined);
+}
+/** Number of WIRE_64 occurrences of a field (duplicate-oneof detection for the
+ *  fixed64 `Value.timestamp` member, the analogue of `countVarintField`). */
+function countFixed64Field(fields, field) {
+    return fixed64Fields(fields, field).length;
+}
+/**
+ * Decode an 8-byte little-endian protobuf fixed64/sfixed64 as a BigInt — full
+ * 64-bit precision, no float loss. Daml `Value.timestamp` (`Time`, µs since
+ * epoch) is wire type 1 (SFIXED64), little-endian per the protobuf spec.
+ * Timestamps are non-negative in practice (Canton Time is post-epoch), so we
+ * read the value as UNSIGNED; a "negative" (high-bit) timestamp would be an
+ * absurd far-future µs count that the past-/ordering checks reject anyway.
+ */
+function fixed64ToBigInt(bytes) {
+    if (bytes.length !== 8) {
+        throw new PreparedDecodeError(`fixed64 field has ${bytes.length} bytes, expected exactly 8 — refusing to sign`);
+    }
+    let value = 0n;
+    for (let i = 7; i >= 0; i--) {
+        value = (value << 8n) | BigInt(bytes[i]);
+    }
+    return value;
+}
+/**
+ * Strict accessor for a NON-REPEATED fixed64 field (Daml `Time`/`Value.timestamp`):
+ * returns its single value as a BigInt, `undefined` if absent, and THROWS if it
+ * occurs more than once. Same fail-closed rationale as `varintFieldUnique`: the
+ * wire format is last-occurrence-wins for a non-repeated scalar, so a duplicate
+ * (decoy-first/real-second deadline) would let our read diverge from the
+ * participant's. There is no legitimate reason for a deadline leaf to appear
+ * twice within the same `Value`.
+ */
+function fixed64FieldUnique(fields, field, what) {
+    const all = fixed64Fields(fields, field);
+    if (all.length > 1) {
+        throw new PreparedDecodeError(`non-repeated fixed64 field ${field} (${what}) appears ${all.length} times — ` +
+            `ambiguous encoding (last-occurrence-wins on the participant), refusing to sign`);
+    }
+    const only = all[0];
+    if (only === undefined)
+        return undefined;
+    return fixed64ToBigInt(only.fixed64Bytes);
+}
 /**
  * Re-decode a raw varint byte-sequence as a BigInt — full int64 precision, no
  * `2**shift` float loss. proto3 int64 is up to 10 bytes (64 data bits). We cap
@@ -280,7 +331,7 @@ const V_UNIT = 1; // Value.unit (Daml `()`; google.protobuf.Empty). Non-party le
 const V_BOOL = 2; // Value.bool. Varint. Non-party leaf.
 const V_INT64 = 3; // Value.int64 (Daml `Int`, e.g. TransferCommand.nonce). Varint.
 const V_DATE = 4; // Value.date (Daml `Date`; days since epoch). Varint. Non-party leaf.
-const V_TIMESTAMP = 5; // Value.timestamp (Daml `Time`, e.g. expiresAt). Varint µs.
+const V_TIMESTAMP = 5; // Value.timestamp (Daml `Time`, e.g. expiresAt). SFIXED64 µs (wire type 1, NOT varint).
 const V_NUMERIC = 6;
 const V_PARTY = 7;
 const V_TEXT = 8;
@@ -387,11 +438,18 @@ function assertSingleValueMember(value) {
         { tag: V_GEN_MAP, what: "Value.gen_map" },
         { tag: V_VARIANT, what: "Value.variant" },
     ];
-    // Varint oneof members (Daml Int / Time). Counted separately because they use
-    // wire type 0, not length-delimited; a duplicate int64 (decoy nonce first,
-    // real nonce second) must be caught with the SAME fail-closed rigor.
+    // Varint oneof members (Daml `Int`). Counted separately because they use wire
+    // type 0, not length-delimited; a duplicate int64 (decoy nonce first, real
+    // nonce second) must be caught with the SAME fail-closed rigor.
     const varintMembers = [
         { tag: V_INT64, what: "Value.int64" },
+    ];
+    // Fixed64 oneof members (Daml `Time`/`Value.timestamp`). These use wire type 1
+    // (SFIXED64), NOT varint — so a duplicate deadline (decoy-first/real-second)
+    // would be INVISIBLE to the varint counter and could let our read diverge from
+    // the participant's. Count them with their own wire-type-correct accessor so the
+    // single-member + duplicate guards cover the timestamp leaf too.
+    const fixed64Members = [
         { tag: V_TIMESTAMP, what: "Value.timestamp" },
     ];
     let present = 0;
@@ -413,6 +471,15 @@ function assertSingleValueMember(value) {
         if (count === 1)
             present++;
     }
+    for (const m of fixed64Members) {
+        const count = countFixed64Field(v, m.tag);
+        if (count > 1) {
+            throw new PreparedDecodeError(`Value oneof member ${m.what} set ${count} times — ambiguous encoding ` +
+                `(last-occurrence-wins on the participant), refusing to sign`);
+        }
+        if (count === 1)
+            present++;
+    }
     if (present > 1) {
         throw new PreparedDecodeError("Value sets more than one oneof member — ambiguous encoding, refusing to sign");
     }
@@ -454,10 +521,16 @@ function leafOf(value) {
     // signed read (a negative nonce still decodes negative for the sanity check).
     if (int64 !== undefined)
         return { kind: "int64", value: zigzagDecodeInt64(int64).toString() };
-    // Timestamp µs are always non-negative in practice; keep the raw (unsigned)
-    // value — Canton Time is post-epoch, so a "negative" timestamp would be a
-    // pre-1970 microsecond count we'd reject on the past-expiry check anyway.
-    const timestamp = varintFieldUnique(v, V_TIMESTAMP, "Value.timestamp");
+    // Daml `Value.timestamp` (`Time`, µs since epoch, e.g. settlement.allocateBefore/
+    // settleBefore) is a protobuf SFIXED64 — wire type 1, little-endian 8 bytes —
+    // NOT a varint. The earlier code read it via the varint accessor, so on the real
+    // wire (where the participant emits `field 5, wire 1`) the timestamp read back as
+    // ABSENT — the same fixture-vs-reality trap as the zigzag-nonce / Optional-DSO
+    // bugs: a varint-encoded fixture passed while the live fixed64 wire failed,
+    // false-tripping the deadline-fail-closed check on a legitimate allocation. Read
+    // it as a fixed64 so the value equals the participant's read. Timestamps are
+    // non-negative in practice; the unsigned value is exact (BigInt).
+    const timestamp = fixed64FieldUnique(v, V_TIMESTAMP, "Value.timestamp");
     if (timestamp !== undefined)
         return { kind: "timestamp", value: timestamp.toString() };
     return undefined;
@@ -696,6 +769,7 @@ const EX_RESULT = 13;
 const EX_CHOICE_OBSERVERS = 14;
 const EX_KEY = 15; // Exercise.key : optional GlobalKeyWithMaintainers
 // interactive.transaction.v1.Create field numbers.
+const CREATE_TEMPLATE_ID = 4; // Create.template_id : Identifier (same shape as Exercise.template_id).
 const CREATE_ARGUMENT = 5;
 const CREATE_SIGNATORIES = 6;
 const CREATE_STAKEHOLDERS = 7;
@@ -767,7 +841,7 @@ function identifierQualifiedName(idBytes) {
     catch {
         return undefined;
     }
-    if (flat.length === 0 || flat.includes(""))
+    if (flat.length === 0 || flat.includes("\u0000"))
         return undefined;
     const parts = flat.split(":");
     if (parts.length >= 3)
@@ -845,6 +919,7 @@ function decodeV1Node(v1Body) {
     if (create !== undefined) {
         const cFields = decodeMessage(create);
         const arg = lenFieldUnique(cFields, CREATE_ARGUMENT, "Create.argument");
+        const cTmpl = lenFieldUnique(cFields, CREATE_TEMPLATE_ID, "Create.template_id");
         const partyMeta = [
             ...stringFields(cFields, CREATE_SIGNATORIES),
             ...stringFields(cFields, CREATE_STAKEHOLDERS),
@@ -855,7 +930,19 @@ function decodeV1Node(v1Body) {
         const cKey = lenFieldUnique(cFields, CREATE_KEY, "Create.key");
         if (cKey !== undefined)
             collectGlobalKeyWithMaintainersParties(cKey, partyMeta, 0);
-        return { kind: "create", children: [], values: arg !== undefined ? [arg] : [], partyMeta };
+        return {
+            kind: "create",
+            // Capture the created template + argument so an arm can pin a NUMERIC
+            // (non-party) field of a consequence create (e.g. X402Escrow.amount), which
+            // the party-leaf backstop cannot see.
+            create: {
+                templateQualifiedName: cTmpl !== undefined ? identifierQualifiedName(cTmpl) : undefined,
+                argument: arg,
+            },
+            children: [],
+            values: arg !== undefined ? [arg] : [],
+            partyMeta,
+        };
     }
     if (rollback !== undefined) {
         const rFields = decodeMessage(rollback);
@@ -1003,6 +1090,7 @@ export function decodePrepared(preparedTransactionB64) {
             recognizedVersion: true,
             kind: dv.kind,
             exercise: dv.exercise,
+            create: dv.create,
             children: dv.children,
             values: dv.values,
             partyMeta: dv.partyMeta,
@@ -1164,6 +1252,101 @@ allowedConsequenceChoices = []) {
     }
     return { exercise: rootNode.exercise, rootNodeId: rootId };
 }
+/**
+ * Create-root analog of `assertSingleAllowedRootExercise`: assert the prepared
+ * transaction is EXACTLY a single top-level CREATE of the allowed template, with
+ * NO exercise anywhere (a value-moving choice is never a legitimate consequence of
+ * a bare consent create), EVERY node recognized, exactly ONE root that IS that
+ * create, and no orphan/extra-leg node.
+ *
+ * Used by the x402-direct onboarding arms (`createSenderConsent` /
+ * `createMerchantConsent`): the SenderConsent / MerchantConsent are created by the
+ * party SIGNING ITS OWN create (signatory = that party), so the prepared tx is a
+ * single CreateCommand → one CREATE root node. Creating a standing consent MOVES NO
+ * FUNDS; the ONLY parties it introduces are the signing party and the facilitator
+ * (observer). A relay-injected EXERCISE (an Allocation_ExecuteTransfer /
+ * TransferFactory_Transfer / CreateTransferCommand drain) or a second create/root is
+ * refused. Fail-closed in every case.
+ */
+function assertSingleAllowedRootCreate(decoded, 
+/** Caller-intent `module:entity` of the created template (e.g.
+ *  "X402Direct:SenderConsent"). Pinned against the create's decoded template when
+ *  present; a create carrying no decodable template is tolerated (normalized wire)
+ *  and identified by its principals at the call site. */
+expectedCreatedQualifiedName) {
+    // (1) NO exercise of any choice anywhere. A consent create has no value-moving
+    // consequence exercise; an exercise node is a relay-injected drain.
+    if (decoded.exercises.length > 0) {
+        throw new PreparedTransferMismatchError(`relay-prepared consent-create transaction contains ${decoded.exercises.length} ` +
+            `exercise(s) ${decoded.exercises
+                .map((e) => JSON.stringify(e.choiceId))
+                .join(", ")} — expected a single bare create with no exercise — refusing to sign`);
+    }
+    // (2) Every node fully recognized (same fail-closed stance as the exercise arm).
+    for (const node of decoded.nodes) {
+        if (!node.recognizedVersion) {
+            throw new PreparedTransferMismatchError(`relay-prepared transaction contains a node (id ${JSON.stringify(node.nodeId)}) carried ` +
+                `under an unrecognized node version — refusing to sign`);
+        }
+        if (node.kind === undefined) {
+            throw new PreparedTransferMismatchError(`relay-prepared transaction contains a node (id ${JSON.stringify(node.nodeId)}) with an ` +
+                `unknown or ambiguous node type — refusing to sign`);
+        }
+    }
+    // (3) Exactly one root, and it must be the allowed CREATE.
+    if (decoded.roots.length !== 1) {
+        throw new PreparedTransferMismatchError(`relay-prepared transaction has ${decoded.roots.length} root nodes — expected exactly one ` +
+            `(${JSON.stringify(expectedCreatedQualifiedName)} create) — refusing to sign`);
+    }
+    const byId = new Map();
+    for (const node of decoded.nodes) {
+        if (byId.has(node.nodeId)) {
+            throw new PreparedTransferMismatchError(`relay-prepared transaction has duplicate node id ${JSON.stringify(node.nodeId)} — ` +
+                `refusing to sign (ambiguous node graph)`);
+        }
+        byId.set(node.nodeId, node);
+    }
+    const rootId = decoded.roots[0];
+    const rootNode = byId.get(rootId);
+    if (rootNode === undefined) {
+        throw new PreparedTransferMismatchError(`relay-prepared transaction root id ${JSON.stringify(rootId)} does not match any node — ` +
+            `refusing to sign`);
+    }
+    if (rootNode.kind !== "create" || rootNode.create === undefined) {
+        throw new PreparedTransferMismatchError(`relay-prepared transaction root node is not a ${JSON.stringify(expectedCreatedQualifiedName)} ` +
+            `create (got node type ${JSON.stringify(rootNode.kind ?? "unknown")}) — refusing to sign`);
+    }
+    // Pin the created template's module:entity when the node carries one (a normalized
+    // wire may omit it; the caller then self-anchors on the create's principals).
+    if (rootNode.create.templateQualifiedName !== undefined &&
+        rootNode.create.templateQualifiedName !== expectedCreatedQualifiedName) {
+        throw new PreparedTransferMismatchError(`relay-prepared create is of template ${JSON.stringify(rootNode.create.templateQualifiedName)} — ` +
+            `expected ${JSON.stringify(expectedCreatedQualifiedName)} — refusing to sign`);
+    }
+    // (4) No orphans: every node reachable from the single root.
+    const reachable = new Set();
+    const stack = [rootId];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (reachable.has(id))
+            continue;
+        reachable.add(id);
+        const node = byId.get(id);
+        if (node === undefined) {
+            throw new PreparedTransferMismatchError(`relay-prepared transaction references child node id ${JSON.stringify(id)} that does not ` +
+                `exist — refusing to sign`);
+        }
+        for (const child of node.children)
+            stack.push(child);
+    }
+    const orphans = decoded.nodes.filter((nd) => !reachable.has(nd.nodeId));
+    if (orphans.length > 0) {
+        throw new PreparedTransferMismatchError(`relay-prepared transaction contains ${orphans.length} node(s) not reachable from the root ` +
+            `(ids ${orphans.map((o) => JSON.stringify(o.nodeId)).join(", ")}) — refusing to sign ` +
+            `(possible tampered/compromised relay hiding an extra leg)`);
+    }
+    return { create: rootNode.create, rootNodeId: rootId };
+}
 /* ────────────────────────────────────────────────────────────────────────
  * Shared SIGNED-Metadata checks (synchronizer + timing). Every field below is
  * in the proto's "Metadata information that needs to be signed" block, so the
@@ -1174,6 +1357,35 @@ allowedConsequenceChoices = []) {
  * ──────────────────────────────────────────────────────────────────────── */
 /** Pin Metadata.synchronizer_id to caller intent when the caller supplies one.
  *  Fail-closed: if pinned but absent/different, refuse. (No pin ⇒ unchanged.) */
+/**
+ * The version-serial suffix a participant deterministically appends to the
+ * LOGICAL synchronizer id to form the PHYSICAL one it signs into
+ * Metadata.synchronizer_id: `::<protocol-version>-<topology-serial>`, e.g. a
+ * logical `global-domain::1220<fingerprint>` is signed as
+ * `global-domain::1220<fingerprint>::35-2`. STRICT shape: two non-empty decimal
+ * runs joined by a single hyphen. (Confirmed on a live TestNet prepared
+ * AllocationFactory_Allocate: prepare REQUIRES the logical id — the participant
+ * 400s `INVALID_FIELD synchronizer_id` on the physical form — yet the bytes it
+ * returns carry the physical `::35-2` suffix, so an exact-equality pin against
+ * the logical caller intent false-rejects a legitimate tx.) */
+const PHYSICAL_SYNCHRONIZER_SUFFIX = /^[0-9]+-[0-9]+$/;
+/**
+ * Pin Metadata.synchronizer_id to caller intent. Fail-closed: a different domain
+ * is refused. The caller threads the LOGICAL synchronizer id (`<name>::<namespace
+ * fingerprint>`) — the value the participant accepts on prepare — but the SIGNED
+ * bytes carry the PHYSICAL id (logical + `::<version>-<serial>`). We therefore
+ * accept the signed id iff it is EXACTLY the expected logical id, OR the expected
+ * id followed by a single `::<version>-<serial>` suffix of the strict
+ * physical-synchronizer shape.
+ *
+ * This is NOT a weakening: the security-relevant identity is the logical id,
+ * whose `1220…` is the domain's cryptographic NAMESPACE fingerprint — an attacker
+ * cannot forge a different domain that shares it, so anything matching
+ * `expected + "::<n>-<m>"` is provably the SAME domain (same namespace owner) at
+ * a participant-chosen protocol-version/topology-serial. A genuinely different
+ * domain (different name or fingerprint), a non-suffix extension, or a
+ * garbage/empty suffix does NOT match and is still rejected.
+ */
 function assertSynchronizerMatches(synchronizerId, expected) {
     if (expected === undefined)
         return; // caller did not pin — unchanged behaviour
@@ -1181,9 +1393,17 @@ function assertSynchronizerMatches(synchronizerId, expected) {
         throw new PreparedTransferMismatchError(`relay-prepared transaction has no synchronizer_id but caller intent pins ` +
             `${JSON.stringify(expected)} — refusing to sign`);
     }
-    if (synchronizerId !== expected) {
+    let matches = synchronizerId === expected;
+    if (!matches && synchronizerId.startsWith(expected + "::")) {
+        // The remainder after the logical id MUST be exactly one physical-suffix
+        // segment `<version>-<serial>` — no further `::` segments, no empty/garbage.
+        const suffix = synchronizerId.slice(expected.length + 2);
+        matches = PHYSICAL_SYNCHRONIZER_SUFFIX.test(suffix);
+    }
+    if (!matches) {
         throw new PreparedTransferMismatchError(`relay-prepared transaction synchronizer_id is ${JSON.stringify(synchronizerId)} — expected ` +
-            `${JSON.stringify(expected)} — refusing to sign (relay-chosen synchronizer/domain)`);
+            `${JSON.stringify(expected)} (optionally with a ::<version>-<serial> physical suffix) — ` +
+            `refusing to sign (relay-chosen synchronizer/domain)`);
     }
 }
 /** A generous skew (24h) for sanity-bounding the SIGNED Metadata timing fields.
@@ -1565,6 +1785,17 @@ const TRANSFER_CONSEQUENCE_CHOICES = [
  * even though the numeric value is identical. Pure string math (no float) so
  * large amounts keep full precision. A non-numeric input is returned as-is, so
  * it still mismatches (fail-closed).
+ *
+ * UNIT-BY-SCHEME invariant: BOTH sides of every amount compare here are
+ * on-ledger Daml **Decimals** — `t.amount` is decoded from the prepared tx's
+ * `Value.numeric` (always a ledger Decimal) and `expect.amount` is the caller's
+ * INTENDED ledger Decimal (the relay/agent path sources `opts.amount` as the
+ * Decimal, never the x402 wire atomic value). `canonicalAmount` therefore only
+ * pads Decimals; it must NEVER be fed an atomic integer (an atomic "1" would
+ * canonicalize to "1.0000000000" and silently mis-compare against the ledger
+ * "0.0000000001"). If a future caller ever sources `expect.amount` from an
+ * atomic-scheme wire, it MUST first convert via
+ * `wireAmountToLedgerDecimal(scheme, amount)` from @ftptech/x402-canton-core.
  */
 export function canonicalAmount(raw) {
     const m = String(raw).trim().match(/^(\d+)(?:\.(\d*))?$/);
@@ -1910,6 +2141,808 @@ export function assertPreparedAcceptMatches(preparedTransactionB64, expect) {
     // authority, never a third party's.
     assertActAsIsSender(decoded.actAs, expect.selfParty);
 }
+/* ════════════════════════════════════════════════════════════════════════
+ * allocation-api (CIP-56 DVP) — verify-before-sign for the
+ * `AllocationFactory_Allocate` exercise.
+ *
+ * THREAT MODEL — identical to the cip56 / v1 arms, for the Allocation path.
+ * The agent asks the relay to PREPARE an `AllocationFactory_Allocate` (it LOCKS
+ * the agent's input holdings into an Allocation naming the facilitator as
+ * settlement.executor). A compromised relay could prepare a DIFFERENT
+ * allocation — swap the receiver, inflate the amount, name an ATTACKER (not the
+ * facilitator) as settlement.executor so the attacker can later steer
+ * Allocation_ExecuteTransfer, or widen the deadline window — and hand back its
+ * hash. Because the agent signs with its own key (the choice's sole controller
+ * is allocation.transferLeg.sender = the payer), a blind signature would
+ * authorize the attacker's allocation. We decode the prepared bytes with the
+ * SAME structural rigor (Daml-LF POSITIONAL record reads via entryByDeclOrder,
+ * fail-closed on duplicate/multi-member oneofs, parties matched BY TYPE not
+ * text) and assert each money/escrow-critical leaf equals CALLER INTENT at its
+ * declaration-order position.
+ *
+ * AllocationFactory_Allocate choiceArgument :: Record {
+ *   [0] expectedAdmin    : Party,                -- the instrument admin (DSO)
+ *   [1] allocation       : AllocationSpecification,
+ *   [2] requestedAt      : Time,
+ *   [3] inputHoldingCids : [ContractId Holding],
+ *   [4] extraArgs        : ExtraArgs
+ * }
+ * AllocationSpecification :: Record {
+ *   [0] settlement    : SettlementInfo {
+ *         [0] executor       : Party,   -- MUST == facilitatorParty (executor)
+ *         [1] settlementRef  : Reference,
+ *         [2] requestedAt    : Time,
+ *         [3] allocateBefore : Time,    -- MUST be < settleBefore
+ *         [4] settleBefore   : Time,
+ *         [5] meta           : Metadata },
+ *   [1] transferLegId : Text,
+ *   [2] transferLeg   : TransferLeg {
+ *         [0] sender       : Party,     -- the payer (sole controller; act_as)
+ *         [1] receiver     : Party,     -- MUST == merchant payTo from the 402
+ *         [2] amount       : Numeric,   -- MUST == the required amount
+ *         [3] instrumentId : InstrumentId { [0] admin : Party, [1] id : Text },
+ *         [4] meta         : Metadata }
+ * }
+ *
+ * FIELD-ORDER AUTHORITY (confirmed): the declared field ORDER above is CONFIRMED
+ * against the canonical Splice DAML source — Daml-LF encodes records POSITIONALLY
+ * by `with`-block field declaration order, so the canonical .daml IS the
+ * authoritative ground truth for these positions:
+ *   - SettlementInfo, TransferLeg, AllocationSpecification, Reference:
+ *       token-standard/splice-api-token-allocation-v1/daml/Splice/Api/Token/AllocationV1.daml
+ *   - InstrumentId:
+ *       token-standard/splice-api-token-holding-v1/daml/Splice/Api/Token/HoldingV1.daml
+ *   - AllocationFactory_Allocate choice arg:
+ *       token-standard/splice-api-token-allocation-instruction-v1/daml/Splice/Api/Token/AllocationInstructionV1.daml
+ *   repo github.com/canton-network/splice @ commit
+ *   b1767c6e9aba37a278faadd50b17b3e11b153a3f (main, fetched 2026-06-23). Every
+ *   position pinned below matches that source verbatim (AllocationSpecification
+ *   has 3 fields with transferLegId at [1] between settlement[0] and
+ *   transferLeg[2]; SettlementInfo executor[0]/allocateBefore[3]/settleBefore[4];
+ *   TransferLeg sender[0]/receiver[1]/amount[2]/instrumentId[3];
+ *   InstrumentId admin[0]/id[1]; choice arg allocation at [1]).
+ * Daml-LF binds records POSITIONALLY, so the positional reads below
+ * (entryByDeclOrder) are the exact, fail-closed pin the cip56/v1 arms already
+ * use; this is a STRUCTURAL pin by declaration order, not a best-effort substring
+ * scan. Do NOT silently relax the positional reads to label-based ones to "make
+ * it work" against a live shape — that reintroduces the label/position divergence
+ * vector the cip56 arm documents. RESIDUAL: a live participant prepared-tx vector
+ * remains a nice-to-have cross-check (DevNet infra-blocked: synchronizer topology
+ * frozen since 2026-06-03) but is no longer blocking — the canonical source above
+ * is the field-order authority.
+ * ════════════════════════════════════════════════════════════════════════ */
+/** The allocate choice on an AllocationFactory (allocation-api / DVP). */
+const ALLOCATE_CHOICE = "AllocationFactory_Allocate";
+/** Choices the honest AllocationFactory_Allocate consequence subtree carries —
+ *  for Amulet the allocation creates an AmuletAllocation + LockedAmulet and
+ *  archives the consumed input Amulet(s). Permitted ONLY as reachable
+ *  consequences of the single Allocate root (never as a second root / orphan);
+ *  sender/receiver/amount/executor/admin stay pinned by extractAllocation and
+ *  the all-nodes foreign-party backstop still runs, so an injected redirect is
+ *  refused. Kept conservative (Archive only) like the strict pay paths; widen
+ *  ONLY against a confirmed live consequence subtree, never speculatively. */
+const ALLOCATE_CONSEQUENCE_CHOICES = ["Archive"];
+/**
+ * Extract the allocation's money/escrow-critical leaves from the
+ * `AllocationFactory_Allocate` choice argument, BY TYPE at each Daml
+ * DECLARATION-ORDER POSITION (what the participant binds), NOT by label — with
+ * the same label/position-divergence guard the cip56/v1 arms use. Fails closed
+ * on any wrong-type / missing money-critical field.
+ */
+export function extractAllocation(chosenValue) {
+    const top = recordEntries(chosenValue);
+    // choiceArgument: [0]expectedAdmin [1]allocation [2]requestedAt
+    //                 [3]inputHoldingCids [4]extraArgs — read position 1 ONLY.
+    const allocationVal = entryByDeclOrder(top, 1, "allocation")?.value;
+    if (!allocationVal) {
+        throw new PreparedDecodeError("could not locate allocation record in AllocationFactory_Allocate choice argument");
+    }
+    // AllocationSpecification: [0]settlement [1]transferLegId [2]transferLeg.
+    const spec = recordEntries(allocationVal);
+    const settlementVal = entryByDeclOrder(spec, 0, "settlement")?.value;
+    const transferLegVal = entryByDeclOrder(spec, 2, "transferLeg")?.value;
+    if (!settlementVal)
+        throw new PreparedDecodeError("allocation.settlement missing");
+    if (!transferLegVal)
+        throw new PreparedDecodeError("allocation.transferLeg missing");
+    // SettlementInfo: [0]executor [1]settlementRef [2]requestedAt
+    //                 [3]allocateBefore [4]settleBefore [5]meta.
+    const settlement = recordEntries(settlementVal);
+    const executorE = entryByDeclOrder(settlement, 0, "executor");
+    const allocateBeforeE = entryByDeclOrder(settlement, 3, "allocateBefore");
+    const settleBeforeE = entryByDeclOrder(settlement, 4, "settleBefore");
+    const executor = executorE ? leafOf(executorE.value) : undefined;
+    const allocateBefore = allocateBeforeE ? leafOf(allocateBeforeE.value) : undefined;
+    const settleBefore = settleBeforeE ? leafOf(settleBeforeE.value) : undefined;
+    if (!executor || executor.kind !== "party") {
+        throw new PreparedDecodeError("allocation.settlement.executor is not a party");
+    }
+    // TransferLeg: [0]sender [1]receiver [2]amount [3]instrumentId [4]meta.
+    const leg = recordEntries(transferLegVal);
+    const senderE = entryByDeclOrder(leg, 0, "sender");
+    const receiverE = entryByDeclOrder(leg, 1, "receiver");
+    const amountE = entryByDeclOrder(leg, 2, "amount");
+    const instrE = entryByDeclOrder(leg, 3, "instrumentId");
+    const sender = senderE ? leafOf(senderE.value) : undefined;
+    const receiver = receiverE ? leafOf(receiverE.value) : undefined;
+    const amount = amountE ? leafOf(amountE.value) : undefined;
+    const instrumentVal = instrE?.value;
+    if (!sender || sender.kind !== "party") {
+        throw new PreparedDecodeError("allocation.transferLeg.sender is not a party");
+    }
+    if (!receiver || receiver.kind !== "party") {
+        throw new PreparedDecodeError("allocation.transferLeg.receiver is not a party");
+    }
+    if (!amount || amount.kind !== "numeric") {
+        throw new PreparedDecodeError("allocation.transferLeg.amount is not numeric");
+    }
+    if (!instrumentVal)
+        throw new PreparedDecodeError("allocation.transferLeg.instrumentId missing");
+    const instrument = readInstrument(instrumentVal);
+    return {
+        sender: sender.value,
+        receiver: receiver.value,
+        amount: amount.value,
+        instrumentAdmin: instrument.admin,
+        instrumentId: instrument.id,
+        executor: executor.value,
+        ...(allocateBefore && allocateBefore.kind === "timestamp"
+            ? { allocateBefore: allocateBefore.value }
+            : {}),
+        ...(settleBefore && settleBefore.kind === "timestamp"
+            ? { settleBefore: settleBefore.value }
+            : {}),
+    };
+}
+/**
+ * Assert the relay-returned `preparedTransaction` encodes EXACTLY the
+ * `AllocationFactory_Allocate` the agent intended. Throws
+ * `PreparedTransferMismatchError` on any mismatch and `PreparedDecodeError` if
+ * the bytes are not a decodable PreparedTransaction carrying a single allocate
+ * exercise. Call BEFORE signing the hash. Fail-closed: anything not positively
+ * proven to match the intent throws.
+ */
+export function assertPreparedAllocationMatches(preparedTransactionB64, expect) {
+    const decoded = decodePrepared(preparedTransactionB64);
+    // Node-traversal invariant (shared with the cip56 / v1 arms): exactly one
+    // allowed ROOT exercise & no other; EVERY node recognized; EXACTLY ONE root
+    // that IS the single allowed AllocationFactory_Allocate exercise; no
+    // orphan/extra-leg node. Honest Amulet consequence (Archive of the locked
+    // input) whitelisted as a CONSEQUENCE only.
+    const { exercise: ex, rootNodeId } = assertSingleAllowedRootExercise(decoded, ALLOCATE_CHOICE, "allocation", ALLOCATE_CONSEQUENCE_CHOICES);
+    const a = extractAllocation(ex.chosenValue);
+    // OWN-PARTY SENDER PIN (hardening) — asserted FIRST, fail-CLOSED. The
+    // AllocationFactory_Allocate controller is the sender, and the agent knows its
+    // OWN party (wallet.party) independently of the relay. The extracted
+    // transferLeg.sender MUST equal that own party. transferLeg.sender and
+    // transferLeg.receiver are BOTH Party leaves at adjacent declaration-order
+    // positions and the declared order is not yet confirmed against a live wire, so
+    // a real-wire transposition of those two (or a wrong-position sender) could
+    // otherwise slip past the type guard. Pinning the sender to the agent's own
+    // party neutralizes that transposition risk REGARDLESS of field order — a swap
+    // that puts any non-self party (e.g. the receiver/merchant) in the sender
+    // position is refused here before anything else runs.
+    if (a.sender !== expect.expectedSender) {
+        throw new PreparedTransferMismatchError(`relay-prepared allocation transferLeg.sender (got ${JSON.stringify(a.sender)}) is not ` +
+            `the agent's own party (${JSON.stringify(expect.expectedSender)}) — refusing to sign ` +
+            `(possible sender/receiver transposition or wrong-position sender from a tampered/` +
+            `compromised relay redirecting the locked funds)`);
+    }
+    const mismatches = [];
+    if (a.sender !== expect.sender) {
+        mismatches.push(`transferLeg.sender (got ${JSON.stringify(a.sender)}, intended ${JSON.stringify(expect.sender)})`);
+    }
+    if (a.receiver !== expect.receiver) {
+        mismatches.push(`transferLeg.receiver (got ${JSON.stringify(a.receiver)}, intended ${JSON.stringify(expect.receiver)})`);
+    }
+    if (canonicalAmount(a.amount) !== canonicalAmount(expect.amount)) {
+        mismatches.push(`transferLeg.amount (got ${JSON.stringify(a.amount)}, intended ${JSON.stringify(expect.amount)})`);
+    }
+    if (a.instrumentId !== expect.instrumentId) {
+        mismatches.push(`transferLeg.instrumentId.id (got ${JSON.stringify(a.instrumentId)}, intended ${JSON.stringify(expect.instrumentId)})`);
+    }
+    // settlement.executor MUST equal the facilitator party (escrow-trust anchor).
+    if (a.executor !== expect.executor) {
+        mismatches.push(`settlement.executor (got ${JSON.stringify(a.executor)}, intended ${JSON.stringify(expect.executor)})`);
+    }
+    // Only pin the admin if the caller supplied an independently-trusted value.
+    if (expect.instrumentAdmin !== undefined && a.instrumentAdmin !== expect.instrumentAdmin) {
+        mismatches.push(`transferLeg.instrumentId.admin (got ${JSON.stringify(a.instrumentAdmin)}, intended ${JSON.stringify(expect.instrumentAdmin)})`);
+    }
+    if (mismatches.length > 0) {
+        throw new PreparedTransferMismatchError(`relay-prepared allocation does not match intent: ${mismatches.join("; ")} — ` +
+            `refusing to sign (possible tampered/compromised relay redirecting funds or executor)`);
+    }
+    // The admin/dso must never be aliased to a money/escrow role — otherwise a
+    // relay could set the (unpinned) admin to the receiver/sender/executor and
+    // have the backstop exempt that party. Reject up front.
+    if (a.instrumentAdmin === expect.sender ||
+        a.instrumentAdmin === expect.receiver ||
+        a.instrumentAdmin === expect.executor) {
+        throw new PreparedTransferMismatchError(`relay-prepared allocation instrumentId.admin ${JSON.stringify(a.instrumentAdmin)} equals a ` +
+            `transfer/escrow party (sender/receiver/executor) — refusing to sign`);
+    }
+    // The executor must not be aliased to the sender or receiver — the executor is
+    // the facilitator (a distinct party); collapsing it onto a money party would
+    // defeat the escrow-trust separation.
+    if (a.executor === expect.sender || a.executor === expect.receiver) {
+        throw new PreparedTransferMismatchError(`relay-prepared allocation settlement.executor ${JSON.stringify(a.executor)} equals the ` +
+            `sender or receiver — refusing to sign (escrow-trust separation broken)`);
+    }
+    // DEADLINE FAIL-CLOSED (hardening). Both allocateBefore AND settleBefore MUST
+    // be present as Value.timestamp leaves. extractAllocation only populates these
+    // when the leaf is actually a `timestamp`; a relay that OMITS a deadline leaf
+    // or RE-TYPES it (e.g. a text/numeric/optional leaf at the settleBefore
+    // position) makes the field read back undefined. Previously the ordering +
+    // future-margin check was CONDITIONAL on both being present, so such a relay
+    // could make the client skip the check entirely. Now a missing/wrong-type
+    // deadline is itself a tamper signal: THROW (fail closed) rather than sign an
+    // allocation with no enforceable settle window.
+    if (a.allocateBefore === undefined || a.settleBefore === undefined) {
+        throw new PreparedTransferMismatchError(`relay-prepared allocation is missing a timestamp deadline ` +
+            `(allocateBefore present=${a.allocateBefore !== undefined}, ` +
+            `settleBefore present=${a.settleBefore !== undefined}) — refusing to sign ` +
+            `(a relay that omits or re-types a deadline leaf must not bypass the ` +
+            `ordering + future-margin check)`);
+    }
+    // allocateBefore < settleBefore (deadline ordering). The spec REQUIRES
+    // settleBefore strictly after allocateBefore; an inverted/equal window is a
+    // tamper signal (it would make the allocation un-executable or immediately
+    // reclaimable). Both are Value.timestamp µs since epoch.
+    {
+        let ab;
+        let sb;
+        try {
+            ab = BigInt(a.allocateBefore);
+            sb = BigInt(a.settleBefore);
+        }
+        catch {
+            throw new PreparedTransferMismatchError(`relay-prepared allocation has a non-integer deadline — refusing to sign`);
+        }
+        if (!(ab < sb)) {
+            throw new PreparedTransferMismatchError(`relay-prepared allocation has allocateBefore (${a.allocateBefore}) >= settleBefore ` +
+                `(${a.settleBefore}) — refusing to sign (invalid/un-executable deadline window)`);
+        }
+        // settleBefore must be in the future — a lapsed window can never settle.
+        const nowMs = expect.nowMs ?? Date.now();
+        const settleMs = Number(sb / 1000n);
+        if (Number.isFinite(settleMs) && settleMs <= nowMs) {
+            throw new PreparedTransferMismatchError(`relay-prepared allocation settleBefore (${new Date(settleMs).toISOString()}) is in the ` +
+                `past — refusing to sign (allocation could never be executed)`);
+        }
+    }
+    // Pin WHICH template + WHICH contract the choice runs against, and the SIGNED
+    // synchronizer + timing metadata. No-ops unless the caller supplies intent.
+    assertTemplateMatches(ex, expect.templateQualifiedName);
+    assertContractIdMatches(ex, expect.expectedContractId);
+    assertSynchronizerMatches(decoded.synchronizerId, expect.synchronizerId);
+    assertTimingPlausible(decoded, expect.nowMs ?? Date.now());
+    // Cross-check the authoritative submitter: the allocate's sole controller is
+    // transferLeg.sender = the agent, so act_as must be exactly the agent.
+    assertActAsIsSender(decoded.actAs, expect.sender);
+    // Position-aware foreign-party backstop over the WHOLE signed message. Allowed
+    // recipients are {sender, receiver, executor} — the executor (facilitator) is a
+    // LEGITIMATE party of the allocation (it is settlement.executor / observer), so
+    // it must be in the allowed set or the honest allocation's own executor leaf
+    // would surface as foreign. The instrument admin (DSO) is allowed at its known
+    // root positions (expectedAdmin + instrumentId.admin = 2), value-excluded
+    // OUTSIDE its root position ONLY when pinned to an independently-trusted value.
+    const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
+    assertNoForeignParties(leaves, new Set([expect.sender, expect.receiver, expect.executor]), a.instrumentAdmin, 2 /* expectedAdmin + instrumentId.admin */, expect.instrumentAdmin !== undefined /* trusted iff caller pinned it */);
+}
+/* ════════════════════════════════════════════════════════════════════════
+ * allocation-api reclaim — verify-before-sign for `Allocation_Withdraw`
+ * (Track B "locked funds always recoverable").
+ *
+ * THREAT MODEL. The agent has an open `AmuletAllocation` (it locked its own
+ * holdings into an Allocation for a DvP that never settled / it wants to abort)
+ * and wants its funds BACK. The canonical recovery choice on
+ * `Splice.Api.Token.AllocationV1` is `Allocation_Withdraw`:
+ *
+ *   choice Allocation_Withdraw : Allocation_WithdrawResult
+ *     controller (view this).allocation.transferLeg.sender   -- the SENDER ALONE
+ *     with extraArgs : ExtraArgs
+ *   -- returns Allocation_WithdrawResult { senderHoldingCids, meta }
+ *   -- funds return to the sender BY CONSTRUCTION (no attacker-controllable
+ *      destination is encodable in the choice argument).
+ *   Confirmed against canton-network/splice@main, interface
+ *   Splice.Api.Token.AllocationV1.
+ *
+ * Even though the funds return to the sender by the choice's own definition, the
+ * agent must NOT blind-sign a relay-prepared `Allocation_Withdraw`: a compromised
+ * relay could instead prepare (a) a DIFFERENT choice that DOES move value to the
+ * attacker (e.g. `Allocation_ExecuteTransfer`, a `TransferFactory_Transfer`
+ * drain), (b) a withdraw of a DIFFERENT allocation than the one the caller
+ * intended, (c) a withdraw with an extra/sibling outbound transfer leg as a
+ * consequence, or (d) the same choice submitted under a foreign party's
+ * authority. We therefore apply the SAME fail-closed structural gate the accept
+ * (claim) arm uses — accept is the closest analog (funds-IN, structural,
+ * own-party) — PLUS a REQUIRED contract-id pin (the caller names exactly which
+ * allocation to reclaim, closing the resolve→prepare TOCTOU) and the all-nodes
+ * foreign-party backstop with the ONLY allowed party being the agent itself
+ * (Allocation_Withdraw returns funds to the sender, so ANY other party anywhere
+ * — an injected outbound leg, a different receiver, an executor-as-payee — is a
+ * smuggled redirect and is rejected). Anything not positively proven to be a
+ * single self-submitted withdraw of the caller's own allocation throws.
+ * ════════════════════════════════════════════════════════════════════════ */
+/** The reclaim choice on a Splice AmuletAllocation (funds-back / Track B). */
+const WITHDRAW_CHOICE = "Allocation_Withdraw";
+/** Choices the honest `Allocation_Withdraw` consequence subtree carries: it
+ *  archives the consumed `AmuletAllocation` / `LockedAmulet` and recreates the
+ *  sender's Amulet(s). Kept conservative (Archive only) like the strict pay /
+ *  allocate paths — a value-MOVING choice is never whitelisted here, so an
+ *  injected outbound drain is refused. Widen ONLY against a confirmed live
+ *  consequence subtree, never speculatively; the foreign-party backstop is the
+ *  real guard against a smuggled outbound leg regardless. */
+// Honest Allocation_Withdraw consequences. With an expire-lock choice-context the
+// withdraw unlocks the held Amulet back to its owner (the sender) via
+// LockedAmulet_UnlockV2 (older ledgers: LockedAmulet_Unlock) and archives the
+// consumed AmuletAllocation/LockedAmulet. These are SAFE to whitelist because the
+// step-5 foreign-party backstop still runs over the WHOLE signed message with the
+// agent (sender) as the ONLY permitted party — the unlock can therefore only
+// return funds to the sender, never redirect them. A relay-injected outbound drain
+// (Allocation_ExecuteTransfer / TransferFactory_Transfer / a second root) is still
+// neither the root choice nor a whitelisted consequence, so it is refused.
+const WITHDRAW_CONSEQUENCE_CHOICES = [
+    "Archive",
+    "LockedAmulet_UnlockV2",
+    "LockedAmulet_Unlock",
+];
+/**
+ * Assert the relay-returned `preparedTransaction` for the reclaim path encodes
+ * EXACTLY a single `Allocation_Withdraw` exercise, on the caller's own
+ * allocation cid, submitted by the agent — and is NOT a different (value-moving)
+ * choice, a withdraw of a different contract, an outbound drain, or a
+ * foreign-party submission. Throws `PreparedTransferMismatchError` on any
+ * mismatch and `PreparedDecodeError` if the bytes are not a decodable
+ * PreparedTransaction. Call BEFORE signing the hash. Fail-closed: anything not
+ * positively proven to be a self-withdraw of the caller's own allocation throws.
+ */
+export function assertPreparedAllocationWithdrawMatches(preparedTransactionB64, expect) {
+    const decoded = decodePrepared(preparedTransactionB64);
+    // (1) Shared node-traversal invariant: EXACTLY ONE root and it IS the
+    // Allocation_Withdraw exercise; EVERY node recognized; no orphan/extra-leg
+    // node. The honest withdraw's settlement consequences (Archive of the consumed
+    // AmuletAllocation / LockedAmulet) are whitelisted as CONSEQUENCES only — still
+    // bound to the single Withdraw root by the reachability check. A relay-injected
+    // outbound drain (Allocation_ExecuteTransfer / TransferFactory_Transfer /
+    // CreateTransferCommand / a second root) is refused: it is neither the root
+    // choice nor a whitelisted consequence.
+    const { exercise: ex, rootNodeId } = assertSingleAllowedRootExercise(decoded, WITHDRAW_CHOICE, WITHDRAW_CHOICE, WITHDRAW_CONSEQUENCE_CHOICES);
+    // (2) Target-contract pin (CALLER INTENT — REQUIRED). The exercised
+    // Exercise.contract_id MUST equal the caller's allocationCid: this is the core
+    // "withdraw exactly the allocation I asked for" guarantee and closes the
+    // resolve→prepare TOCTOU (a relay resolving one allocation to us then preparing
+    // the withdraw against another).
+    assertContractIdMatches(ex, expect.allocationCid);
+    // (3) SIGNED timing metadata sanity (relay-chosen validity window).
+    assertTimingPlausible(decoded, expect.nowMs ?? Date.now());
+    // (4) act_as / controller = own party. The submitter (the authoritative
+    // act_as) must be exactly the agent. The Daml controller is
+    // allocation.transferLeg.sender; since act_as is the authoritative submitter
+    // and the choice's sole controller is the sender, pinning act_as == selfParty
+    // proves the agent is the sender exercising its own reclaim.
+    assertActAsIsSender(decoded.actAs, expect.selfParty);
+    // (5) Foreign-party / no-outbound-leg backstop over the WHOLE signed message.
+    // Allocation_Withdraw returns funds to the SENDER by construction, so the ONLY
+    // party permitted anywhere — root chosen_value, consequence/sibling nodes, any
+    // node's party metadata, Metadata.input_contracts — is the agent itself. ANY
+    // other party (an injected outbound transfer leg, a different receiver, an
+    // executor-as-payee, a foreign submitter leaf) is a smuggled redirect and is
+    // rejected. No admin/dso exemption is threaded (unlike accept/allocate): zero
+    // allowed admin slots, so a relay-supplied DSO cannot be aliased to an attacker
+    // and smuggled in. Widen ONLY if a confirmed live consequence subtree proves an
+    // honest non-self party must appear — never speculatively.
+    const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
+    // Allowed parties: the sender (funds-back recipient) ALWAYS, plus — ONLY when
+    // the caller pinned them (lock-expiry path) — the facilitator (the allocation
+    // executor / lock holder, who is a stakeholder on the unlocked LockedAmulet and
+    // on disclosed contracts), the DSO (AmuletRules signatory referenced by the
+    // expire-lock context), and the RECEIVER (merchant). All are caller-intent, so a
+    // relay cannot smuggle a foreign recipient by aliasing it to one of them. On the
+    // no-lock (empty-context) path none is pinned and the set stays {sender} exactly.
+    //
+    // The receiver pin closes the "Design B" DIRECT gap: there the allocation's
+    // receiver is the MERCHANT (not the facilitator, as in "Design A" escrow where
+    // receiver == executor == facilitator), so the legitimate expire-lock
+    // choice-context references the merchant party — which is none of
+    // {self, facilitator, instrumentAdmin}, so the backstop would otherwise reject a
+    // VALID withdraw. We add EXACTLY the caller-pinned receiver (never a wildcard),
+    // so it remains fail-closed: an UNPINNED receiver is still rejected, and any
+    // party other than the exact pinned receiver is still rejected. Design A omits it
+    // (receiver == facilitator, already allowed) and behavior is unchanged.
+    const allowedWithdraw = new Set([expect.selfParty]);
+    if (expect.facilitator)
+        allowedWithdraw.add(expect.facilitator);
+    if (expect.receiver)
+        allowedWithdraw.add(expect.receiver);
+    assertNoForeignParties(leaves, allowedWithdraw, expect.instrumentAdmin /* DSO: AmuletRules signatory in the expire-lock ctx */, expect.instrumentAdmin !== undefined ? 4 : 0 /* AmuletRules + round + unlock refs */, expect.instrumentAdmin !== undefined /* trusted iff caller pinned it */);
+}
+/* ════════════════════════════════════════════════════════════════════════
+ * x402-escrow "Design A" ACCEPT — verify-before-sign for
+ * `X402EscrowOffer_Accept` (the sender captures its one-time authorization).
+ *
+ * THREAT MODEL. The facilitator created an `X402EscrowOffer` (signatory
+ * facilitator, observer sender) and the SENDER — an external party whose key the
+ * agent-wallet holds — must exercise `X402EscrowOffer_Accept` to durably capture
+ * its authorization. The choice's sole controller is the sender; ACCEPTING MOVES
+ * NO FUNDS — it only archives the offer and creates the `X402Escrow` whose
+ * signatories are {facilitator, sender}. (Source of truth: daml/x402-escrow/daml/
+ * X402Escrow.daml — template `X402EscrowOffer`, choice `X402EscrowOffer_Accept`,
+ * no choice args, `create X402Escrow with {facilitator, sender, merchant, amount,
+ * instrumentAdmin}`; X402Escrow `signatory facilitator, sender`.)
+ *
+ * Even though the accept moves no funds, the agent must NOT blind-sign a
+ * relay-prepared `X402EscrowOffer_Accept`: a compromised relay could instead
+ * prepare (a) a DIFFERENT, value-MOVING choice (an `Allocation_ExecuteTransfer` /
+ * `TransferFactory_Transfer` / `ExternalPartyAmuletRules_CreateTransferCommand` /
+ * `Allocation_Withdraw` drain), (b) an accept of a DIFFERENT offer contract than
+ * the one the caller intended, (c) an extra/sibling outbound transfer leg as a
+ * consequence (an injected Amulet/Holding create to a foreign party), or (d) the
+ * same choice submitted under a foreign party's authority. We apply the SAME
+ * fail-closed structural gate the withdraw/accept(claim) arms use — withdraw is
+ * the closest analog (own-party-controlled, structural, no money-critical leaf in
+ * the chosen value) — PLUS a REQUIRED offer contract-id pin (closing the
+ * resolve→prepare TOCTOU) and a position-aware foreign-party backstop whose
+ * ONLY allowed parties are the agent (sender) and the caller-pinned facilitator
+ * (the two `X402Escrow` signatories), optionally extended with the caller-pinned
+ * merchant + instrumentAdmin (recorded as reference fields on the created
+ * `X402Escrow`). ANY other party anywhere — a relay-substituted facilitator that
+ * could later settle the escrow to itself, an injected outbound transfer leg, a
+ * foreign submitter leaf — is a tamper signal and is rejected.
+ *
+ * WHAT AN ATTACKER-TAMPERED ACCEPT TRIPS:
+ *   - choice swapped to a value-moving drain        → root-choice pin (1)
+ *   - second/sibling outbound leg or extra root     → single-root + no-orphan (1)
+ *   - accept of a different offer cid               → contract-id pin (2)
+ *   - act_as a foreign party (or self+foreign)      → act_as == sender pin (4)
+ *   - relay-substituted facilitator / smuggled      → foreign-party backstop (5)
+ *     recipient party in the created escrow / a
+ *     consequence Amulet|Holding create
+ * Anything not positively proven to be a single self-submitted accept of the
+ * caller's own offer, creating an escrow only among the caller-intended parties,
+ * throws. Fail-closed in every case.
+ * ════════════════════════════════════════════════════════════════════════ */
+/** The accept choice on an `X402EscrowOffer` (Design A escrow setup). */
+const ESCROW_ACCEPT_CHOICE = "X402EscrowOffer_Accept";
+/** Choices the honest `X402EscrowOffer_Accept` consequence subtree carries: it
+ *  archives the consumed `X402EscrowOffer` and creates the `X402Escrow` (a Create
+ *  node, NOT an exercise). The only consequence EXERCISE is the Archive of the
+ *  offer. Kept conservative (Archive only) like the strict withdraw/allocate
+ *  paths — a value-MOVING choice is NEVER whitelisted here, so an injected
+ *  outbound drain (Allocation_ExecuteTransfer / TransferFactory_Transfer /
+ *  CreateTransferCommand) as a consequence is refused. Widen ONLY against a
+ *  confirmed live consequence subtree, never speculatively; the foreign-party
+ *  backstop is the real guard against a smuggled outbound leg regardless. */
+const ESCROW_ACCEPT_CONSEQUENCE_CHOICES = ["Archive"];
+/** The created template's `module:entity` qualified name for the `X402Escrow`
+ *  contract the accept's consequence Create produces (package-id dropped — it
+ *  changes across upgrades). Used to positively identify the escrow Create node
+ *  among the consequences when pinning its recorded `amount`. */
+const X402_ESCROW_CREATED_QUALIFIED_NAME = "X402Escrow:X402Escrow";
+/**
+ * Extract the `amount` recorded on a created `X402Escrow` from its `Create.argument`
+ * record, BY ITS DAML DECLARATION-ORDER POSITION (with the same label/position
+ * divergence guard the money fields use).
+ *
+ * X402Escrow create-args (X402Escrow.daml, Daml declaration order):
+ *   [0] facilitator : Party
+ *   [1] sender      : Party
+ *   [2] merchant    : Party
+ *   [3] amount      : Decimal   ← the load-bearing settle term
+ *   [4] instrumentAdmin : Party
+ *
+ * WHY THIS MATTERS (the amount-swap bypass the party backstop cannot see). The
+ * accept choice has NO arguments; the escrow's terms live in this CONSEQUENCE
+ * Create. The foreign-party backstop only inspects PARTY leaves, so a swapped
+ * `amount` (a Numeric) is INVISIBLE to it. Yet the escrow's `amount` is exactly
+ * what the facilitator's later `X402Escrow_Settle` pins the live allocation
+ * against (`assertMsg "allocation amount mismatch" (leg.amount == amount)` in
+ * X402Escrow.daml). A malicious/buggy facilitator that authored the offer with an
+ * inflated `amount` (sender shown a small price) would, on a blind-signed accept,
+ * obtain the sender's durable authorization for an escrow that settles the larger
+ * amount. So when the caller pins `amount`, the wallet MUST read this Numeric at
+ * its real position and require exact (canonical) equality — fail closed.
+ *
+ * Returns the amount as a decimal string. Throws `PreparedDecodeError` if the
+ * argument is not the escrow create record shape (position 3 not a Numeric, or a
+ * label/position divergence) — a tamper signal in itself.
+ */
+function extractEscrowCreateAmount(argument) {
+    const entries = recordEntries(argument);
+    const amountE = entryByDeclOrder(entries, 3, "amount");
+    const amount = amountE ? leafOf(amountE.value) : undefined;
+    if (!amount || amount.kind !== "numeric") {
+        throw new PreparedDecodeError("X402Escrow.amount is not numeric");
+    }
+    return amount.value;
+}
+/**
+ * Read the {facilitator, sender} parties of an `X402Escrow` create-args record at
+ * their declaration positions ([0] facilitator, [1] sender), for self-anchored
+ * identification of the escrow Create among consequence creates when the create
+ * carries no decodable template id. Returns undefined if the record is not the
+ * escrow shape at those positions (so a non-escrow consequence create is simply
+ * skipped, not mis-pinned).
+ */
+function readEscrowCreatePrincipals(argument) {
+    let entries;
+    try {
+        entries = recordEntries(argument);
+    }
+    catch {
+        return undefined;
+    }
+    let facilitator;
+    let sender;
+    try {
+        const facE = entryByDeclOrder(entries, 0, "facilitator");
+        const sndE = entryByDeclOrder(entries, 1, "sender");
+        facilitator = facE ? leafOf(facE.value) : undefined;
+        sender = sndE ? leafOf(sndE.value) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    if (!facilitator || facilitator.kind !== "party")
+        return undefined;
+    if (!sender || sender.kind !== "party")
+        return undefined;
+    return { facilitator: facilitator.value, sender: sender.value };
+}
+/**
+ * Pin the `amount` recorded on the created `X402Escrow` to caller intent, when the
+ * caller supplies one. Locates the single escrow Create node among the (already
+ * reachability-checked) consequence nodes — by its created-template qualified name
+ * when present, else self-anchored on the create's {facilitator, sender} principals
+ * matching the caller-pinned facilitator + selfParty — then requires its Numeric
+ * `amount` to canonically equal `expect.amount`. Fail closed: if the caller pins an
+ * amount and NO matching escrow create is found (or its amount differs / is not a
+ * Numeric), refuse to sign. No pin ⇒ unchanged behaviour.
+ */
+function assertEscrowCreateAmountMatches(decoded, expectedAmount, facilitator, selfParty) {
+    if (expectedAmount === undefined)
+        return; // caller did not pin — unchanged behaviour
+    // Candidate escrow Create nodes: prefer an exact created-template match; fall
+    // back to self-anchored principals (facilitator + sender) when the create
+    // carries no decodable template (e.g. a normalized wire). Both anchors are
+    // CALLER INTENT / already-trusted — never a relay-widened allowlist.
+    const escrowCreates = decoded.nodes.filter((n) => {
+        if (n.kind !== "create" || n.create === undefined || n.create.argument === undefined) {
+            return false;
+        }
+        if (n.create.templateQualifiedName === X402_ESCROW_CREATED_QUALIFIED_NAME)
+            return true;
+        if (n.create.templateQualifiedName !== undefined)
+            return false; // a DIFFERENT named template
+        const principals = readEscrowCreatePrincipals(n.create.argument);
+        return (principals !== undefined &&
+            principals.facilitator === facilitator &&
+            principals.sender === selfParty);
+    });
+    if (escrowCreates.length === 0) {
+        throw new PreparedTransferMismatchError(`relay-prepared escrow-accept does not create an X402Escrow with the caller's ` +
+            `{facilitator, sender} — refusing to sign (cannot verify the escrow's recorded amount)`);
+    }
+    if (escrowCreates.length > 1) {
+        throw new PreparedTransferMismatchError(`relay-prepared escrow-accept creates ${escrowCreates.length} X402Escrow contracts — ` +
+            `expected exactly one — refusing to sign`);
+    }
+    const argument = escrowCreates[0].create?.argument;
+    const onLedger = extractEscrowCreateAmount(argument);
+    if (canonicalAmount(onLedger) !== canonicalAmount(expectedAmount)) {
+        throw new PreparedTransferMismatchError(`relay-prepared escrow records amount ${JSON.stringify(onLedger)} — expected ` +
+            `${JSON.stringify(expectedAmount)} — refusing to sign ` +
+            `(a swapped escrow amount settles a different value than the sender intends)`);
+    }
+}
+/**
+ * Assert the relay-returned `preparedTransaction` for the escrow-accept path
+ * encodes EXACTLY a single `X402EscrowOffer_Accept` exercise, on the caller's own
+ * offer cid, submitted by the agent (sender) — and is NOT a different
+ * (value-moving) choice, an accept of a different contract, an outbound drain, or
+ * a foreign-party submission, and creates an `X402Escrow` only among the
+ * caller-intended parties. Throws `PreparedTransferMismatchError` on any mismatch
+ * and `PreparedDecodeError` if the bytes are not a decodable PreparedTransaction.
+ * Call BEFORE signing the hash. Fail-closed: anything not positively proven to be
+ * a self-submitted accept of the caller's own offer throws.
+ */
+export function assertPreparedEscrowAcceptMatches(preparedTransactionB64, expect) {
+    const decoded = decodePrepared(preparedTransactionB64);
+    // (1) Shared node-traversal invariant: EXACTLY ONE root and it IS the
+    // X402EscrowOffer_Accept exercise; EVERY node recognized; no orphan/extra-leg
+    // node. The honest accept's consequences (Archive of the consumed
+    // X402EscrowOffer + the Create of the X402Escrow — a Create node, not an
+    // exercise) are bound to the single Accept root by the reachability check; the
+    // only whitelisted consequence EXERCISE is Archive. A relay-injected outbound
+    // drain (Allocation_ExecuteTransfer / TransferFactory_Transfer /
+    // ExternalPartyAmuletRules_CreateTransferCommand / Allocation_Withdraw / a
+    // second root) is refused: it is neither the root choice nor a whitelisted
+    // consequence.
+    const { exercise: ex, rootNodeId } = assertSingleAllowedRootExercise(decoded, ESCROW_ACCEPT_CHOICE, ESCROW_ACCEPT_CHOICE, ESCROW_ACCEPT_CONSEQUENCE_CHOICES);
+    // (2) Target-contract pin (CALLER INTENT — REQUIRED). The exercised
+    // Exercise.contract_id MUST equal the caller's offerCid: the core "accept
+    // exactly the offer I asked for" guarantee, closing the resolve→prepare TOCTOU
+    // (a relay resolving one offer to us then preparing the accept against another).
+    assertContractIdMatches(ex, expect.offerCid);
+    // (3) Pin WHICH template the choice runs against + the SIGNED synchronizer +
+    // timing metadata. Template/synchronizer are no-ops unless the caller pins them;
+    // timing is always sanity-bounded (relay-chosen validity window).
+    assertTemplateMatches(ex, expect.templateQualifiedName);
+    assertSynchronizerMatches(decoded.synchronizerId, expect.synchronizerId);
+    assertTimingPlausible(decoded, expect.nowMs ?? Date.now());
+    // (4) act_as / controller = own party (the sender). The submitter (the
+    // authoritative act_as) must be exactly the agent. The Daml controller is the
+    // offer's `sender`; since act_as is the authoritative submitter and the choice's
+    // sole controller is the sender, pinning act_as == selfParty proves the agent is
+    // the sender exercising its own accept — never a third party's authority.
+    assertActAsIsSender(decoded.actAs, expect.selfParty);
+    // (5) Foreign-party / no-outbound-leg backstop over the WHOLE signed message.
+    // The honest accept creates an `X402Escrow` signed by {facilitator, sender} and
+    // recording merchant + instrumentAdmin as reference fields; the consumed
+    // `X402EscrowOffer` (signatory facilitator, observer sender) is archived and
+    // appears in Metadata.input_contracts. So the ONLY parties that may appear
+    // anywhere are the agent (sender), the caller-pinned facilitator, and — when the
+    // honest escrow names them as distinct parties — the caller-pinned merchant +
+    // instrumentAdmin. EVERY allowed party is CALLER INTENT (selfParty/facilitator
+    // are required; merchant/instrumentAdmin are pinned when supplied) — none is
+    // taken from the relay. ANY other party anywhere (a relay-substituted
+    // facilitator that could later settle to itself, an injected outbound transfer
+    // leg creating an Amulet/Holding for a foreign payee, a foreign submitter leaf)
+    // is a smuggled redirect and is rejected. No admin/dso *root-position* exemption
+    // is threaded (the instrumentAdmin here is a plain reference field of the created
+    // escrow, allowed by exact-equality membership when pinned, not by a positional
+    // admin budget): zero allowed admin slots, so a relay-supplied value cannot be
+    // aliased to an attacker and smuggled in.
+    const allowed = new Set([expect.selfParty, expect.facilitator]);
+    if (expect.merchant !== undefined)
+        allowed.add(expect.merchant);
+    if (expect.instrumentAdmin !== undefined)
+        allowed.add(expect.instrumentAdmin);
+    const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
+    assertNoForeignParties(leaves, allowed, undefined /* no positional admin/dso exemption */, 0 /* zero allowed admin slots */, false /* untrusted */);
+    // (6) NUMERIC escrow-term pin the party backstop cannot see. The accept choice
+    // has no arguments; the escrow's terms live in the consequence Create of the
+    // X402Escrow. `amount` is a Daml Decimal (a Numeric leaf), invisible to the
+    // foreign-party backstop above — yet it is exactly what the facilitator's later
+    // `X402Escrow_Settle` pins the live allocation against. When the caller pins an
+    // amount we read the created escrow's recorded `amount` at its real declaration
+    // position and require canonical equality; fail closed otherwise. This closes
+    // the amount-swap trust-boundary gap: a malicious/buggy facilitator authoring
+    // the offer with an inflated amount (sender shown a small price) can no longer
+    // get the sender to blind-authorize an escrow that settles the larger value.
+    assertEscrowCreateAmountMatches(decoded, expect.amount, expect.facilitator, expect.selfParty);
+}
+/* ════════════════════════════════════════════════════════════════════════
+ * x402-direct (Design B "2-tx DIRECT") CONSENT CREATE — verify-before-sign for a
+ * `SenderConsent` / `MerchantConsent` create (the party captures its one-time
+ * standing authorization).
+ *
+ * THREAT MODEL. In the direct flow each party signs ONE standing consent ever — the
+ * SENDER a `SenderConsent {sender, facilitator}`, the MERCHANT a `MerchantConsent
+ * {merchant, facilitator}` (source of truth: daml/x402-direct/daml/X402Direct.daml;
+ * each template's signatory is the named party, observer = facilitator). The party
+ * (an external party whose key the agent-wallet holds) creates it directly, so the
+ * prepared tx is a single CreateCommand → one CREATE root. CREATING A STANDING
+ * CONSENT MOVES NO FUNDS.
+ *
+ * Even so the agent must NOT blind-sign: a compromised relay could instead prepare
+ * (a) a value-MOVING exercise (an `Allocation_ExecuteTransfer` /
+ * `TransferFactory_Transfer` / `ExternalPartyAmuletRules_CreateTransferCommand` /
+ * `Allocation_Withdraw` drain), (b) a consent naming a DIFFERENT facilitator (who
+ * could later mint a both-party consent and settle the agent's allocations), (c) an
+ * extra/sibling outbound leg, or (d) a foreign-party submission. We apply a
+ * fail-closed CREATE-root gate (the create analog of the escrow-accept/withdraw
+ * arms): EXACTLY one create of the expected template, NO exercise anywhere, act_as
+ * == the signing party, the consent's [0] self-party == the agent AND [1]
+ * facilitator == caller intent, and a foreign-party backstop whose ONLY allowed
+ * parties are {selfParty, facilitator} (the consent's two parties). ANY other party
+ * anywhere — a relay-substituted facilitator, an injected outbound leg, a foreign
+ * submitter leaf — is rejected.
+ *
+ * WHAT AN ATTACKER-TAMPERED CONSENT CREATE TRIPS:
+ *   - swapped to a value-moving exercise          → no-exercise + create-root pin
+ *   - second/sibling leg or extra root            → single-root + no-orphan
+ *   - relay-substituted facilitator               → [1] facilitator pin + backstop
+ *   - self-party not the agent                     → [0] self-party pin + act_as pin
+ *   - act_as a foreign party                       → act_as == selfParty pin
+ *   - any smuggled recipient party anywhere        → foreign-party backstop
+ * Anything not positively proven to be a single self-submitted create of the
+ * caller's own consent among exactly {selfParty, facilitator} throws. Fail-closed.
+ * ════════════════════════════════════════════════════════════════════════ */
+/** Created template `module:entity` names for the two standing consents. */
+const SENDER_CONSENT_CREATED_QUALIFIED_NAME = "X402Direct:SenderConsent";
+const MERCHANT_CONSENT_CREATED_QUALIFIED_NAME = "X402Direct:MerchantConsent";
+/** Read the {self, facilitator} parties of a consent create-args record at their
+ *  declaration positions ([0] self, [1] facilitator). Both SenderConsent and
+ *  MerchantConsent share this shape (the [0] label differs: sender vs merchant).
+ *  Returns undefined if the record is not the consent shape at those positions. */
+function readConsentCreatePrincipals(argument, selfLabel) {
+    let entries;
+    try {
+        entries = recordEntries(argument);
+    }
+    catch {
+        return undefined;
+    }
+    let self;
+    let facilitator;
+    try {
+        const selfE = entryByDeclOrder(entries, 0, selfLabel);
+        const facE = entryByDeclOrder(entries, 1, "facilitator");
+        self = selfE ? leafOf(selfE.value) : undefined;
+        facilitator = facE ? leafOf(facE.value) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    if (!self || self.kind !== "party")
+        return undefined;
+    if (!facilitator || facilitator.kind !== "party")
+        return undefined;
+    return { self: self.value, facilitator: facilitator.value };
+}
+/**
+ * Assert the relay-returned `preparedTransaction` for the x402-direct consent-create
+ * path encodes EXACTLY a single `SenderConsent` / `MerchantConsent` create, signed
+ * by the agent, naming {selfParty, facilitator} — and is NOT a value-moving choice,
+ * a second leg, a relay-substituted facilitator, or a foreign-party submission.
+ * Throws `PreparedTransferMismatchError` on any mismatch and `PreparedDecodeError`
+ * if the bytes are not a decodable PreparedTransaction. Call BEFORE signing. Fail-
+ * closed: anything not positively proven to be a self-submitted consent create among
+ * exactly {selfParty, facilitator} throws.
+ */
+export function assertPreparedConsentCreateMatches(preparedTransactionB64, expect) {
+    const decoded = decodePrepared(preparedTransactionB64);
+    const selfLabel = expect.consent === "sender" ? "sender" : "merchant";
+    const expectedCreatedQualifiedName = expect.consent === "sender"
+        ? SENDER_CONSENT_CREATED_QUALIFIED_NAME
+        : MERCHANT_CONSENT_CREATED_QUALIFIED_NAME;
+    // (1) Shared CREATE-root invariant: EXACTLY one create of the expected consent
+    // template, NO exercise anywhere, every node recognized, no orphan/extra-leg node.
+    const { create, rootNodeId } = assertSingleAllowedRootCreate(decoded, expectedCreatedQualifiedName);
+    // (2) Pin the SIGNED synchronizer + timing metadata (relay-chosen validity
+    // window). Synchronizer is a no-op unless the caller pins it; timing is always
+    // sanity-bounded.
+    assertSynchronizerMatches(decoded.synchronizerId, expect.synchronizerId);
+    assertTimingPlausible(decoded, expect.nowMs ?? Date.now());
+    // (3) act_as / signatory = own party. The consent's sole signatory is the signing
+    // party; act_as is the authoritative submitter, so act_as == selfParty proves the
+    // agent is creating its OWN consent (never a third party's authority).
+    assertActAsIsSender(decoded.actAs, expect.selfParty);
+    // (4) The created consent's principals at their declaration positions: [0] the
+    // self-party (sender/merchant) MUST equal the agent, [1] facilitator MUST equal
+    // caller intent. This pins WHO the consent binds — a relay-substituted facilitator
+    // (who could later mint a both-party consent and settle the agent's allocations)
+    // or a self-party other than the agent is rejected here even before the backstop.
+    if (create.argument === undefined) {
+        throw new PreparedTransferMismatchError(`relay-prepared consent create carries no decodable argument — refusing to sign ` +
+            `(cannot verify the consent's {${selfLabel}, facilitator})`);
+    }
+    const principals = readConsentCreatePrincipals(create.argument, selfLabel);
+    if (principals === undefined) {
+        throw new PreparedTransferMismatchError(`relay-prepared consent create argument is not the {${selfLabel}, facilitator} record ` +
+            `shape at positions [0],[1] — refusing to sign`);
+    }
+    if (principals.self !== expect.selfParty) {
+        throw new PreparedTransferMismatchError(`relay-prepared consent ${selfLabel} is ${JSON.stringify(principals.self)} — expected the ` +
+            `agent ${JSON.stringify(expect.selfParty)} — refusing to sign`);
+    }
+    if (principals.facilitator !== expect.facilitator) {
+        throw new PreparedTransferMismatchError(`relay-prepared consent facilitator is ${JSON.stringify(principals.facilitator)} — expected ` +
+            `${JSON.stringify(expect.facilitator)} — refusing to sign (a relay-substituted facilitator ` +
+            `could later mint a both-party consent and settle the agent's allocations)`);
+    }
+    // (5) Foreign-party backstop over the WHOLE signed message. The honest consent
+    // create introduces ONLY {selfParty, facilitator} (signatory + observer); the
+    // create root has no exercise, so all its party leaves are scanned under
+    // `elsewhere`. ANY other party anywhere is a smuggled redirect. Both allowed
+    // parties are CALLER INTENT; zero admin/dso slots (a consent has no instrument
+    // admin), so a relay-supplied value cannot be aliased in.
+    const allowed = new Set([expect.selfParty, expect.facilitator]);
+    const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
+    assertNoForeignParties(leaves, allowed, undefined /* no admin/dso exemption */, 0 /* zero allowed admin slots */, false /* untrusted */);
+}
 /** Thrown when a supplied `recomputeHash` cannot faithfully encode the bytes. */
 export class PreparedHashUnavailableError extends Error {
     constructor(message) {