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

package/src/canton/index.js

@@ -45,7 +45,7 @@ import unlockAmuletSchema from "./request_schemas/unlock_amulet.json" with { typ
 import createUtilityCredentialSchema from "./request_schemas/create_utility_credential.json" with { type: "json" };
 
 // Import instrument catalog
-import { RegistrarInternalScheme, instrumentCatalog, instrumentIdToSymbol, supportedTradingPairs, supportedSymbols, normalizeAssetId } from "./instrumentCatalog.js";
+import { RegistrarInternalScheme, instrumentCatalog, instrumentIdToSymbol, supportedTradingPairs, supportedSymbols, normalizeAssetId, resolveOnChainInstrumentId } from "./instrumentCatalog.js";
 
 
 /**
@@ -1233,7 +1233,7 @@ async function buildLocalUtilityTransferFactory(investor, registrar, amount, hol
 			amount: amount,
 			instrumentId: {
 				admin: registrar,
-				id: utilityAsset || "tSBC",
+				id: resolveOnChainInstrumentId(utilityAsset) || "tSBC",
 			},
 		},
 		expectedAdmin: registrar,
@@ -1270,7 +1270,7 @@ async function getTransferFactoryFromRegistry(investor, registrar, amount, holdi
 		dso: registrar,
 		amount: amount,
 		holding_ids: holdingIds,
-		instrument_id: utilityAsset,
+		instrument_id: resolveOnChainInstrumentId(utilityAsset),
 		time: new Date().toISOString(),
 		timeEnd: new Date(Date.now() + 3600 * 1000).toISOString(),
 	};
@@ -1315,7 +1315,7 @@ export async function getTransferFactory(investor, admin, amount, holdingIds, re
 		dso: admin,
 		amount: amount,
 		holding_ids: holdingIds,
-		instrument_id: utilityAsset || "Amulet",
+		instrument_id: resolveOnChainInstrumentId(utilityAsset) || "Amulet",
 		time: new Date().toISOString(),
 		timeEnd: new Date(Date.now() + 3600 * 1000).toISOString(),
 	};
@@ -1627,8 +1627,9 @@ export async function getUtxoCount(party, assetId, provider = null) {
 			quantity = parseFloat(createArg?.amount?.initialAmount || 0);
 			matchesAsset = true;
 		} else {
-			const asset = createArg?.instrument?.id || null;
-			if (asset !== assetId) continue;
+			const onChainId = createArg?.instrument?.id || null;
+			const heldSymbol = instrumentIdToSymbol[onChainId] || onChainId;
+			if (heldSymbol !== assetId) continue;
 			isLocked = !!createArg?.lock;
 			quantity = parseFloat(createArg?.amount || 0);
 			matchesAsset = true;
@@ -1818,8 +1819,12 @@ export async function getCandidateHoldingForOrderCreation(party, isAmulet, requi
 			// For Utility, quantity is in createArgument.amount
 			const quantity = isAmulet ? parseFloat(createdEvent.createArgument?.amount?.initialAmount || 0) : parseFloat(createdEvent.createArgument?.amount || 0);
 
-			// For Utility, also get the asset ID and scheme
-			const asset = isAmulet ? "Amulet" : createdEvent.createArgument?.instrument?.id || null;
+			// For Utility, also get the asset ID and scheme.
+			// instrument.id from the ledger is the on-chain value (UUID for USDA/SBC);
+			// translate to catalog symbol so downstream comparisons against user-passed
+			// expectedAssetId work uniformly.
+			const onChainId = isAmulet ? null : createdEvent.createArgument?.instrument?.id || null;
+			const asset = isAmulet ? "Amulet" : instrumentIdToSymbol[onChainId] || onChainId;
 			const instrumentScheme = isAmulet ? null : createdEvent.createArgument?.instrument?.scheme || null;
 
 			// Extract owner/holder/operator/provider for debugging
@@ -2006,8 +2011,8 @@ export async function mergeAmuletHoldingsForParty(party, returnCommand = false,
 		return null;
 	}
 
-	// Sort by quantity ascending (smallest first) and apply maxUtxos limit
-	contracts.sort((a, b) => a.quantity - b.quantity);
+	// Sort by quantity descending (largest first) and apply maxUtxos limit
+	contracts.sort((a, b) => b.quantity - a.quantity);
 	const selectedContracts = maxUtxos && maxUtxos < contracts.length ? contracts.slice(0, maxUtxos) : contracts;
 
 	if (selectedContracts.length < 2) {
@@ -2209,7 +2214,8 @@ export async function mergeUtilityHoldingsForParty(party, utilityAsset, returnCo
 			const source = createArg?.instrument?.source || null;
 			const rawAmount = createArg?.amount || "0";
 			const quantity = parseFloat(rawAmount);
-			const asset = createArg?.instrument?.id || null;
+			const onChainId = createArg?.instrument?.id || null;
+			const asset = instrumentIdToSymbol[onChainId] || onChainId;
 			const lock = createArg?.lock || false;
 			// Extract the holder from the holding contract (for utility tokens)
 			// Try multiple possible field names
@@ -2312,9 +2318,9 @@ export async function mergeUtilityHoldingsForParty(party, utilityAsset, returnCo
 	const finalHolders = [...new Set(contracts.map((c) => c.holder).filter(Boolean))];
 	const holder = finalHolders[0] || party; // Use the holder from filtered holdings
 
-	// Sort ascending by quantity so smallest UTXOs are merged first
+	// Sort descending by quantity so largest UTXOs are merged first
 	if (maxUtxos) {
-		contracts.sort((a, b) => a.quantity - b.quantity);
+		contracts.sort((a, b) => b.quantity - a.quantity);
 		if (contracts.length > maxUtxos) {
 			contracts.length = maxUtxos;
 		}
@@ -2368,7 +2374,7 @@ export async function mergeUtilityHoldingsForParty(party, utilityAsset, returnCo
 	const rawAmount = transferInstruction.amount || totalQuantity;
 	const actualAmount = parseFloat(parseFloat(rawAmount).toFixed(10));
 	const instrumentAdmin = transferInstruction.instrumentId?.admin || registrar;
-	const instrumentIdValue = transferInstruction.instrumentId?.id || utilityAsset;
+	const instrumentIdValue = transferInstruction.instrumentId?.id || resolveOnChainInstrumentId(utilityAsset);
 	// For utility tokens the TransferFactory is registrar-administered, so expectedAdmin = registrar.
 	// Prefer the value returned by the Registry API, then fall back to the registrar from holdings.
 	const expectedAdmin = transferFactoryData.expectedAdmin || registrar;
@@ -2645,6 +2651,185 @@ 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 ─────────────────────────────────────────────────
 
@@ -2832,6 +3017,177 @@ export async function isUserOnboarded(user = null, returnCommand = false) {
 	}
 }
 
+/**
+ * Build an Allocation_Withdraw ExerciseCommand for one or more stuck allocation CIDs.
+ * Returns the command(s) ready for submission via wallet adapter or ledger API.
+ *
+ * @param {Object} opts
+ * @param {string|string[]} opts.allocationCids - Single CID or array of allocation contract IDs
+ * @param {string} opts.assetId - The asset symbol ("Amulet", "CC", "USDCx", etc.)
+ * @param {string} [opts.sender] - Party ID. Falls back to wallet adapter or VALIDATOR_USER_PARTY_ID.
+ * @param {Object} [opts.disclosures] - Pre-fetched disclosures (optional, will be resolved if missing)
+ * @returns {Promise<Object>} { commands: [...] } array of { command, endpoint } objects, or { error }
+ */
+export async function buildAllocationWithdrawCommand(opts) {
+	const { disclosures, userId } = opts || {};
+	const assetId = (opts.assetId === "CC" || opts.assetId === "cc") ? "Amulet" : 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 };
+	});
+
+	return { commands };
+}
+
 /**
  * Get all balances for a party, grouped by asset type.
  * Returns Amulet, locked Amulet, and utility token holdings with totals.

package/src/canton/instrumentCatalog.d.ts

@@ -4,3 +4,4 @@ export const instrumentIdToSymbol: Record<string, string>;
 export const supportedTradingPairs: Array<{ baseAsset: string; quoteAsset: string }>;
 export const supportedSymbols: Record<string, unknown>;
 export function normalizeAssetId(symbol: string): string;
+export function resolveOnChainInstrumentId(symbol: string): string;