@temple-digital-group/temple-canton-js 2.0.0-beta.9 → 2.0.1

package/src/canton/withdrawals.ts

@@ -1,489 +1,810 @@
-import config from "../../src/config/index.js";
-import axios from "axios";
-import {
-	getDisclosures,
-	createWithdrawalRequest,
-	getWithdrawalRequestStatus,
-	getDelegation,
-} from "../api/index.js";
-import { getUserId } from "../api/tokenStore.js";
-import { getAdapterPartyId, getWalletAdapter, submitCommand } from "../../src/canton/walletAdapter.js";
-import {
-	randomUUID,
-	shouldUseLedgerForMetadata,
-	normalizeContractId,
-	resolveInstrumentDefinition,
-	getInstrumentRegistrar,
-	dedupeDisclosedContracts,
-	buildHeaders,
-	DEFAULT_AMULET_CONTEXT_KEYS,
-	DEFAULT_UTILITY_CONTEXT_KEYS,
-} from "./helpers.js";
-import type { DisclosedContract, ContractMetadata } from "./helpers.js";
-import {
-	resolveAmuletContext,
-	resolveUtilityInstrumentConfiguration,
-	resolveUtilityAllocationFactory,
-} from "../../src/canton/index.js";
-import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface FinalizeWithdrawOpts {
-	allocationId: string;
-	sender?: string;
-	assetId: string;
-	disclosures?: {
-		disclosures?: {
-			choiceContext?: {
-				choiceContextData?: Record<string, unknown>;
-				disclosedContracts?: DisclosedContract[];
-			};
-		};
-		choiceContext?: {
-			choiceContextData?: Record<string, unknown>;
-			disclosedContracts?: DisclosedContract[];
-		};
-	};
-	userId?: string;
-}
-
-export interface WithdrawFundsOpts {
-	asset_id: string;
-	amount: string | number;
-	pollIntervalMs?: number;
-	maxPollAttempts?: number;
-}
-
-// ─── Withdrawal Functions ────────────────────────────────────────────────────
-
-/**
- * Finalize a withdrawal by exercising the Allocation_Withdraw choice.
- *
- * Supports three metadata resolution paths:
- * 1. Localhost: resolves context from ledger directly
- * 2. Amulet via disclosures (FE/proxy path — no Scan API access)
- * 3. Remote: Scan API / Registry API
- */
-export async function finalizeWithdrawFunds(
-	opts: FinalizeWithdrawOpts,
-	returnCommand = false,
-): Promise<Record<string, unknown>> {
-	const { allocationId, sender: senderOpt, assetId: rawAssetId, disclosures, userId } = opts;
-	const assetId = normalizeAssetId(rawAssetId);
-	const sender = getAdapterPartyId() ?? senderOpt ?? config.VALIDATOR_USER_PARTY_ID;
-
-	if (!allocationId || !sender || !assetId) {
-		const msg = "finalizeWithdrawFunds: allocationId, sender, and assetId are required";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	const isAmulet = assetId === "Amulet";
-
-	const allocationCid = normalizeContractId(allocationId) as string;
-	let choiceContextData: Record<string, unknown> = {};
-	let disclosedContracts: DisclosedContract[] = [];
-
-	if (shouldUseLedgerForMetadata()) {
-		// Localhost: resolve context from ledger directly
-		if (isAmulet) {
-			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
-			if (!amuletCtx) {
-				const msg = "finalizeWithdrawFunds: 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;
-
-			choiceContextData = {
-				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 },
-				},
-			};
-			disclosedContracts = [
-				{
-					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) {
-				disclosedContracts.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) {
-				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 && !config.VALIDATOR_SCAN_API_URL) {
-		// Amulet via disclosures (FE/proxy path — no Scan API access)
-		// Use pre-fetched disclosures if provided, otherwise fetch from API
-		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 = `finalizeWithdrawFunds: failed to resolve Amulet disclosures: ${detail}`;
-				console.error(msg);
-				return { error: msg };
-			}
-		}
-
-		const choiceContext = resolvedData.choiceContext as Record<string, unknown>;
-		choiceContextData = (choiceContext.choiceContextData as Record<string, unknown>) || {};
-		// Ensure expire-lock is present (required by Allocation_Withdraw but not always in API response)
-		const values = choiceContextData.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 };
-		}
-		disclosedContracts = ((choiceContext.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
-			templateId: dc.templateId,
-			contractId: dc.contractId,
-			createdEventBlob: dc.createdEventBlob,
-			synchronizerId: dc.synchronizerId,
-		}));
-	} else {
-		// Remote: fetch choice context from Scan API / Registry API
-		let baseUrl: string;
-		let contextHeaders: Record<string, string> = {};
-
-		if (isAmulet) {
-			if (!config.VALIDATOR_SCAN_API_URL) {
-				const msg = "finalizeWithdrawFunds: 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 = `finalizeWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
-				console.error(msg);
-				return { error: msg };
-			}
-			baseUrl = registryAPI;
-		}
-
-		const contextUrl = `${baseUrl}/allocations/v1/${encodeURIComponent(allocationCid)}/choice-contexts/withdraw`;
-		let contextData: Record<string, unknown>;
-		try {
-			const contextResponse = await axios.post(
-				contextUrl,
-				{
-					meta: {},
-					excludeDebugFields: true,
-				},
-				Object.keys(contextHeaders).length > 0 ? { headers: contextHeaders } : undefined,
-			);
-			contextData = contextResponse.data;
-		} catch (error: unknown) {
-			const axiosErr = error as { response?: { data?: unknown }; message?: string };
-			const detail = axiosErr.response?.data ? JSON.stringify(axiosErr.response.data) : axiosErr.message;
-			const msg = `finalizeWithdrawFunds: error fetching withdraw context from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
-			console.error(msg);
-			return { error: msg };
-		}
-
-		choiceContextData = (contextData?.choiceContextData as Record<string, unknown>) || {};
-		disclosedContracts = ((contextData?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
-			templateId: dc.templateId,
-			contractId: dc.contractId,
-			createdEventBlob: dc.createdEventBlob,
-			synchronizerId: dc.synchronizerId,
-		}));
-	}
-
-	// --- Build the ExerciseCommand for Allocation_Withdraw ---
-	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);
-
-	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
-
-	if (returnCommand) {
-		return { command, endpoint };
-	}
-
-	// Auto-submit via wallet adapter if available
-	if (getWalletAdapter()) {
-		try {
-			return (await submitCommand(command)) as Record<string, unknown>;
-		} catch (error: unknown) {
-			const msg = `finalizeWithdrawFunds: 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 = `finalizeWithdrawFunds: error submitting command: ${errorDetail}`;
-		console.error(msg);
-		return { error: msg };
-	}
-}
-
-/**
- * High-level withdrawal flow:
- * 1. Creates a withdrawal request via the backend API.
- * 2. Polls the request status until it is no longer "pending".
- * 3. Exercises Allocation_Withdraw on the allocation contract to release holdings back to the user.
- */
-export async function withdrawFunds(
-	opts: WithdrawFundsOpts,
-	returnCommand = false,
-): Promise<Record<string, unknown>> {
-	const { amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
-	const asset_id = normalizeAssetId(opts?.asset_id);
-
-	const sender = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
-	if (!sender) {
-		const msg = "withdrawFunds: sender party is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID.";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	// 1. Submit the withdrawal request
-	const createResult = (await createWithdrawalRequest(asset_id, amount)) as Record<string, unknown>;
-	if (createResult?.error) {
-		return createResult;
-	}
-
-	const requestId = createResult?.request_id;
-	if (requestId == null) {
-		const msg = "withdrawFunds: backend did not return a request_id";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	console.log(`withdrawFunds: withdrawal request ${requestId} submitted, polling for status...`);
-
-	// 2. Poll until status is "ready" and allocation_cid is available
-	let allocationCid: string | null = null;
-	for (let attempt = 1; attempt <= maxPollAttempts; attempt++) {
-		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-
-		const status = (await getWithdrawalRequestStatus(String(requestId))) as Record<string, unknown>;
-		if (status?.error) {
-			return status;
-		}
-
-		// Terminal failure states — stop polling
-		if (status.status === "failed" || status.status === "rejected") {
-			console.error(`withdrawFunds: request ${requestId} ${status.status}`);
-			return status;
-		}
-
-		// Ready with an allocation_cid — proceed to withdraw
-		if (status.status === "ready" && status.allocation_cid) {
-			console.log(`withdrawFunds: request ${requestId} ready — allocation_cid: ${status.allocation_cid}`);
-			allocationCid = status.allocation_cid as string;
-			break;
-		}
-
-		if (attempt % 5 === 0) {
-			console.log(`withdrawFunds: still waiting (status=${status.status}) after ${attempt} poll(s)...`);
-		}
-	}
-
-	if (!allocationCid) {
-		const msg = `withdrawFunds: request ${requestId} not ready after ${maxPollAttempts} attempts`;
-		console.error(msg);
-		return { error: msg, request_id: requestId };
-	}
-
-	// 3. Exercise Allocation_Withdraw to release held funds back to the user
-	console.log(`withdrawFunds: exercising Allocation_Withdraw on ${allocationCid}...`);
-	const assetId = asset_id;
-	const withdrawResult = await finalizeWithdrawFunds({ allocationId: allocationCid, sender, assetId }, returnCommand);
-
-	if (withdrawResult?.error) {
-		console.error(`withdrawFunds: Allocation_Withdraw failed for request ${requestId}: ${withdrawResult.error}`);
-		return { error: withdrawResult.error as string, request_id: requestId, allocation_cid: allocationCid };
-	}
-
-	console.log(`withdrawFunds: withdrawal complete for request ${requestId}`);
-	return { ...withdrawResult, request_id: requestId, allocation_cid: allocationCid };
-}
-
-/**
- * Withdraw a Delegation contract (user-initiated).
- *
- * Exercises the WithdrawDelegation choice on the Delegation interface,
- * which archives the delegation and revokes the operator's authority.
- */
-export async function withdrawDelegation(
-	delegationId: string | null = null,
-	user: string | null = null,
-	returnCommand = false,
-): Promise<Record<string, unknown>> {
-	let resolvedUser = user ?? getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
-	let resolvedDelegationId = delegationId;
-
-	// If no delegationId passed, fetch it from the API
-	if (!resolvedDelegationId) {
-		const result = (await getDelegation()) as unknown as Record<string, unknown>;
-		const delegation = result?.delegation as Record<string, unknown> | undefined;
-		if (result?.error || !delegation) {
-			const msg =
-				"withdrawDelegation: could not resolve delegation. Pass delegationId directly or ensure the user is onboarded.";
-			console.error(msg);
-			return { error: msg };
-		}
-		resolvedDelegationId = delegation.delegation_cid as string;
-	}
-	if (!resolvedUser) {
-		const msg =
-			"withdrawDelegation: user party is required. Pass it directly, set WALLET_ADAPTER, or configure VALIDATOR_USER_PARTY_ID.";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	const command = {
-		commands: [
-			{
-				ExerciseCommand: {
-					templateId: `${config.PACKAGE_NAME_SETTLEMENT_INTERFACE}:Temple.Settlement.Interface.Delegation:Delegation`,
-					contractId: normalizeContractId(resolvedDelegationId),
-					choice: "WithdrawDelegation",
-					choiceArgument: {},
-				},
-			},
-		],
-		commandId: randomUUID(),
-		userId: getUserId() || config.AUTH0_USER_ID || "temple",
-		applicationId: "temple",
-		actAs: [resolvedUser],
-	};
-
-	if (returnCommand) {
-		return { command, endpoint: `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait` };
-	}
-
-	// Auto-submit via wallet adapter if available
-	if (getWalletAdapter()) {
-		try {
-			return (await submitCommand(command)) as Record<string, unknown>;
-		} catch (error: unknown) {
-			const msg = `withdrawDelegation: wallet adapter submission failed: ${(error as Error).message}`;
-			console.error(msg);
-			return { error: msg };
-		}
-	}
-
-	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
-	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 = `withdrawDelegation: error submitting command: ${errorDetail}`;
-		console.error(msg);
-		return { error: msg };
-	}
-}
+import config from "../../src/config/index.js";
+import axios from "axios";
+import {
+	getDisclosures,
+	createWithdrawalRequest,
+	getWithdrawalRequestStatus,
+	getDelegation,
+} from "../api/index.js";
+import { getUserId } from "../api/tokenStore.js";
+import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "../../src/canton/walletAdapter.js";
+import {
+	randomUUID,
+	shouldUseLedgerForMetadata,
+	normalizeContractId,
+	resolveInstrumentDefinition,
+	getInstrumentRegistrar,
+	resolveProvider,
+	dedupeDisclosedContracts,
+	buildHeaders,
+	DEFAULT_AMULET_CONTEXT_KEYS,
+	DEFAULT_UTILITY_CONTEXT_KEYS,
+} from "./helpers.js";
+import type { DisclosedContract, ContractMetadata } from "./helpers.js";
+import {
+	resolveAmuletContext,
+	resolveUtilityInstrumentConfiguration,
+	resolveUtilityAllocationFactory,
+	getUtxoCount,
+} from "../../src/canton/index.js";
+import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const CC_FEE_RESERVE = 10;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface FinalizeWithdrawOpts {
+	allocationId: string;
+	sender?: string;
+	assetId: string;
+	disclosures?: {
+		disclosures?: {
+			choiceContext?: {
+				choiceContextData?: Record<string, unknown>;
+				disclosedContracts?: DisclosedContract[];
+			};
+		};
+		choiceContext?: {
+			choiceContextData?: Record<string, unknown>;
+			disclosedContracts?: DisclosedContract[];
+		};
+	};
+	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;
+	pollIntervalMs?: number;
+	maxPollAttempts?: number;
+}
+
+// ─── Withdrawal Functions ────────────────────────────────────────────────────
+
+/**
+ * Finalize a withdrawal by exercising the Allocation_Withdraw choice.
+ *
+ * Supports three metadata resolution paths:
+ * 1. Localhost: resolves context from ledger directly
+ * 2. Amulet via disclosures (FE/proxy path — no Scan API access)
+ * 3. Remote: Scan API / Registry API
+ */
+export async function finalizeWithdrawFunds(
+	opts: FinalizeWithdrawOpts,
+	returnCommand = false,
+): Promise<Record<string, unknown>> {
+	const { allocationId, sender: senderOpt, assetId: rawAssetId, disclosures, userId } = opts;
+	const assetId = normalizeAssetId(rawAssetId);
+	const sender = getAdapterPartyId() ?? senderOpt ?? config.VALIDATOR_USER_PARTY_ID;
+
+	if (!allocationId || !sender || !assetId) {
+		const msg = "finalizeWithdrawFunds: allocationId, sender, and assetId are required";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	const isAmulet = assetId === "Amulet";
+
+	const allocationCid = normalizeContractId(allocationId) as string;
+	let choiceContextData: Record<string, unknown> = {};
+	let disclosedContracts: DisclosedContract[] = [];
+
+	if (shouldUseLedgerForMetadata()) {
+		// Localhost: resolve context from ledger directly
+		if (isAmulet) {
+			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
+			if (!amuletCtx) {
+				const msg = "finalizeWithdrawFunds: 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;
+
+			choiceContextData = {
+				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 },
+				},
+			};
+			disclosedContracts = [
+				{
+					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) {
+				disclosedContracts.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) {
+				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 && !config.VALIDATOR_SCAN_API_URL) {
+		// Amulet via disclosures (FE/proxy path — no Scan API access)
+		// Use pre-fetched disclosures if provided, otherwise fetch from API
+		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 = `finalizeWithdrawFunds: failed to resolve Amulet disclosures: ${detail}`;
+				console.error(msg);
+				return { error: msg };
+			}
+		}
+
+		const choiceContext = resolvedData.choiceContext as Record<string, unknown>;
+		choiceContextData = (choiceContext.choiceContextData as Record<string, unknown>) || {};
+		// Ensure expire-lock is present (required by Allocation_Withdraw but not always in API response)
+		const values = choiceContextData.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 };
+		}
+		disclosedContracts = ((choiceContext.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+	} else {
+		// Remote: fetch choice context from Scan API / Registry API
+		let baseUrl: string;
+		let contextHeaders: Record<string, string> = {};
+
+		if (isAmulet) {
+			if (!config.VALIDATOR_SCAN_API_URL) {
+				const msg = "finalizeWithdrawFunds: 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 = `finalizeWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
+				console.error(msg);
+				return { error: msg };
+			}
+			baseUrl = registryAPI;
+		}
+
+		const contextUrl = `${baseUrl}/allocations/v1/${encodeURIComponent(allocationCid)}/choice-contexts/withdraw`;
+		let contextData: Record<string, unknown>;
+		try {
+			const contextResponse = await axios.post(
+				contextUrl,
+				{
+					meta: {},
+					excludeDebugFields: true,
+				},
+				Object.keys(contextHeaders).length > 0 ? { headers: contextHeaders } : undefined,
+			);
+			contextData = contextResponse.data;
+		} catch (error: unknown) {
+			const axiosErr = error as { response?: { data?: unknown }; message?: string };
+			const detail = axiosErr.response?.data ? JSON.stringify(axiosErr.response.data) : axiosErr.message;
+			const msg = `finalizeWithdrawFunds: error fetching withdraw context from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
+			console.error(msg);
+			return { error: msg };
+		}
+
+		choiceContextData = (contextData?.choiceContextData as Record<string, unknown>) || {};
+		disclosedContracts = ((contextData?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+	}
+
+	// --- Build the ExerciseCommand for Allocation_Withdraw ---
+	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);
+
+	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
+
+	if (returnCommand) {
+		return { command, endpoint };
+	}
+
+	// Auto-submit via wallet adapter if available
+	if (getWalletAdapter()) {
+		try {
+			await payDueGasIfAny();
+			return (await submitCommand(command)) as Record<string, unknown>;
+		} catch (error: unknown) {
+			const msg = `finalizeWithdrawFunds: 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 = `finalizeWithdrawFunds: error submitting command: ${errorDetail}`;
+		console.error(msg);
+		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: 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.
+ * 2. Polls the request status until it is no longer "pending".
+ * 3. Exercises Allocation_Withdraw on the allocation contract to release holdings back to the user.
+ */
+export async function withdrawFunds(
+	opts: WithdrawFundsOpts,
+	returnCommand = false,
+): Promise<Record<string, unknown>> {
+	const { amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
+	const asset_id = normalizeAssetId(opts?.asset_id);
+
+	const sender = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
+	if (!sender) {
+		const msg = "withdrawFunds: sender party is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID.";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	// Pay any outstanding network gas first so the fee-reserve check below is accurate.
+	await payDueGasIfAny();
+
+	// Ensure the user has enough CC unlocked to pay gas for the eventual Allocation_Withdraw.
+	const provider = resolveProvider(null);
+	const ccBalance = await getUtxoCount(sender, "Amulet", provider);
+	const availableCC = ccBalance.unlockedBalance || 0;
+	if (availableCC < CC_FEE_RESERVE) {
+		return {
+			error: `withdrawFunds: insufficient CC for fees. You have ${availableCC} CC but need at least ${CC_FEE_RESERVE} CC to cover transaction fees.`,
+			data: { ccBalance: availableCC, feeReserve: CC_FEE_RESERVE },
+		};
+	}
+
+	// 1. Submit the withdrawal request
+	const createResult = (await createWithdrawalRequest(asset_id, amount)) as Record<string, unknown>;
+	if (createResult?.error) {
+		return createResult;
+	}
+
+	const requestId = createResult?.request_id;
+	if (requestId == null) {
+		const msg = "withdrawFunds: backend did not return a request_id";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	console.log(`withdrawFunds: withdrawal request ${requestId} submitted, polling for status...`);
+
+	// 2. Poll until status is "ready" and allocation_cid is available
+	let allocationCid: string | null = null;
+	for (let attempt = 1; attempt <= maxPollAttempts; attempt++) {
+		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+
+		const status = (await getWithdrawalRequestStatus(String(requestId))) as Record<string, unknown>;
+		if (status?.error) {
+			return status;
+		}
+
+		// Terminal failure states — stop polling
+		if (status.status === "failed" || status.status === "rejected") {
+			console.error(`withdrawFunds: request ${requestId} ${status.status}`);
+			return status;
+		}
+
+		// Ready with an allocation_cid — proceed to withdraw
+		if (status.status === "ready" && status.allocation_cid) {
+			console.log(`withdrawFunds: request ${requestId} ready — allocation_cid: ${status.allocation_cid}`);
+			allocationCid = status.allocation_cid as string;
+			break;
+		}
+
+		if (attempt % 5 === 0) {
+			console.log(`withdrawFunds: still waiting (status=${status.status}) after ${attempt} poll(s)...`);
+		}
+	}
+
+	if (!allocationCid) {
+		const msg = `withdrawFunds: request ${requestId} not ready after ${maxPollAttempts} attempts`;
+		console.error(msg);
+		return { error: msg, request_id: requestId };
+	}
+
+	// 3. Exercise Allocation_Withdraw to release held funds back to the user
+	console.log(`withdrawFunds: exercising Allocation_Withdraw on ${allocationCid}...`);
+	const assetId = asset_id;
+	const withdrawResult = await finalizeWithdrawFunds({ allocationId: allocationCid, sender, assetId }, returnCommand);
+
+	if (withdrawResult?.error) {
+		console.error(`withdrawFunds: Allocation_Withdraw failed for request ${requestId}: ${withdrawResult.error}`);
+		return { error: withdrawResult.error as string, request_id: requestId, allocation_cid: allocationCid };
+	}
+
+	console.log(`withdrawFunds: withdrawal complete for request ${requestId}`);
+	return { ...withdrawResult, request_id: requestId, allocation_cid: allocationCid };
+}
+
+/**
+ * Withdraw a Delegation contract (user-initiated).
+ *
+ * Exercises the WithdrawDelegation choice on the Delegation interface,
+ * which archives the delegation and revokes the operator's authority.
+ */
+export async function withdrawDelegation(
+	delegationId: string | null = null,
+	user: string | null = null,
+	returnCommand = false,
+): Promise<Record<string, unknown>> {
+	let resolvedUser = user ?? getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
+	let resolvedDelegationId = delegationId;
+
+	// If no delegationId passed, fetch it from the API
+	if (!resolvedDelegationId) {
+		const result = (await getDelegation()) as unknown as Record<string, unknown>;
+		const delegation = result?.delegation as Record<string, unknown> | undefined;
+		if (result?.error || !delegation) {
+			const msg =
+				"withdrawDelegation: could not resolve delegation. Pass delegationId directly or ensure the user is onboarded.";
+			console.error(msg);
+			return { error: msg };
+		}
+		resolvedDelegationId = delegation.delegation_cid as string;
+	}
+	if (!resolvedUser) {
+		const msg =
+			"withdrawDelegation: user party is required. Pass it directly, set WALLET_ADAPTER, or configure VALIDATOR_USER_PARTY_ID.";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	const command = {
+		commands: [
+			{
+				ExerciseCommand: {
+					templateId: `${config.PACKAGE_NAME_SETTLEMENT_INTERFACE}:Temple.Settlement.Interface.Delegation:Delegation`,
+					contractId: normalizeContractId(resolvedDelegationId),
+					choice: "WithdrawDelegation",
+					choiceArgument: {},
+				},
+			},
+		],
+		commandId: randomUUID(),
+		userId: getUserId() || config.AUTH0_USER_ID || "temple",
+		applicationId: "temple",
+		actAs: [resolvedUser],
+	};
+
+	if (returnCommand) {
+		return { command, endpoint: `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait` };
+	}
+
+	// Auto-submit via wallet adapter if available
+	if (getWalletAdapter()) {
+		try {
+			await payDueGasIfAny();
+			return (await submitCommand(command)) as Record<string, unknown>;
+		} catch (error: unknown) {
+			const msg = `withdrawDelegation: wallet adapter submission failed: ${(error as Error).message}`;
+			console.error(msg);
+			return { error: msg };
+		}
+	}
+
+	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
+	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 = `withdrawDelegation: error submitting command: ${errorDetail}`;
+		console.error(msg);
+		return { error: msg };
+	}
+}