@temple-digital-group/temple-canton-js 2.0.0 → 2.0.1

package/README.md

@@ -109,6 +109,7 @@ const result = await deposit(10, "CC");
 ```
 
 `deposit()` requires the wallet adapter to be connected. It:
+
 1. Checks your CC balance to ensure at least 10 CC is reserved for transaction fees
 2. For utility deposits (USDCx, CBTC), verifies you have enough of the token **and** 10 CC for fees
 3. Selects the right UTXOs from your wallet
@@ -301,10 +302,10 @@ These require an explicit subscribe message. The SDK handles this automatically.
 
 | Function                                    | Channel                          | Example                   |
 | ------------------------------------------- | -------------------------------- | ------------------------- |
-| `subscribeOrderbook(symbol, cb)`            | `orderbook:{symbol}`             | `orderbook:Amulet/USDCx` |
-| `subscribeTrades(symbol, cb)`               | `trades:{symbol}`                | `trades:Amulet/USDCx`    |
-| `subscribeTicker(symbol, cb)`               | `ticker:{symbol}`                | `ticker:CBTC/USDCx`      |
-| `subscribeCandles(symbol, granularity, cb)` | `candles:{symbol}:{granularity}` | `candles:Amulet/USDCx:60`|
+| `subscribeOrderbook(symbol, cb)`            | `orderbook:{symbol}`             | `orderbook:Amulet/USDCx`  |
+| `subscribeTrades(symbol, cb)`               | `trades:{symbol}`                | `trades:Amulet/USDCx`     |
+| `subscribeTicker(symbol, cb)`               | `ticker:{symbol}`                | `ticker:CBTC/USDCx`       |
+| `subscribeCandles(symbol, granularity, cb)` | `candles:{symbol}:{granularity}` | `candles:Amulet/USDCx:60` |
 | `subscribeOracle(symbol, cb)`               | `oracle:{symbol}`                | `oracle:cc`               |
 | `subscribeOracleVolume(symbol, cb)`         | `oracle_volume:{symbol}`         | `oracle_volume:cc`        |
 
@@ -314,11 +315,11 @@ These require an explicit subscribe message. The SDK handles this automatically.
 
 Pushed automatically by the server after authentication. No subscribe message is sent — you just register a local handler. Requires `API_KEY` (Node.js) or cookie auth (browser).
 
-| Function                   | Server Event   | Description                                        |
-| -------------------------- | -------------- | -------------------------------------------------- |
-| `subscribeUserOrders(cb)`  | `user_order`   | Order lifecycle updates (created, filled, cancelled)|
-| `subscribeUserTrades(cb)`  | `user_trade`   | Trade fill confirmations                           |
-| `subscribeUserBalances(cb)`| `user_balance` | Balance changes                                    |
+| Function                    | Server Event   | Description                                          |
+| --------------------------- | -------------- | ---------------------------------------------------- |
+| `subscribeUserOrders(cb)`   | `user_order`   | Order lifecycle updates (created, filled, cancelled) |
+| `subscribeUserTrades(cb)`   | `user_trade`   | Trade fill confirmations                             |
+| `subscribeUserBalances(cb)` | `user_balance` | Balance changes                                      |
 
 ### Advanced Usage
 
@@ -370,13 +371,13 @@ const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
 
 ### Deposits & Withdrawals
 
-| Function                                  | Provider | Description                                           |
-| ----------------------------------------- | -------- | ----------------------------------------------------- |
+| Function                                  | Provider | Description                                                |
+| ----------------------------------------- | -------- | ---------------------------------------------------------- |
 | `deposit(amount, symbol)`                 | **W**    | Deposit funds (validates balance, reserves 10 CC for fees) |
-| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount (low-level)     |
-| `depositFunds(opts)`                      | **W**    | Submit deposit allocation (low-level)                 |
-| `withdrawFunds({ asset_id, amount })`     | **W**    | Withdraw available trading balance back to wallet     |
-| `emergencyWithdrawFunds(opts)`            | **W**    | Cancel all orders and withdraw everything immediately |
+| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount (low-level)          |
+| `depositFunds(opts)`                      | **W**    | Submit deposit allocation (low-level)                      |
+| `withdrawFunds({ asset_id, amount })`     | **W**    | Withdraw available trading balance back to wallet          |
+| `bulkWithdrawFunds(opts)`                 | **W**    | Cancel all orders and withdraw everything immediately      |
 
 ### Holdings
 
@@ -418,13 +419,13 @@ const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
 
 #### Trading
 
-| Function                            | Description                                            |
-| ----------------------------------- | ------------------------------------------------------ |
-| `createOrderRequest(opts)`          | Place a buy/sell order via the trading backend          |
-| `cancelOrder(orderId)`              | Cancel a specific order                                |
-| `cancelAllOrders(options?)`         | Cancel all orders (options: `symbol` filter)            |
-| `getTradingBalance()`               | Get user's trading balance (unlocked/locked/in-flight)  |
-| `getActiveOrders(options?)`         | Get active orders (options: `symbol`, `limit`)          |
+| Function                    | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `createOrderRequest(opts)`  | Place a buy/sell order via the trading backend         |
+| `cancelOrder(orderId)`      | Cancel a specific order                                |
+| `cancelAllOrders(options?)` | Cancel all orders (options: `symbol` filter)           |
+| `getTradingBalance()`       | Get user's trading balance (unlocked/locked/in-flight) |
+| `getActiveOrders(options?)` | Get active orders (options: `symbol`, `limit`)         |
 
 #### Withdrawals
 
@@ -435,23 +436,20 @@ const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
 
 #### Disclosures & Delegation
 
-| Function                  | Description                                                                  |
-| ------------------------- | ---------------------------------------------------------------------------- |
-| `getDisclosures(partyId)` | Get Amulet disclosure data (factory ID, choice context, disclosed contracts) |
-| `getDelegation()`         | Get the user's delegation contract from the API                              |
+| Function           | Description                                                                  |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `getDisclosures()` | Get Amulet disclosure data (factory ID, choice context, disclosed contracts) |
+| `getDelegation()`  | Get the user's delegation contract from the API                              |
 
 ### WebSocket
 
-| Function                                    | Description                                                    |
-| ------------------------------------------- | -------------------------------------------------------------- |
-| `createWebSocket()`                         | Get or create the shared WS instance (auto-connects)           |
-| `disconnectWebSocket()`                     | Disconnect and destroy the shared WS instance                  |
-| `subscribeOrderbook(symbol, cb)`            | Subscribe to orderbook updates                                 |
-| `subscribeTrades(symbol, cb)`               | Subscribe to trade updates                                     |
-| `subscribeTicker(symbol, cb)`               | Subscribe to ticker updates                                    |
-| `subscribeCandles(symbol, granularity, cb)` | Subscribe to candle updates                                    |
-| `subscribeOracle(symbol, cb)`               | Subscribe to oracle price updates                              |
-| `subscribeOracleVolume(symbol, cb)`         | Subscribe to oracle volume updates                             |
-| `subscribeUserOrders(cb)`                   | Listen to user order events (auto-pushed, no subscribe needed) |
-| `subscribeUserTrades(cb)`                   | Listen to user trade events (auto-pushed, no subscribe needed) |
-| `subscribeUserBalances(cb)`                 | Listen to user balance events (auto-pushed, no subscribe needed)|
+| Function                                    | Description                                          |
+| ------------------------------------------- | ---------------------------------------------------- |
+| `createWebSocket()`                         | Get or create the shared WS instance (auto-connects) |
+| `disconnectWebSocket()`                     | Disconnect and destroy the shared WS instance        |
+| `subscribeOrderbook(symbol, cb)`            | Subscribe to orderbook updates                       |
+| `subscribeTrades(symbol, cb)`               | Subscribe to trade updates                           |
+| `subscribeTicker(symbol, cb)`               | Subscribe to ticker updates                          |
+| `subscribeCandles(symbol, granularity, cb)` | Subscribe to candle updates                          |
+| `subscribeOracle(symbol, cb)`               | Subscribe to oracle price updates                    |
+| `subscribeOracleVolume(symbol, cb)`         | Subscribe to oracle volume updates                   |

package/dist/canton/withdrawals.d.ts

@@ -17,6 +17,13 @@ export interface FinalizeWithdrawOpts {
     };
     userId?: string;
 }
+export interface BulkWithdrawFundsOpts {
+    allocationIds: string[];
+    sender?: string;
+    assetId: string;
+    disclosures?: FinalizeWithdrawOpts["disclosures"];
+    userId?: string;
+}
 export interface WithdrawFundsOpts {
     asset_id: string;
     amount: string | number;
@@ -32,6 +39,19 @@ export interface WithdrawFundsOpts {
  * 3. Remote: Scan API / Registry API
  */
 export declare function finalizeWithdrawFunds(opts: FinalizeWithdrawOpts, returnCommand?: boolean): Promise<Record<string, unknown>>;
+/**
+ * Finalize multiple withdrawals in a single signed transaction.
+ *
+ * Bundles N Allocation_Withdraw exercises into one ledger submission so the user
+ * signs once for the whole batch. All allocations must belong to the same sender
+ * and the same asset (caller's responsibility — pass one assetId).
+ *
+ * Choice-context fetching:
+ * - Localhost ledger / Amulet via /api/amulet/disclosures: one shared context for all N.
+ * - Scan API (Amulet) / Registry API (utility): one fetch per allocation, then disclosed
+ *   contracts merged and deduped.
+ */
+export declare function bulkWithdrawFunds(opts: BulkWithdrawFundsOpts, returnCommand?: boolean): Promise<Record<string, unknown>>;
 /**
  * High-level withdrawal flow:
  * 1. Creates a withdrawal request via the backend API.

package/dist/canton/withdrawals.js

@@ -258,6 +258,271 @@ export async function finalizeWithdrawFunds(opts, returnCommand = false) {
         return { error: msg };
     }
 }
+/**
+ * Finalize multiple withdrawals in a single signed transaction.
+ *
+ * Bundles N Allocation_Withdraw exercises into one ledger submission so the user
+ * signs once for the whole batch. All allocations must belong to the same sender
+ * and the same asset (caller's responsibility — pass one assetId).
+ *
+ * Choice-context fetching:
+ * - Localhost ledger / Amulet via /api/amulet/disclosures: one shared context for all N.
+ * - Scan API (Amulet) / Registry API (utility): one fetch per allocation, then disclosed
+ *   contracts merged and deduped.
+ */
+export async function bulkWithdrawFunds(opts, returnCommand = false) {
+    const { allocationIds, sender: senderOpt, assetId: rawAssetId, disclosures, userId } = opts;
+    const assetId = normalizeAssetId(rawAssetId);
+    const sender = getAdapterPartyId() ?? senderOpt ?? config.VALIDATOR_USER_PARTY_ID;
+    if (!Array.isArray(allocationIds) || allocationIds.length === 0) {
+        const msg = "bulkWithdrawFunds: allocationIds must be a non-empty array";
+        console.error(msg);
+        return { error: msg };
+    }
+    if (!sender || !assetId) {
+        const msg = "bulkWithdrawFunds: sender and assetId are required";
+        console.error(msg);
+        return { error: msg };
+    }
+    const isAmulet = assetId === "Amulet";
+    const allocationCids = allocationIds.map((cid) => normalizeContractId(cid));
+    // Per-allocation choice context (one entry per allocation, in the same order).
+    // Shared-context paths fill all N entries with the same object.
+    let perAllocContexts = [];
+    let mergedDisclosedContracts = [];
+    if (shouldUseLedgerForMetadata()) {
+        // Localhost: resolve once, reuse for all allocations.
+        let sharedContext = {};
+        const sharedDisclosed = [];
+        if (isAmulet) {
+            const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
+            if (!amuletCtx) {
+                const msg = "bulkWithdrawFunds: failed to resolve Amulet context from ledger";
+                console.error(msg);
+                return { error: msg };
+            }
+            const ctx = amuletCtx;
+            const contextKeys = ctx.contextKeys;
+            const amuletRules = ctx.amuletRules;
+            const openMiningRound = ctx.openMiningRound;
+            const featuredAppRight = ctx.featuredAppRight;
+            const externalAmuletRules = ctx.externalAmuletRules;
+            sharedContext = {
+                values: {
+                    [contextKeys.amuletRules]: { tag: "AV_ContractId", value: amuletRules.contractCid },
+                    [contextKeys.openRound]: { tag: "AV_ContractId", value: openMiningRound.contractCid },
+                    [contextKeys.featuredAppRight]: { tag: "AV_ContractId", value: featuredAppRight.contractCid },
+                    [contextKeys.expireLock]: { tag: "AV_Bool", value: true },
+                },
+            };
+            sharedDisclosed.push({
+                templateId: amuletRules.templateId ?? null,
+                contractId: amuletRules.contractCid,
+                createdEventBlob: amuletRules.disclosureCid,
+                synchronizerId: amuletRules.synchronizerId,
+            }, {
+                templateId: openMiningRound.templateId ?? null,
+                contractId: openMiningRound.contractCid,
+                createdEventBlob: openMiningRound.disclosureCid,
+                synchronizerId: openMiningRound.synchronizerId,
+            }, {
+                templateId: externalAmuletRules.templateId ?? null,
+                contractId: externalAmuletRules.contractCid,
+                createdEventBlob: externalAmuletRules.disclosureCid,
+                synchronizerId: externalAmuletRules.synchronizerId,
+            });
+            if (featuredAppRight?.contractCid && featuredAppRight?.disclosureCid) {
+                sharedDisclosed.push({
+                    templateId: featuredAppRight.templateId ?? null,
+                    contractId: featuredAppRight.contractCid,
+                    createdEventBlob: featuredAppRight.disclosureCid,
+                    synchronizerId: featuredAppRight.synchronizerId,
+                });
+            }
+        }
+        else {
+            const instrumentDef = resolveInstrumentDefinition(assetId);
+            const networkDef = instrumentDef?.[config.NETWORK];
+            const registrar = networkDef?.registrar || getInstrumentRegistrar(assetId) || config.VALIDATOR_REGISTRAR_PARTY_ID;
+            const [allocFactory, instConfig] = await Promise.all([
+                resolveUtilityAllocationFactory(registrar, sender),
+                resolveUtilityInstrumentConfiguration(assetId, registrar),
+            ]);
+            if (instConfig) {
+                sharedContext = {
+                    values: {
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfiguration]: {
+                            tag: "AV_ContractId",
+                            value: instConfig.contractCid,
+                        },
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfigurationPrefixed]: {
+                            tag: "AV_ContractId",
+                            value: instConfig.contractCid,
+                        },
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentials]: { tag: "AV_List", value: [] },
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentialsPrefixed]: { tag: "AV_List", value: [] },
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentials]: { tag: "AV_List", value: [] },
+                        [DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentialsPrefixed]: { tag: "AV_List", value: [] },
+                        [DEFAULT_AMULET_CONTEXT_KEYS.expireLock]: { tag: "AV_Bool", value: true },
+                    },
+                };
+                sharedDisclosed.push({
+                    templateId: null,
+                    contractId: instConfig.contractCid,
+                    createdEventBlob: instConfig.disclosureCid,
+                    synchronizerId: instConfig.synchronizerId,
+                });
+            }
+            if (allocFactory) {
+                sharedDisclosed.push({
+                    templateId: null,
+                    contractId: allocFactory.contractCid,
+                    createdEventBlob: allocFactory.disclosureCid,
+                    synchronizerId: allocFactory.synchronizerId,
+                });
+            }
+        }
+        perAllocContexts = allocationCids.map(() => sharedContext);
+        mergedDisclosedContracts = sharedDisclosed;
+    }
+    else if (isAmulet && !config.VALIDATOR_SCAN_API_URL) {
+        // Amulet via /api/amulet/disclosures: one fetch shared across all allocations.
+        const factoryData = disclosures?.disclosures || disclosures || null;
+        let resolvedData = factoryData;
+        if (!resolvedData?.choiceContext) {
+            const disclosuresResult = (await getDisclosures(sender));
+            resolvedData = disclosuresResult?.disclosures;
+            if (disclosuresResult?.error || !resolvedData?.choiceContext) {
+                const detail = disclosuresResult?.message ||
+                    disclosuresResult?.error ||
+                    "missing choiceContext in response";
+                const msg = `bulkWithdrawFunds: failed to resolve Amulet disclosures: ${detail}`;
+                console.error(msg);
+                return { error: msg };
+            }
+        }
+        const choiceContext = resolvedData.choiceContext;
+        const sharedContext = choiceContext.choiceContextData || {};
+        const values = sharedContext.values;
+        if (values && !values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]) {
+            values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock] = { tag: "AV_Bool", value: true };
+        }
+        const sharedDisclosed = (choiceContext.disclosedContracts || []).map((dc) => ({
+            templateId: dc.templateId,
+            contractId: dc.contractId,
+            createdEventBlob: dc.createdEventBlob,
+            synchronizerId: dc.synchronizerId,
+        }));
+        perAllocContexts = allocationCids.map(() => sharedContext);
+        mergedDisclosedContracts = sharedDisclosed;
+    }
+    else {
+        // Per-allocation context: Scan API (Amulet) or Registry API (utility).
+        let baseUrl;
+        let contextHeaders = {};
+        if (isAmulet) {
+            if (!config.VALIDATOR_SCAN_API_URL) {
+                const msg = "bulkWithdrawFunds: VALIDATOR_SCAN_API_URL is required for Amulet allocations";
+                console.error(msg);
+                return { error: msg };
+            }
+            baseUrl = `${config.VALIDATOR_SCAN_API_URL}/registry`;
+            contextHeaders = await buildHeaders();
+        }
+        else {
+            const instrumentDef = resolveInstrumentDefinition(assetId);
+            const networkContracts = instrumentDef?.[config.NETWORK];
+            const registryAPI = networkContracts?.registryAPI;
+            if (!registryAPI) {
+                const msg = `bulkWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
+                console.error(msg);
+                return { error: msg };
+            }
+            baseUrl = registryAPI;
+        }
+        const requestConfig = Object.keys(contextHeaders).length > 0 ? { headers: contextHeaders } : undefined;
+        try {
+            const contextResults = await Promise.all(allocationCids.map(async (cid) => {
+                const url = `${baseUrl}/allocations/v1/${encodeURIComponent(cid)}/choice-contexts/withdraw`;
+                try {
+                    const resp = await axios.post(url, { meta: {}, excludeDebugFields: true }, requestConfig);
+                    return resp.data;
+                }
+                catch (error) {
+                    const axiosErr = error;
+                    const detail = axiosErr.response?.data ? JSON.stringify(axiosErr.response.data) : axiosErr.message;
+                    throw new Error(`bulkWithdrawFunds: error fetching withdraw context for ${cid} from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`);
+                }
+            }));
+            for (const data of contextResults) {
+                perAllocContexts.push(data?.choiceContextData || {});
+                const disclosed = (data?.disclosedContracts || []).map((dc) => ({
+                    templateId: dc.templateId,
+                    contractId: dc.contractId,
+                    createdEventBlob: dc.createdEventBlob,
+                    synchronizerId: dc.synchronizerId,
+                }));
+                mergedDisclosedContracts.push(...disclosed);
+            }
+        }
+        catch (error) {
+            const msg = error.message;
+            console.error(msg);
+            return { error: msg };
+        }
+    }
+    // Build one ExerciseCommand per allocation; Canton signs the whole submission atomically.
+    const exerciseCommands = allocationCids.map((cid, idx) => ({
+        ExerciseCommand: {
+            templateId: "#splice-api-token-allocation-v1:Splice.Api.Token.AllocationV1:Allocation",
+            contractId: cid,
+            choice: "Allocation_Withdraw",
+            choiceArgument: {
+                extraArgs: {
+                    context: perAllocContexts[idx],
+                    meta: { values: {} },
+                },
+            },
+        },
+    }));
+    const command = {
+        commands: exerciseCommands,
+        commandId: randomUUID(),
+        userId: userId || getUserId() || config.AUTH0_USER_ID || "temple",
+        applicationId: "temple",
+        actAs: [sender],
+        disclosedContracts: mergedDisclosedContracts,
+    };
+    dedupeDisclosedContracts(command);
+    const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
+    if (returnCommand) {
+        return { command, endpoint };
+    }
+    if (getWalletAdapter()) {
+        try {
+            await payDueGasIfAny();
+            return (await submitCommand(command));
+        }
+        catch (error) {
+            const msg = `bulkWithdrawFunds: wallet adapter submission failed: ${error.message}`;
+            console.error(msg);
+            return { error: msg };
+        }
+    }
+    const headers = await buildHeaders();
+    try {
+        const response = await axios.post(endpoint, command, { headers });
+        return response.data;
+    }
+    catch (error) {
+        const axiosErr = error;
+        const errorData = axiosErr?.response?.data;
+        const errorDetail = errorData ? JSON.stringify(errorData, null, 2) : axiosErr.message;
+        const msg = `bulkWithdrawFunds: error submitting command: ${errorDetail}`;
+        console.error(msg);
+        return { error: msg };
+    }
+}
 /**
  * High-level withdrawal flow:
  * 1. Creates a withdrawal request via the backend API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temple-digital-group/temple-canton-js",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "JavaScript library for interacting with Temple Canton blockchain",
   "type": "module",
   "main": "index.js",

package/src/canton/index.js

@@ -2645,185 +2645,6 @@ export { deposit, prepareDepositHoldings, depositFunds } from "../../dist/canton
 // Withdrawal functions moved to src/canton/withdrawals.ts
 export { finalizeWithdrawFunds, withdrawFunds, withdrawDelegation } from "../../dist/canton/withdrawals.js";
 
-// ─── Emergency Allocation Withdraw ──────────────────────────────────────────
-
-export async function buildAllocationWithdrawCommand(opts) {
-	const { disclosures, userId } = opts || {};
-	const assetId = normalizeAssetId(opts.assetId);
-	const sender = getAdapterPartyId() || opts.sender || config.VALIDATOR_USER_PARTY_ID;
-
-	if (!opts.allocationCids || !sender || !assetId) {
-		return { error: "buildAllocationWithdrawCommand: allocationCids, sender, and assetId are required" };
-	}
-
-	const cids = Array.isArray(opts.allocationCids) ? opts.allocationCids : [opts.allocationCids];
-	if (cids.length === 0) {
-		return { error: "buildAllocationWithdrawCommand: allocationCids must not be empty" };
-	}
-
-	const isAmulet = assetId === "Amulet";
-
-	// --- Resolve context and disclosures (once for all CIDs) ---
-	let choiceContextData = {};
-	let disclosedContracts = [];
-
-	if (shouldUseLedgerForMetadata()) {
-		if (isAmulet) {
-			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
-			if (!amuletCtx) {
-				return { error: "buildAllocationWithdrawCommand: failed to resolve Amulet context from ledger" };
-			}
-			const contextKeys = amuletCtx.contextKeys;
-			choiceContextData = {
-				values: {
-					[contextKeys.amuletRules]: { tag: "AV_ContractId", value: amuletCtx.amuletRules.contractCid },
-					[contextKeys.openRound]: { tag: "AV_ContractId", value: amuletCtx.openMiningRound.contractCid },
-					[contextKeys.featuredAppRight]: { tag: "AV_ContractId", value: amuletCtx.featuredAppRight.contractCid },
-					[contextKeys.expireLock]: { tag: "AV_Bool", value: true },
-				},
-			};
-			disclosedContracts = [
-				{ templateId: amuletCtx.amuletRules.templateId || null, contractId: amuletCtx.amuletRules.contractCid, createdEventBlob: amuletCtx.amuletRules.disclosureCid, synchronizerId: amuletCtx.amuletRules.synchronizerId },
-				{ templateId: amuletCtx.openMiningRound.templateId || null, contractId: amuletCtx.openMiningRound.contractCid, createdEventBlob: amuletCtx.openMiningRound.disclosureCid, synchronizerId: amuletCtx.openMiningRound.synchronizerId },
-				{ templateId: amuletCtx.externalAmuletRules.templateId || null, contractId: amuletCtx.externalAmuletRules.contractCid, createdEventBlob: amuletCtx.externalAmuletRules.disclosureCid, synchronizerId: amuletCtx.externalAmuletRules.synchronizerId },
-			];
-			if (amuletCtx.featuredAppRight?.contractCid && amuletCtx.featuredAppRight?.disclosureCid) {
-				disclosedContracts.push({ templateId: amuletCtx.featuredAppRight.templateId || null, contractId: amuletCtx.featuredAppRight.contractCid, createdEventBlob: amuletCtx.featuredAppRight.disclosureCid, synchronizerId: amuletCtx.featuredAppRight.synchronizerId });
-			}
-		} else {
-			const instrumentDef = resolveInstrumentDefinition(assetId);
-			const networkDef = instrumentDef?.[config.NETWORK];
-			const registrar = networkDef?.registrar || getInstrumentRegistrar(assetId) || config.VALIDATOR_REGISTRAR_PARTY_ID;
-			const [allocFactory, instConfig] = await Promise.all([
-				resolveUtilityAllocationFactory(registrar, sender),
-				resolveUtilityInstrumentConfiguration(assetId, registrar),
-			]);
-			if (instConfig) {
-				choiceContextData = {
-					values: {
-						[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfiguration]: { tag: "AV_ContractId", value: instConfig.contractCid },
-						[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfigurationPrefixed]: { tag: "AV_ContractId", value: instConfig.contractCid },
-						[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentials]: { tag: "AV_List", value: [] },
-						[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentialsPrefixed]: { tag: "AV_List", value: [] },
-						[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentials]: { tag: "AV_List", value: [] },
-						[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentialsPrefixed]: { tag: "AV_List", value: [] },
-						[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]: { tag: "AV_Bool", value: true },
-					},
-				};
-				disclosedContracts.push({ templateId: null, contractId: instConfig.contractCid, createdEventBlob: instConfig.disclosureCid, synchronizerId: instConfig.synchronizerId });
-			}
-			if (allocFactory) {
-				disclosedContracts.push({ templateId: null, contractId: allocFactory.contractCid, createdEventBlob: allocFactory.disclosureCid, synchronizerId: allocFactory.synchronizerId });
-			}
-		}
-	} else if (isAmulet) {
-		// Resolve via disclosures API
-		let resolvedData = disclosures?.disclosures || disclosures || null;
-		if (!resolvedData?.choiceContext) {
-			const disclosuresResult = await getDisclosures(sender);
-			resolvedData = disclosuresResult?.disclosures;
-			if (disclosuresResult?.error || !resolvedData?.choiceContext) {
-				return { error: `buildAllocationWithdrawCommand: failed to resolve Amulet disclosures: ${disclosuresResult?.message || disclosuresResult?.error || "missing choiceContext"}` };
-			}
-		}
-		choiceContextData = resolvedData.choiceContext.choiceContextData || {};
-		const values = choiceContextData.values;
-		if (values && !values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]) {
-			values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock] = { tag: "AV_Bool", value: true };
-		}
-		disclosedContracts = (resolvedData.choiceContext.disclosedContracts || []).map(dc => ({
-			templateId: dc.templateId, contractId: dc.contractId, createdEventBlob: dc.createdEventBlob, synchronizerId: dc.synchronizerId,
-		}));
-	} else {
-		// Utility: build context from catalog data (no ledger/validator access needed)
-		const instrumentDef = resolveInstrumentDefinition(assetId);
-		const networkContracts = instrumentDef?.[config.NETWORK];
-		if (!networkContracts) {
-			return { error: `buildAllocationWithdrawCommand: no ${config.NETWORK} config for ${assetId} in instrument catalog` };
-		}
-		const instConfig = networkContracts.instrumentConfiguration;
-		const allocFactory = networkContracts.allocationFactory;
-		const synchronizerId = networkContracts.synchronizerId;
-
-		if (!instConfig?.contractId || !instConfig?.eventBlob) {
-			return { error: `buildAllocationWithdrawCommand: instrumentConfiguration missing for ${assetId} on ${config.NETWORK}` };
-		}
-
-		choiceContextData = {
-			values: {
-				[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfiguration]: { tag: "AV_ContractId", value: instConfig.contractId },
-				[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfigurationPrefixed]: { tag: "AV_ContractId", value: instConfig.contractId },
-				[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentials]: { tag: "AV_List", value: [] },
-				[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentialsPrefixed]: { tag: "AV_List", value: [] },
-				[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentials]: { tag: "AV_List", value: [] },
-				[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentialsPrefixed]: { tag: "AV_List", value: [] },
-				[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]: { tag: "AV_Bool", value: true },
-			},
-		};
-		disclosedContracts.push({
-			templateId: instConfig.templateId || null,
-			contractId: instConfig.contractId,
-			createdEventBlob: instConfig.eventBlob,
-			synchronizerId: synchronizerId,
-		});
-		if (allocFactory?.contractId && allocFactory?.eventBlob) {
-			disclosedContracts.push({
-				templateId: allocFactory.templateId || null,
-				contractId: allocFactory.contractId,
-				createdEventBlob: allocFactory.eventBlob,
-				synchronizerId: synchronizerId,
-			});
-		}
-	}
-
-	// --- Build one command per allocation CID ---
-	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
-	const commands = cids.map(cid => {
-		const allocationCid = normalizeContractId(cid);
-		const command = {
-			commands: [{
-				ExerciseCommand: {
-					templateId: "#splice-api-token-allocation-v1:Splice.Api.Token.AllocationV1:Allocation",
-					contractId: allocationCid,
-					choice: "Allocation_Withdraw",
-					choiceArgument: {
-						extraArgs: {
-							context: choiceContextData,
-							meta: { values: {} },
-						},
-					},
-				},
-			}],
-			commandId: randomUUID(),
-			userId: userId || getUserId() || config.AUTH0_USER_ID || "temple",
-			applicationId: "temple",
-			actAs: [sender],
-			disclosedContracts: [...disclosedContracts],
-		};
-		dedupeDisclosedContracts(command);
-		return { command, endpoint };
-	});
-
-	// Auto-submit via wallet adapter if submit option is true
-	if (opts.submit && getWalletAdapter()) {
-		const results = [];
-		for (const { command } of commands) {
-			try {
-				const txResult = await submitCommand(command);
-				results.push({ success: true, commandId: command.commandId, result: txResult });
-			} catch (error) {
-				results.push({ success: false, commandId: command.commandId, error: error.message });
-			}
-		}
-		return { commands, results };
-	}
-
-	if (opts.submit && !getWalletAdapter()) {
-		return { error: "buildAllocationWithdrawCommand: submit requires a wallet adapter. Call setWalletAdapter() first." };
-	}
-
-	return { commands };
-}
 
 // ─── Onboarding & Delegation ─────────────────────────────────────────────────
 

package/src/canton/withdrawals.ts

@@ -54,6 +54,14 @@ export interface FinalizeWithdrawOpts {
 	userId?: string;
 }
 
+export interface BulkWithdrawFundsOpts {
+	allocationIds: string[];
+	sender?: string;
+	assetId: string;
+	disclosures?: FinalizeWithdrawOpts["disclosures"];
+	userId?: string;
+}
+
 export interface WithdrawFundsOpts {
 	asset_id: string;
 	amount: string | number;
@@ -332,6 +340,297 @@ export async function finalizeWithdrawFunds(
 	}
 }
 
+/**
+ * Finalize multiple withdrawals in a single signed transaction.
+ *
+ * Bundles N Allocation_Withdraw exercises into one ledger submission so the user
+ * signs once for the whole batch. All allocations must belong to the same sender
+ * and the same asset (caller's responsibility — pass one assetId).
+ *
+ * Choice-context fetching:
+ * - Localhost ledger / Amulet via /api/amulet/disclosures: one shared context for all N.
+ * - Scan API (Amulet) / Registry API (utility): one fetch per allocation, then disclosed
+ *   contracts merged and deduped.
+ */
+export async function bulkWithdrawFunds(
+	opts: BulkWithdrawFundsOpts,
+	returnCommand = false,
+): Promise<Record<string, unknown>> {
+	const { allocationIds, sender: senderOpt, assetId: rawAssetId, disclosures, userId } = opts;
+	const assetId = normalizeAssetId(rawAssetId);
+	const sender = getAdapterPartyId() ?? senderOpt ?? config.VALIDATOR_USER_PARTY_ID;
+
+	if (!Array.isArray(allocationIds) || allocationIds.length === 0) {
+		const msg = "bulkWithdrawFunds: allocationIds must be a non-empty array";
+		console.error(msg);
+		return { error: msg };
+	}
+	if (!sender || !assetId) {
+		const msg = "bulkWithdrawFunds: sender and assetId are required";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	const isAmulet = assetId === "Amulet";
+	const allocationCids = allocationIds.map((cid) => normalizeContractId(cid) as string);
+
+	// Per-allocation choice context (one entry per allocation, in the same order).
+	// Shared-context paths fill all N entries with the same object.
+	let perAllocContexts: Record<string, unknown>[] = [];
+	let mergedDisclosedContracts: DisclosedContract[] = [];
+
+	if (shouldUseLedgerForMetadata()) {
+		// Localhost: resolve once, reuse for all allocations.
+		let sharedContext: Record<string, unknown> = {};
+		const sharedDisclosed: DisclosedContract[] = [];
+
+		if (isAmulet) {
+			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
+			if (!amuletCtx) {
+				const msg = "bulkWithdrawFunds: failed to resolve Amulet context from ledger";
+				console.error(msg);
+				return { error: msg };
+			}
+			const ctx = amuletCtx as Record<string, unknown>;
+			const contextKeys = ctx.contextKeys as Record<string, string>;
+			const amuletRules = ctx.amuletRules as ContractMetadata;
+			const openMiningRound = ctx.openMiningRound as ContractMetadata;
+			const featuredAppRight = ctx.featuredAppRight as ContractMetadata;
+			const externalAmuletRules = ctx.externalAmuletRules as ContractMetadata;
+
+			sharedContext = {
+				values: {
+					[contextKeys.amuletRules]: { tag: "AV_ContractId", value: amuletRules.contractCid },
+					[contextKeys.openRound]: { tag: "AV_ContractId", value: openMiningRound.contractCid },
+					[contextKeys.featuredAppRight]: { tag: "AV_ContractId", value: featuredAppRight.contractCid },
+					[contextKeys.expireLock]: { tag: "AV_Bool", value: true },
+				},
+			};
+			sharedDisclosed.push(
+				{
+					templateId: amuletRules.templateId ?? null,
+					contractId: amuletRules.contractCid,
+					createdEventBlob: amuletRules.disclosureCid,
+					synchronizerId: amuletRules.synchronizerId,
+				},
+				{
+					templateId: openMiningRound.templateId ?? null,
+					contractId: openMiningRound.contractCid,
+					createdEventBlob: openMiningRound.disclosureCid,
+					synchronizerId: openMiningRound.synchronizerId,
+				},
+				{
+					templateId: externalAmuletRules.templateId ?? null,
+					contractId: externalAmuletRules.contractCid,
+					createdEventBlob: externalAmuletRules.disclosureCid,
+					synchronizerId: externalAmuletRules.synchronizerId,
+				},
+			);
+			if (featuredAppRight?.contractCid && featuredAppRight?.disclosureCid) {
+				sharedDisclosed.push({
+					templateId: featuredAppRight.templateId ?? null,
+					contractId: featuredAppRight.contractCid,
+					createdEventBlob: featuredAppRight.disclosureCid,
+					synchronizerId: featuredAppRight.synchronizerId,
+				});
+			}
+		} else {
+			const instrumentDef = resolveInstrumentDefinition(assetId);
+			const networkDef = instrumentDef?.[config.NETWORK] as Record<string, unknown> | undefined;
+			const registrar =
+				(networkDef?.registrar as string) || getInstrumentRegistrar(assetId) || config.VALIDATOR_REGISTRAR_PARTY_ID;
+			const [allocFactory, instConfig] = await Promise.all([
+				resolveUtilityAllocationFactory(registrar, sender),
+				resolveUtilityInstrumentConfiguration(assetId, registrar),
+			]);
+			if (instConfig) {
+				sharedContext = {
+					values: {
+						[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfiguration]: {
+							tag: "AV_ContractId",
+							value: instConfig.contractCid,
+						},
+						[DEFAULT_UTILITY_CONTEXT_KEYS.instrumentConfigurationPrefixed]: {
+							tag: "AV_ContractId",
+							value: instConfig.contractCid,
+						},
+						[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentials]: { tag: "AV_List", value: [] },
+						[DEFAULT_UTILITY_CONTEXT_KEYS.senderCredentialsPrefixed]: { tag: "AV_List", value: [] },
+						[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentials]: { tag: "AV_List", value: [] },
+						[DEFAULT_UTILITY_CONTEXT_KEYS.receiverCredentialsPrefixed]: { tag: "AV_List", value: [] },
+						[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]: { tag: "AV_Bool", value: true },
+					},
+				};
+				sharedDisclosed.push({
+					templateId: null,
+					contractId: instConfig.contractCid,
+					createdEventBlob: instConfig.disclosureCid,
+					synchronizerId: instConfig.synchronizerId,
+				});
+			}
+			if (allocFactory) {
+				sharedDisclosed.push({
+					templateId: null,
+					contractId: allocFactory.contractCid,
+					createdEventBlob: allocFactory.disclosureCid,
+					synchronizerId: allocFactory.synchronizerId,
+				});
+			}
+		}
+
+		perAllocContexts = allocationCids.map(() => sharedContext);
+		mergedDisclosedContracts = sharedDisclosed;
+	} else if (isAmulet && !config.VALIDATOR_SCAN_API_URL) {
+		// Amulet via /api/amulet/disclosures: one fetch shared across all allocations.
+		const factoryData = (disclosures as Record<string, unknown>)?.disclosures || disclosures || null;
+		let resolvedData = factoryData as Record<string, unknown> | null;
+
+		if (!resolvedData?.choiceContext) {
+			const disclosuresResult = (await getDisclosures(sender)) as unknown as Record<string, unknown>;
+			resolvedData = disclosuresResult?.disclosures as Record<string, unknown>;
+			if (disclosuresResult?.error || !resolvedData?.choiceContext) {
+				const detail =
+					(disclosuresResult?.message as string) ||
+					(disclosuresResult?.error as string) ||
+					"missing choiceContext in response";
+				const msg = `bulkWithdrawFunds: failed to resolve Amulet disclosures: ${detail}`;
+				console.error(msg);
+				return { error: msg };
+			}
+		}
+
+		const choiceContext = resolvedData.choiceContext as Record<string, unknown>;
+		const sharedContext = (choiceContext.choiceContextData as Record<string, unknown>) || {};
+		const values = sharedContext.values as Record<string, unknown> | undefined;
+		if (values && !values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]) {
+			values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock] = { tag: "AV_Bool", value: true };
+		}
+		const sharedDisclosed = ((choiceContext.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+
+		perAllocContexts = allocationCids.map(() => sharedContext);
+		mergedDisclosedContracts = sharedDisclosed;
+	} else {
+		// Per-allocation context: Scan API (Amulet) or Registry API (utility).
+		let baseUrl: string;
+		let contextHeaders: Record<string, string> = {};
+
+		if (isAmulet) {
+			if (!config.VALIDATOR_SCAN_API_URL) {
+				const msg = "bulkWithdrawFunds: VALIDATOR_SCAN_API_URL is required for Amulet allocations";
+				console.error(msg);
+				return { error: msg };
+			}
+			baseUrl = `${config.VALIDATOR_SCAN_API_URL}/registry`;
+			contextHeaders = await buildHeaders();
+		} else {
+			const instrumentDef = resolveInstrumentDefinition(assetId);
+			const networkContracts = instrumentDef?.[config.NETWORK] as Record<string, unknown> | undefined;
+			const registryAPI = networkContracts?.registryAPI as string | undefined;
+			if (!registryAPI) {
+				const msg = `bulkWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
+				console.error(msg);
+				return { error: msg };
+			}
+			baseUrl = registryAPI;
+		}
+
+		const requestConfig = Object.keys(contextHeaders).length > 0 ? { headers: contextHeaders } : undefined;
+		try {
+			const contextResults = await Promise.all(
+				allocationCids.map(async (cid) => {
+					const url = `${baseUrl}/allocations/v1/${encodeURIComponent(cid)}/choice-contexts/withdraw`;
+					try {
+						const resp = await axios.post(url, { meta: {}, excludeDebugFields: true }, requestConfig);
+						return resp.data as Record<string, unknown>;
+					} catch (error: unknown) {
+						const axiosErr = error as { response?: { data?: unknown }; message?: string };
+						const detail = axiosErr.response?.data ? JSON.stringify(axiosErr.response.data) : axiosErr.message;
+						throw new Error(
+							`bulkWithdrawFunds: error fetching withdraw context for ${cid} from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`,
+						);
+					}
+				}),
+			);
+
+			for (const data of contextResults) {
+				perAllocContexts.push((data?.choiceContextData as Record<string, unknown>) || {});
+				const disclosed = ((data?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+					templateId: dc.templateId,
+					contractId: dc.contractId,
+					createdEventBlob: dc.createdEventBlob,
+					synchronizerId: dc.synchronizerId,
+				}));
+				mergedDisclosedContracts.push(...disclosed);
+			}
+		} catch (error: unknown) {
+			const msg = (error as Error).message;
+			console.error(msg);
+			return { error: msg };
+		}
+	}
+
+	// Build one ExerciseCommand per allocation; Canton signs the whole submission atomically.
+	const exerciseCommands = allocationCids.map((cid, idx) => ({
+		ExerciseCommand: {
+			templateId: "#splice-api-token-allocation-v1:Splice.Api.Token.AllocationV1:Allocation",
+			contractId: cid,
+			choice: "Allocation_Withdraw",
+			choiceArgument: {
+				extraArgs: {
+					context: perAllocContexts[idx],
+					meta: { values: {} },
+				},
+			},
+		},
+	}));
+
+	const command = {
+		commands: exerciseCommands,
+		commandId: randomUUID(),
+		userId: userId || getUserId() || config.AUTH0_USER_ID || "temple",
+		applicationId: "temple",
+		actAs: [sender],
+		disclosedContracts: mergedDisclosedContracts,
+	};
+
+	dedupeDisclosedContracts(command);
+
+	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
+
+	if (returnCommand) {
+		return { command, endpoint };
+	}
+
+	if (getWalletAdapter()) {
+		try {
+			await payDueGasIfAny();
+			return (await submitCommand(command)) as Record<string, unknown>;
+		} catch (error: unknown) {
+			const msg = `bulkWithdrawFunds: wallet adapter submission failed: ${(error as Error).message}`;
+			console.error(msg);
+			return { error: msg };
+		}
+	}
+
+	const headers = await buildHeaders();
+	try {
+		const response = await axios.post(endpoint, command, { headers });
+		return response.data;
+	} catch (error: unknown) {
+		const axiosErr = error as { response?: { data?: unknown }; message?: string };
+		const errorData = axiosErr?.response?.data;
+		const errorDetail = errorData ? JSON.stringify(errorData, null, 2) : axiosErr.message;
+		const msg = `bulkWithdrawFunds: error submitting command: ${errorDetail}`;
+		console.error(msg);
+		return { error: msg };
+	}
+}
+
 /**
  * High-level withdrawal flow:
  * 1. Creates a withdrawal request via the backend API.