@ftptech/canton-agent-wallet 0.5.0 → 0.6.0

package/dist/verify-prepared.js

@@ -1227,101 +1227,6 @@ 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
@@ -1908,553 +1813,6 @@ 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-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) {