@ftptech/canton-agent-wallet 0.1.19 → 0.2.0

package/dist/verify-prepared.js

@@ -535,31 +535,6 @@ function leafOf(value) {
         return { kind: "timestamp", value: timestamp.toString() };
     return undefined;
 }
-/**
- * Read an `Optional Party` leaf out of a `Value`, unwrapping exactly one `Some`.
- *
- * The Splice `ExternalPartyAmuletRules_CreateTransferCommand` declares its
- * `expectedDso` field as `Optional Party`, so the participant encodes the present
- * value as `Value.optional { value: Value.party }` — NOT a bare `Value.party`.
- * The scalar `leafOf` only reads bare leaves, so it returns undefined for the
- * wrapped party and the matcher then wrongly sees `expectedDso = undefined`,
- * rejecting EVERY honest v1 payment. We unwrap one `Some` level here (the same
- * `Value.optional → Optional.value` shape `collectPartyLeaves` descends) and read
- * the inner party with the SAME strict leaf reader (so a duplicate/decoy inner
- * member still fails closed). Returns undefined for `None` or a non-party inner;
- * the caller pins it by exact equality to the trusted DSO, so a forged inner
- * party surfaces as a field mismatch. A bare (non-optional) Party is tolerated
- * defensively in case a future package flattens the field.
- */
-function optionalPartyLeafOf(value) {
-    const opt = lenFieldUnique(decodeMessage(value), V_OPTIONAL, "Value.optional");
-    if (opt === undefined)
-        return leafOf(value); // defensive: bare Party shape
-    const inner = lenFieldUnique(decodeMessage(opt), OPTIONAL_VALUE, "Optional.value");
-    if (inner === undefined)
-        return undefined; // None
-    return leafOf(inner);
-}
 /** Decode a protobuf SINT64 zigzag varint to its signed BigInt value:
  *  zigzag(w) = (w >> 1) ^ -(w & 1). Daml-LF serializes `Value.int64` as sint64,
  *  so a wire varint of 0 is 0, 1 is -1, 2 is 1, 3 is -2, 4 is 2, … This is what
@@ -1873,214 +1848,6 @@ export function assertPreparedTransferMatches(preparedTransactionB64, expect) {
     const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
     assertNoForeignParties(leaves, new Set([expect.sender, expect.receiver]), t.instrumentAdmin, 2 /* expectedAdmin + instrumentId.admin */, expect.instrumentAdmin !== undefined /* trusted iff caller pinned it */);
 }
-/* ════════════════════════════════════════════════════════════════════════
- * v1 (external-party-amulet-rules) — verify-before-sign for the
- * `ExternalPartyAmuletRules_CreateTransferCommand` exercise.
- *
- * THREAT MODEL — identical to the cip56 arm above, for the v1 path. The agent
- * asks the relay to PREPARE an `ExternalPartyAmuletRules_CreateTransferCommand`
- * (it creates a `TransferCommand` the facilitator later settles). A compromised
- * relay could prepare a DIFFERENT command — swap the receiver, inflate the
- * amount, redirect the delegate to an attacker who can then steer settlement,
- * or change the sender — and hand back its hash. We decode the prepared bytes
- * with the SAME structural rigor (schema-pinned field numbers, fail-closed on
- * duplicate/multi-member oneofs, parties matched BY TYPE not text) and assert
- * each money-critical field equals CALLER INTENT at its structural position.
- *
- * choiceArgument :: Record {
- *   sender      : Party,         -- MUST == the agent's own party
- *   receiver    : Party,         -- MUST == merchant payTo from the 402
- *   delegate    : Party,         -- MUST == facilitatorParty from the 402 extra
- *   amount      : Numeric,       -- MUST == the required amount
- *   expiresAt   : Time,          -- sanity-checked (present, plausible)
- *   nonce       : Int,           -- sanity-checked (>= 0, matches expected)
- *   description : Optional Text, -- not money-critical (facilitator re-validates)
- *   expectedDso : Party          -- relay-supplied; NOT trusted as a recipient
- * }
- *
- * We extract sender/receiver/delegate by label, else by Daml declaration order
- * (parties[0]/[1]/[2]); amount = the single Numeric leaf; nonce = the single
- * Int64 leaf. Every field read uses the unique accessors so a duplicate/decoy
- * occurrence fails closed rather than diverging from the participant's
- * last-wins parse. The foreign-party backstop allows ONLY {sender, receiver,
- * delegate} plus the expectedDso AT its own position — any other party (an extra
- * leg, a smuggled GenMap recipient) is rejected. expectedDso is relay-supplied,
- * so it is allowed positionally but NEVER used to widen the recipient allowlist.
- * ════════════════════════════════════════════════════════════════════════ */
-/** The create choice on ExternalPartyAmuletRules (v1 / facilitator-pays-gas). */
-const CREATE_TRANSFER_COMMAND_CHOICE = "ExternalPartyAmuletRules_CreateTransferCommand";
-/**
- * Extract the v1 create-command fields from its (flat) choice-argument record,
- * BY TYPE at its DAML DECLARATION-ORDER POSITION (what the participant binds),
- * NOT by label — and fail closed on any label/position divergence (the
- * amount-inflation / receiver-swap vector). Declaration order:
- *   [0] sender:Party [1] receiver:Party [2] delegate:Party [3] amount:Numeric
- *   [4] expiresAt:Time [5] nonce:Int [6] description:Optional Text [7] expectedDso:Party
- * Honest encodings — fully labelled in order OR label-free (normalized) — both
- * pass; a record whose labels disagree with declaration order (a decoy field
- * re-using a money-critical label, or a mislabeled value at a money position) is
- * rejected. Fails closed if a money-critical field is the wrong type / missing.
- */
-export function extractCreateTransferCommand(chosenValue) {
-    const entries = recordEntries(chosenValue);
-    // ── positional reads at Daml declaration order, with label/position guard ──
-    const senderE = entryByDeclOrder(entries, 0, "sender");
-    const receiverE = entryByDeclOrder(entries, 1, "receiver");
-    const delegateE = entryByDeclOrder(entries, 2, "delegate");
-    const amountE = entryByDeclOrder(entries, 3, "amount");
-    const expiresAtE = entryByDeclOrder(entries, 4, "expiresAt");
-    const nonceE = entryByDeclOrder(entries, 5, "nonce");
-    // position 6 = description:Optional Text — not money-critical; skip.
-    const expectedDsoE = entryByDeclOrder(entries, 7, "expectedDso");
-    const sender = senderE ? leafOf(senderE.value) : undefined;
-    const receiver = receiverE ? leafOf(receiverE.value) : undefined;
-    const delegate = delegateE ? leafOf(delegateE.value) : undefined;
-    const amount = amountE ? leafOf(amountE.value) : undefined;
-    const nonce = nonceE ? leafOf(nonceE.value) : undefined;
-    const expiresAt = expiresAtE ? leafOf(expiresAtE.value) : undefined;
-    // expectedDso is relay-supplied; read at its own position for the backstop
-    // exclusion only, NEVER as a recipient allowlist entry. It is `Optional Party`
-    // in the Splice choice (Value.optional → party), so unwrap one Some level —
-    // the bare leafOf would read undefined and reject every honest v1 payment.
-    const expectedDso = expectedDsoE
-        ? optionalPartyLeafOf(expectedDsoE.value)
-        : undefined;
-    if (!sender || sender.kind !== "party") {
-        throw new PreparedDecodeError("CreateTransferCommand.sender is not a party");
-    }
-    if (!receiver || receiver.kind !== "party") {
-        throw new PreparedDecodeError("CreateTransferCommand.receiver is not a party");
-    }
-    if (!delegate || delegate.kind !== "party") {
-        throw new PreparedDecodeError("CreateTransferCommand.delegate is not a party");
-    }
-    if (!amount || amount.kind !== "numeric") {
-        throw new PreparedDecodeError("CreateTransferCommand.amount is not numeric");
-    }
-    if (!nonce || nonce.kind !== "int64") {
-        throw new PreparedDecodeError("CreateTransferCommand.nonce is not an int");
-    }
-    return {
-        sender: sender.value,
-        receiver: receiver.value,
-        delegate: delegate.value,
-        amount: amount.value,
-        nonce: nonce.value,
-        ...(expiresAt && expiresAt.kind === "timestamp"
-            ? { expiresAt: expiresAt.value }
-            : {}),
-        ...(expectedDso && expectedDso.kind === "party"
-            ? { expectedDso: expectedDso.value }
-            : {}),
-    };
-}
-/**
- * Assert the relay-returned `preparedTransaction` encodes EXACTLY the v1
- * `ExternalPartyAmuletRules_CreateTransferCommand` the agent intended. Throws
- * `PreparedTransferMismatchError` on any mismatch and `PreparedDecodeError` if
- * the bytes are not a decodable PreparedTransaction carrying a single
- * create-command exercise. Call BEFORE signing the hash. Fail-closed: anything
- * not positively proven to match the intent throws.
- */
-export function assertPreparedCreateTransferCommandMatches(preparedTransactionB64, expect) {
-    const decoded = decodePrepared(preparedTransactionB64);
-    // Node-traversal invariant (shared with the cip56 arm): exactly one allowed
-    // exercise & no other; EVERY node recognized (no node hidden under an unknown
-    // node version/type — closes the "sibling Create" and "node-version 1001"
-    // bypasses); EXACTLY ONE root that IS the single allowed CreateTransferCommand
-    // exercise; no orphan/extra-leg node. Returns the validated root exercise.
-    const { exercise: ex, rootNodeId } = assertSingleAllowedRootExercise(decoded, CREATE_TRANSFER_COMMAND_CHOICE);
-    const c = extractCreateTransferCommand(ex.chosenValue);
-    const mismatches = [];
-    if (c.sender !== expect.sender) {
-        mismatches.push(`sender (got ${JSON.stringify(c.sender)}, intended ${JSON.stringify(expect.sender)})`);
-    }
-    if (c.receiver !== expect.receiver) {
-        mismatches.push(`receiver (got ${JSON.stringify(c.receiver)}, intended ${JSON.stringify(expect.receiver)})`);
-    }
-    if (c.delegate !== expect.delegate) {
-        mismatches.push(`delegate (got ${JSON.stringify(c.delegate)}, intended ${JSON.stringify(expect.delegate)})`);
-    }
-    if (canonicalAmount(c.amount) !== canonicalAmount(expect.amount)) {
-        mismatches.push(`amount (got ${JSON.stringify(c.amount)}, intended ${JSON.stringify(expect.amount)})`);
-    }
-    if (expect.nonce !== undefined && c.nonce !== expect.nonce) {
-        mismatches.push(`nonce (got ${JSON.stringify(c.nonce)}, intended ${JSON.stringify(expect.nonce)})`);
-    }
-    // Pin the DSO only if the caller supplied an independently-trusted value.
-    if (expect.expectedDso !== undefined && c.expectedDso !== expect.expectedDso) {
-        mismatches.push(`expectedDso (got ${JSON.stringify(c.expectedDso)}, intended ${JSON.stringify(expect.expectedDso)})`);
-    }
-    if (mismatches.length > 0) {
-        throw new PreparedTransferMismatchError(`relay-prepared CreateTransferCommand does not match intent: ` +
-            `${mismatches.join("; ")} — refusing to sign ` +
-            `(possible tampered/compromised relay redirecting funds)`);
-    }
-    // The DSO must never be aliased to a money role — otherwise a relay could set
-    // the (unpinned) expectedDso to the receiver/sender/delegate and have the
-    // backstop exempt a money party. Reject up front.
-    if (c.expectedDso !== undefined &&
-        (c.expectedDso === expect.sender ||
-            c.expectedDso === expect.receiver ||
-            c.expectedDso === expect.delegate)) {
-        throw new PreparedTransferMismatchError(`relay-prepared CreateTransferCommand expectedDso ${JSON.stringify(c.expectedDso)} equals a ` +
-            `command party (sender/receiver/delegate) — refusing to sign`);
-    }
-    // Pin WHICH template + WHICH contract the choice runs against
-    // (template/contract-confusion + resolve→prepare TOCTOU) and the SIGNED
-    // synchronizer + timing metadata (relay-chosen domain / validity window).
-    // No-ops unless the caller supplies the corresponding intent.
-    assertTemplateMatches(ex, expect.templateQualifiedName);
-    assertContractIdMatches(ex, expect.expectedContractId);
-    assertSynchronizerMatches(decoded.synchronizerId, expect.synchronizerId);
-    assertTimingPlausible(decoded, expect.nowMs ?? Date.now());
-    // nonce sanity: a negative nonce is never legitimate (Daml Int can be
-    // negative on the wire, but a TransferCommand nonce is a monotonic counter).
-    let nonceBig;
-    try {
-        nonceBig = BigInt(c.nonce);
-    }
-    catch {
-        throw new PreparedTransferMismatchError(`relay-prepared CreateTransferCommand has a non-integer nonce ` +
-            `${JSON.stringify(c.nonce)} — refusing to sign`);
-    }
-    if (nonceBig < 0n) {
-        throw new PreparedTransferMismatchError(`relay-prepared CreateTransferCommand has a negative nonce ` +
-            `${JSON.stringify(c.nonce)} — refusing to sign`);
-    }
-    // expiresAt sanity (best-effort): when present as a timestamp leaf, reject a
-    // value already in the past — a relay-set expiry that has lapsed would create
-    // a command the facilitator can never settle (and at worst replays a stale
-    // intent). Value.timestamp is microseconds since the Unix epoch.
-    if (c.expiresAt !== undefined) {
-        const nowMs = expect.nowMs ?? Date.now();
-        let expiresMs;
-        try {
-            expiresMs = Number(BigInt(c.expiresAt) / 1000n);
-        }
-        catch {
-            expiresMs = NaN;
-        }
-        if (Number.isFinite(expiresMs) && expiresMs <= nowMs) {
-            throw new PreparedTransferMismatchError(`relay-prepared CreateTransferCommand expiresAt is in the past ` +
-                `(${new Date(expiresMs).toISOString()}) — refusing to sign`);
-        }
-    }
-    // Cross-check the authoritative submitter: REQUIRE a non-empty act_as whose
-    // only party is the sender (closes GAP A3 — an empty act_as no longer skips
-    // this). Placed after the field comparison so a consistent-attacker tx
-    // surfaces as a field mismatch first.
-    assertActAsIsSender(decoded.actAs, expect.sender);
-    // Position-aware foreign-party backstop over the WHOLE signed message (all node
-    // Value payloads + node-level party metadata + Metadata.input_contracts): no
-    // party other than {sender, receiver, delegate} may appear, EXCEPT the
-    // expectedDso (DSO) at its known root position (1). The DSO is value-excluded
-    // OUTSIDE its root position ONLY when pinned to an independently-trusted value
-    // (expect.expectedDso) — so a relay-chosen, unpinned DSO can no longer be
-    // aliased to the attacker and smuggled in as a consequence/metadata recipient.
-    const leaves = collectSplitPartyLeaves(decoded, rootNodeId);
-    assertNoForeignParties(leaves, new Set([expect.sender, expect.receiver, expect.delegate]), c.expectedDso, 1 /* expectedDso */, expect.expectedDso !== undefined /* trusted iff caller pinned it */);
-}
 /* ════════════════════════════════════════════════════════════════════════
  * claim path — verify-before-sign for `TransferInstruction_Accept`.
  *
@@ -2558,261 +2325,6 @@ export function assertPreparedAllocationWithdrawMatches(preparedTransactionB64,
         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