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

package/src/canton/deposits.ts

@@ -1,559 +1,563 @@
-import config from "../../src/config/index.js";
-import axios from "axios";
-import { getDisclosures } from "../api/index.js";
-import { getUserId } from "../api/tokenStore.js";
-import { getAdapterPartyId, getWalletAdapter, submitCommand } from "../../src/canton/walletAdapter.js";
-import { normalizeAssetId, instrumentCatalog } from "../../src/canton/instrumentCatalog.js";
-import {
-	randomUUID,
-	shouldUseLedgerForMetadata,
-	normalizeContractId,
-	resolveInstrumentDefinition,
-	getInstrumentRegistrar,
-	resolveProvider,
-	dedupeDisclosedContracts,
-	buildHeaders,
-	DEFAULT_UTILITY_CONTEXT_KEYS,
-} from "./helpers.js";
-import type { DisclosedContract, ContractMetadata } from "./helpers.js";
-import {
-	resolveAmuletContext,
-	resolveUtilityInstrumentConfiguration,
-	resolveUtilityAllocationFactory,
-	getAmuletHoldingsForParty,
-	getUtilityHoldingsForParty,
-	getUtxoCount,
-} from "../../src/canton/index.js";
-
-// ─── Constants ───────────────────────────────────────────────────────────────
-
-const CC_FEE_RESERVE = 10;
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface DepositFundsOpts {
-	sender: string;
-	receiver?: string;
-	assetId: string;
-	amount: string | number;
-	holdingCids?: string[];
-	settlementId?: string;
-	transferLegId?: string;
-	allocateBefore?: string;
-	settleBefore?: string;
-	disclosures?: Record<string, unknown>;
-	userId?: string;
-}
-
-export interface PreparedDeposit {
-	sender: string;
-	receiver: string;
-	assetId: string;
-	amount: string;
-	holdingCids: string[];
-}
-
-// ─── Deposit Functions ───────────────────────────────────────────────────────
-
-/**
- * Prepare holdings for a deposit by selecting UTXOs from the wallet provider.
- *
- * Queries the provider for holdings, filters and sorts them, then greedily
- * selects until the requested amount is covered.
- */
-export async function prepareDepositHoldings(
-	amount: number | string,
-	symbol: string,
-): Promise<PreparedDeposit | { error: string; data?: Record<string, unknown> }> {
-	const provider = resolveProvider(null);
-	if (!provider && !config.VALIDATOR_SCAN_API_URL) {
-		return { error: "prepareDepositHoldings: wallet provider is required to prepare holdings. Connect a wallet adapter." };
-	}
-
-	const party = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
-	if (!party) {
-		return { error: "prepareDepositHoldings: party ID is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID." };
-	}
-
-	const assetId = normalizeAssetId(symbol);
-
-	if (!instrumentCatalog[assetId]) {
-		return { error: `prepareDepositHoldings: unsupported symbol "${symbol}"` };
-	}
-
-	const requiredAmount = parseFloat(String(amount));
-	if (isNaN(requiredAmount) || requiredAmount <= 0) {
-		return { error: "prepareDepositHoldings: amount must be a positive number" };
-	}
-
-	const isAmulet = assetId === "Amulet";
-	const holdings = isAmulet
-		? await getAmuletHoldingsForParty(party, false, provider)
-		: await getUtilityHoldingsForParty(party, false, provider);
-
-	if (!holdings || (holdings as unknown[]).length === 0) {
-		return { error: `prepareDepositHoldings: no holdings found for party ${party}` };
-	}
-
-	// Parse holdings into { contractId, quantity } and filter out locked
-	const parsed: { contractId: string; quantity: number }[] = [];
-	for (const h of holdings as Record<string, unknown>[]) {
-		const contractEntry = h.contractEntry as Record<string, unknown> | undefined;
-		const jsActive = contractEntry?.JsActiveContract as Record<string, unknown> | undefined;
-		const createdEvent = jsActive?.createdEvent as Record<string, unknown> | undefined;
-		if (!createdEvent) continue;
-
-		const createArg = createdEvent.createArgument as Record<string, unknown> | undefined;
-
-		// Skip asset types that don't match the requested symbol
-		const instrument = createArg?.instrument as Record<string, unknown> | undefined;
-		const createdAssetId = (instrument?.id as string) || (isAmulet ? "Amulet" : null);
-		if (createdAssetId !== assetId) continue;
-
-		// Skip locked utility holdings
-		if (!isAmulet && createArg?.lock) continue;
-
-		const amountField = createArg?.amount as Record<string, unknown> | string | undefined;
-		const quantity = isAmulet
-			? parseFloat(((amountField as Record<string, unknown>)?.initialAmount as string) || "0")
-			: parseFloat((amountField as string) || "0");
-
-		if (quantity <= 0) continue;
-
-		parsed.push({
-			contractId: normalizeContractId(createdEvent.contractId as string) as string,
-			quantity,
-		});
-	}
-
-	if (parsed.length === 0) {
-		return { error: `prepareDepositHoldings: no unlocked holdings found for ${assetId}` };
-	}
-
-	// Sort descending — largest first
-	parsed.sort((a, b) => b.quantity - a.quantity);
-
-	// Greedily select until we cover the required amount
-	const selected: string[] = [];
-	let cumulative = 0;
-	for (const holding of parsed) {
-		selected.push(holding.contractId);
-		cumulative += holding.quantity;
-		if (cumulative >= requiredAmount) break;
-	}
-
-	if (cumulative < requiredAmount) {
-		return {
-			error: `prepareDepositHoldings: insufficient balance. Have ${cumulative}, need ${requiredAmount}`,
-			data: { totalBalance: cumulative, requiredAmount },
-		};
-	}
-
-	const formattedAmount = parseFloat(parseFloat(String(amount)).toFixed(10)).toString();
-
-	return {
-		sender: party,
-		receiver: party,
-		assetId,
-		amount: formattedAmount,
-		holdingCids: selected,
-	};
-}
-
-/**
- * High-level deposit helper.
- *
- * Wraps `prepareDepositHoldings` and `depositFunds` into a single call.
- * Validates the user has sufficient balance and reserves 10 CC for transaction fees.
- *
- * Requires:
- * - Wallet adapter (for reading balances and submitting)
- * - API connection (for disclosures on Amulet deposits)
- */
-export async function deposit(
-	amount: number | string,
-	symbol: string,
-): Promise<Record<string, unknown>> {
-	if (!getWalletAdapter()) {
-		return { error: "deposit: wallet adapter is required. Call setWalletAdapter() first." };
-	}
-
-	const party = getAdapterPartyId();
-	if (!party) {
-		return { error: "deposit: could not resolve party ID from wallet adapter." };
-	}
-
-	const assetId = normalizeAssetId(symbol);
-	if (!instrumentCatalog[assetId]) {
-		return { error: `deposit: unsupported symbol "${symbol}"` };
-	}
-
-	const depositAmount = parseFloat(String(amount));
-	if (isNaN(depositAmount) || depositAmount <= 0) {
-		return { error: "deposit: amount must be a positive number" };
-	}
-
-	const isAmulet = assetId === "Amulet";
-	const provider = resolveProvider(null);
-
-	// Check CC balance — required for all deposits (fees)
-	const ccBalance = await getUtxoCount(party, "Amulet", provider);
-	const availableCC = ccBalance.unlockedBalance || 0;
-
-	if (isAmulet) {
-		// CC deposit: user needs depositAmount + 10 CC fee reserve
-		const maxDeposit = availableCC - CC_FEE_RESERVE;
-		if (maxDeposit <= 0) {
-			return {
-				error: `deposit: insufficient CC balance. You have ${availableCC} CC but need at least ${CC_FEE_RESERVE} CC reserved for fees.`,
-				data: { balance: availableCC, feeReserve: CC_FEE_RESERVE, maxDeposit: 0 },
-			};
-		}
-		if (depositAmount > maxDeposit) {
-			return {
-				error: `deposit: amount exceeds maximum. You have ${availableCC} CC, ${CC_FEE_RESERVE} CC is reserved for fees, max deposit is ${maxDeposit} CC.`,
-				data: { balance: availableCC, feeReserve: CC_FEE_RESERVE, maxDeposit },
-			};
-		}
-	} else {
-		// Utility deposit: user needs 10 CC for fees + enough of the utility token
-		if (availableCC < CC_FEE_RESERVE) {
-			return {
-				error: `deposit: 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 },
-			};
-		}
-
-		const utilityBalance = await getUtxoCount(party, assetId, provider);
-		const availableUtility = utilityBalance.unlockedBalance || 0;
-		if (depositAmount > availableUtility) {
-			return {
-				error: `deposit: insufficient ${assetId} balance. You have ${availableUtility} ${assetId}, need ${depositAmount}.`,
-				data: { balance: availableUtility, requested: depositAmount },
-			};
-		}
-	}
-
-	// Step 1: Prepare holdings (select UTXOs)
-	console.log(`deposit: preparing ${depositAmount} ${assetId} for deposit...`);
-	const prepared = await prepareDepositHoldings(depositAmount, assetId);
-	if ("error" in prepared) {
-		return prepared;
-	}
-
-	// Step 2: Execute deposit (allocate holdings)
-	console.log(`deposit: submitting deposit with ${prepared.holdingCids.length} holding(s)...`);
-	const result = await depositFunds(prepared);
-	if (result?.error) {
-		return result;
-	}
-
-	console.log(`deposit: ${depositAmount} ${assetId} deposited successfully`);
-	return result;
-}
-
-/**
- * Create a CIP-56 Allocation.
- * Fetches the AllocationFactory, then exercises AllocationFactory_Allocate
- * to lock holdings for a settlement leg.
- *
- * Three resolution paths:
- * 1. Localhost: resolve factory and context from ledger directly
- * 2. Amulet via disclosures (FE/proxy path — no Scan API access)
- * 3. Remote: Scan API / Registry API
- */
-export async function depositFunds(
-	opts: DepositFundsOpts,
-	returnCommand = false,
-): Promise<Record<string, unknown>> {
-	const { sender, receiver, amount, holdingCids = [], settlementId, transferLegId, allocateBefore, settleBefore, disclosures, userId } = opts;
-	const assetId = normalizeAssetId(opts.assetId);
-
-	if (!sender || !assetId || !amount) {
-		const msg = "depositFunds: sender, assetId, and amount are required";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	const isAmulet = assetId === "Amulet";
-
-	// --- 1. Resolve admin and factory ---
-	let admin: string;
-	let factoryContractId: string | undefined;
-	let choiceContextData: Record<string, unknown> = {};
-	let disclosedContracts: DisclosedContract[] = [];
-
-	if (isAmulet) {
-		admin = config.VALIDATOR_DSO_PARTY_ID;
-	} else {
-		const instrumentDef = resolveInstrumentDefinition(assetId);
-		const networkContracts = instrumentDef?.[config.NETWORK] as Record<string, unknown> | undefined;
-		admin = (networkContracts?.registrar as string) || getInstrumentRegistrar(assetId) || config.VALIDATOR_REGISTRAR_PARTY_ID;
-	}
-
-	// --- 2. Build the choice arguments upfront ---
-	const now = new Date();
-	const allocateDeadline = allocateBefore || new Date(now.getTime() + 60 * 60 * 1000).toISOString();
-	const settleDeadline = settleBefore || new Date(now.getTime() + 2 * 60 * 60 * 1000).toISOString();
-	const executor = config.TEMPLE_PARTY_ID;
-	const resolvedTransferLegId = transferLegId || randomUUID();
-	const resolvedSettlementId = settlementId || `SR-${randomUUID()}`;
-
-	const choiceArgument: Record<string, unknown> = {
-		expectedAdmin: admin,
-		allocation: {
-			settlement: {
-				executor: executor,
-				settlementRef: {
-					id: resolvedSettlementId,
-					cid: null,
-				},
-				requestedAt: now.toISOString(),
-				allocateBefore: allocateDeadline,
-				settleBefore: settleDeadline,
-				meta: { values: config.ALLOCATION_META_TAG ? { tag: config.ALLOCATION_META_TAG } : {} },
-			},
-			transferLegId: resolvedTransferLegId,
-			transferLeg: {
-				sender: sender,
-				receiver: receiver || sender,
-				amount: parseFloat(parseFloat(String(amount)).toFixed(10)).toString(),
-				instrumentId: {
-					admin: admin,
-					id: assetId,
-				},
-				meta: { values: {} },
-			},
-		},
-		requestedAt: now.toISOString(),
-		inputHoldingCids: holdingCids.map(normalizeContractId),
-		extraArgs: {
-			context: { values: {} } as Record<string, unknown>,
-			meta: { values: {} },
-		},
-	};
-
-	// --- 3. Fetch AllocationFactory ---
-	if (shouldUseLedgerForMetadata()) {
-		// Localhost: resolve factory and context from ledger directly
-		if (isAmulet) {
-			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: holdingCids, transferAmount: Number(amount) });
-			if (!amuletCtx) {
-				const msg = "depositFunds: 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;
-
-			factoryContractId = normalizeContractId(externalAmuletRules.contractCid) as string;
-			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 },
-				},
-			};
-			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 {
-			// Utility token: resolve from ledger
-			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 (!allocFactory) {
-				const msg = `depositFunds: no AllocationFactory found on ledger for ${assetId}`;
-				console.error(msg);
-				return { error: msg };
-			}
-			factoryContractId = normalizeContractId(allocFactory.contractCid) as string;
-			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: [] },
-					},
-				};
-				disclosedContracts.push({
-					templateId: null,
-					contractId: instConfig.contractCid,
-					createdEventBlob: instConfig.disclosureCid,
-					synchronizerId: instConfig.synchronizerId,
-				});
-			}
-			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)
-		const factoryData = (disclosures as Record<string, unknown>)?.disclosures || disclosures || null;
-		let resolvedFactoryData = factoryData as Record<string, unknown> | null;
-
-		if (!resolvedFactoryData?.factoryId) {
-			const disclosuresResult = (await getDisclosures(sender)) as unknown as Record<string, unknown>;
-			resolvedFactoryData = disclosuresResult?.disclosures as Record<string, unknown>;
-			if (disclosuresResult?.error || !resolvedFactoryData?.factoryId) {
-				const detail = (disclosuresResult?.message as string) || (disclosuresResult?.error as string) || "missing factoryId in response";
-				const msg = `depositFunds: failed to resolve Amulet disclosures. Pass disclosures directly or ensure API access: ${detail}`;
-				console.error(msg);
-				return { error: msg };
-			}
-		}
-
-		factoryContractId = normalizeContractId(resolvedFactoryData.factoryId as string) as string;
-		const choiceContext = resolvedFactoryData.choiceContext as Record<string, unknown> | undefined;
-		choiceContextData = (choiceContext?.choiceContextData as Record<string, unknown>) || {};
-		disclosedContracts = ((choiceContext?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
-			templateId: dc.templateId,
-			contractId: dc.contractId,
-			createdEventBlob: dc.createdEventBlob,
-			synchronizerId: dc.synchronizerId,
-		}));
-	} else {
-		// Remote: use Scan API (Amulet) or Registry API (utility)
-		let factoryUrl: string;
-		let factoryHeaders: Record<string, string> = {};
-
-		if (isAmulet) {
-			factoryUrl = `${config.VALIDATOR_SCAN_API_URL}/registry/allocation-instruction/v1/allocation-factory`;
-			factoryHeaders = 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 = `depositFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
-				console.error(msg);
-				return { error: msg };
-			}
-			factoryUrl = `${registryAPI}/allocation-instruction/v1/allocation-factory`;
-		}
-
-		const factoryBody = {
-			choiceArguments: isAmulet ? {} : choiceArgument,
-			excludeDebugFields: true,
-		};
-		let factoryData: Record<string, unknown>;
-		try {
-			const factoryResponse = await axios.post(factoryUrl, factoryBody, Object.keys(factoryHeaders).length > 0 ? { headers: factoryHeaders } : undefined);
-			factoryData = factoryResponse.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 = `depositFunds: error fetching allocation factory from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
-			console.error(msg);
-			return { error: msg };
-		}
-
-		factoryContractId = normalizeContractId(factoryData?.factoryId as string) as string;
-		const choiceContext = factoryData?.choiceContext as Record<string, unknown> | undefined;
-		choiceContextData = (choiceContext?.choiceContextData as Record<string, unknown>) || {};
-		disclosedContracts = ((choiceContext?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
-			templateId: dc.templateId,
-			contractId: dc.contractId,
-			createdEventBlob: dc.createdEventBlob,
-			synchronizerId: dc.synchronizerId,
-		}));
-	}
-
-	if (!factoryContractId) {
-		const msg = "depositFunds: allocation factory response missing factoryId";
-		console.error(msg);
-		return { error: msg };
-	}
-
-	// --- 4. Build the ExerciseCommand for AllocationFactory_Allocate ---
-	(choiceArgument.extraArgs as Record<string, unknown>).context = choiceContextData;
-
-	const command = {
-		commands: [
-			{
-				ExerciseCommand: {
-					templateId: "#splice-api-token-allocation-instruction-v1:Splice.Api.Token.AllocationInstructionV1:AllocationFactory",
-					contractId: factoryContractId,
-					choice: "AllocationFactory_Allocate",
-					choiceArgument: choiceArgument,
-				},
-			},
-		],
-		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 = `depositFunds: 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 = `depositFunds: error submitting command: ${errorDetail}`;
-		console.error(msg);
-		return { error: msg };
-	}
-}
+import config from "../../src/config/index.js";
+import axios from "axios";
+import { getDisclosures } from "../api/index.js";
+import { getUserId } from "../api/tokenStore.js";
+import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "../../src/canton/walletAdapter.js";
+import { normalizeAssetId, instrumentCatalog } from "../../src/canton/instrumentCatalog.js";
+import {
+	randomUUID,
+	shouldUseLedgerForMetadata,
+	normalizeContractId,
+	resolveInstrumentDefinition,
+	getInstrumentRegistrar,
+	resolveProvider,
+	dedupeDisclosedContracts,
+	buildHeaders,
+	DEFAULT_UTILITY_CONTEXT_KEYS,
+} from "./helpers.js";
+import type { DisclosedContract, ContractMetadata } from "./helpers.js";
+import {
+	resolveAmuletContext,
+	resolveUtilityInstrumentConfiguration,
+	resolveUtilityAllocationFactory,
+	getAmuletHoldingsForParty,
+	getUtilityHoldingsForParty,
+	getUtxoCount,
+} from "../../src/canton/index.js";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const CC_FEE_RESERVE = 10;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface DepositFundsOpts {
+	sender: string;
+	receiver?: string;
+	assetId: string;
+	amount: string | number;
+	holdingCids?: string[];
+	settlementId?: string;
+	transferLegId?: string;
+	allocateBefore?: string;
+	settleBefore?: string;
+	disclosures?: Record<string, unknown>;
+	userId?: string;
+}
+
+export interface PreparedDeposit {
+	sender: string;
+	receiver: string;
+	assetId: string;
+	amount: string;
+	holdingCids: string[];
+}
+
+// ─── Deposit Functions ───────────────────────────────────────────────────────
+
+/**
+ * Prepare holdings for a deposit by selecting UTXOs from the wallet provider.
+ *
+ * Queries the provider for holdings, filters and sorts them, then greedily
+ * selects until the requested amount is covered.
+ */
+export async function prepareDepositHoldings(
+	amount: number | string,
+	symbol: string,
+): Promise<PreparedDeposit | { error: string; data?: Record<string, unknown> }> {
+	const provider = resolveProvider(null);
+	if (!provider && !config.VALIDATOR_SCAN_API_URL) {
+		return { error: "prepareDepositHoldings: wallet provider is required to prepare holdings. Connect a wallet adapter." };
+	}
+
+	const party = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
+	if (!party) {
+		return { error: "prepareDepositHoldings: party ID is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID." };
+	}
+
+	const assetId = normalizeAssetId(symbol);
+
+	if (!instrumentCatalog[assetId]) {
+		return { error: `prepareDepositHoldings: unsupported symbol "${symbol}"` };
+	}
+
+	const requiredAmount = parseFloat(String(amount));
+	if (isNaN(requiredAmount) || requiredAmount <= 0) {
+		return { error: "prepareDepositHoldings: amount must be a positive number" };
+	}
+
+	const isAmulet = assetId === "Amulet";
+	const holdings = isAmulet
+		? await getAmuletHoldingsForParty(party, false, provider)
+		: await getUtilityHoldingsForParty(party, false, provider);
+
+	if (!holdings || (holdings as unknown[]).length === 0) {
+		return { error: `prepareDepositHoldings: no holdings found for party ${party}` };
+	}
+
+	// Parse holdings into { contractId, quantity } and filter out locked
+	const parsed: { contractId: string; quantity: number }[] = [];
+	for (const h of holdings as Record<string, unknown>[]) {
+		const contractEntry = h.contractEntry as Record<string, unknown> | undefined;
+		const jsActive = contractEntry?.JsActiveContract as Record<string, unknown> | undefined;
+		const createdEvent = jsActive?.createdEvent as Record<string, unknown> | undefined;
+		if (!createdEvent) continue;
+
+		const createArg = createdEvent.createArgument as Record<string, unknown> | undefined;
+
+		// Skip asset types that don't match the requested symbol
+		const instrument = createArg?.instrument as Record<string, unknown> | undefined;
+		const createdAssetId = (instrument?.id as string) || (isAmulet ? "Amulet" : null);
+		if (createdAssetId !== assetId) continue;
+
+		// Skip locked utility holdings
+		if (!isAmulet && createArg?.lock) continue;
+
+		const amountField = createArg?.amount as Record<string, unknown> | string | undefined;
+		const quantity = isAmulet
+			? parseFloat(((amountField as Record<string, unknown>)?.initialAmount as string) || "0")
+			: parseFloat((amountField as string) || "0");
+
+		if (quantity <= 0) continue;
+
+		parsed.push({
+			contractId: normalizeContractId(createdEvent.contractId as string) as string,
+			quantity,
+		});
+	}
+
+	if (parsed.length === 0) {
+		return { error: `prepareDepositHoldings: no unlocked holdings found for ${assetId}` };
+	}
+
+	// Sort descending — largest first
+	parsed.sort((a, b) => b.quantity - a.quantity);
+
+	// Greedily select until we cover the required amount
+	const selected: string[] = [];
+	let cumulative = 0;
+	for (const holding of parsed) {
+		selected.push(holding.contractId);
+		cumulative += holding.quantity;
+		if (cumulative >= requiredAmount) break;
+	}
+
+	if (cumulative < requiredAmount) {
+		return {
+			error: `prepareDepositHoldings: insufficient balance. Have ${cumulative}, need ${requiredAmount}`,
+			data: { totalBalance: cumulative, requiredAmount },
+		};
+	}
+
+	const formattedAmount = parseFloat(parseFloat(String(amount)).toFixed(10)).toString();
+
+	return {
+		sender: party,
+		receiver: party,
+		assetId,
+		amount: formattedAmount,
+		holdingCids: selected,
+	};
+}
+
+/**
+ * High-level deposit helper.
+ *
+ * Wraps `prepareDepositHoldings` and `depositFunds` into a single call.
+ * Validates the user has sufficient balance and reserves 10 CC for transaction fees.
+ *
+ * Requires:
+ * - Wallet adapter (for reading balances and submitting)
+ * - API connection (for disclosures on Amulet deposits)
+ */
+export async function deposit(
+	amount: number | string,
+	symbol: string,
+): Promise<Record<string, unknown>> {
+	if (!getWalletAdapter()) {
+		return { error: "deposit: wallet adapter is required. Call setWalletAdapter() first." };
+	}
+
+	const party = getAdapterPartyId();
+	if (!party) {
+		return { error: "deposit: could not resolve party ID from wallet adapter." };
+	}
+
+	// Pay any outstanding network gas first so the balance check below is accurate.
+	await payDueGasIfAny();
+
+	const assetId = normalizeAssetId(symbol);
+	if (!instrumentCatalog[assetId]) {
+		return { error: `deposit: unsupported symbol "${symbol}"` };
+	}
+
+	const depositAmount = parseFloat(String(amount));
+	if (isNaN(depositAmount) || depositAmount <= 0) {
+		return { error: "deposit: amount must be a positive number" };
+	}
+
+	const isAmulet = assetId === "Amulet";
+	const provider = resolveProvider(null);
+
+	// Check CC balance — required for all deposits (fees)
+	const ccBalance = await getUtxoCount(party, "Amulet", provider);
+	const availableCC = ccBalance.unlockedBalance || 0;
+
+	if (isAmulet) {
+		// CC deposit: user needs depositAmount + 10 CC fee reserve
+		const maxDeposit = availableCC - CC_FEE_RESERVE;
+		if (maxDeposit <= 0) {
+			return {
+				error: `deposit: insufficient CC balance. You have ${availableCC} CC but need at least ${CC_FEE_RESERVE} CC reserved for fees.`,
+				data: { balance: availableCC, feeReserve: CC_FEE_RESERVE, maxDeposit: 0 },
+			};
+		}
+		if (depositAmount > maxDeposit) {
+			return {
+				error: `deposit: amount exceeds maximum. You have ${availableCC} CC, ${CC_FEE_RESERVE} CC is reserved for fees, max deposit is ${maxDeposit} CC.`,
+				data: { balance: availableCC, feeReserve: CC_FEE_RESERVE, maxDeposit },
+			};
+		}
+	} else {
+		// Utility deposit: user needs 10 CC for fees + enough of the utility token
+		if (availableCC < CC_FEE_RESERVE) {
+			return {
+				error: `deposit: 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 },
+			};
+		}
+
+		const utilityBalance = await getUtxoCount(party, assetId, provider);
+		const availableUtility = utilityBalance.unlockedBalance || 0;
+		if (depositAmount > availableUtility) {
+			return {
+				error: `deposit: insufficient ${assetId} balance. You have ${availableUtility} ${assetId}, need ${depositAmount}.`,
+				data: { balance: availableUtility, requested: depositAmount },
+			};
+		}
+	}
+
+	// Step 1: Prepare holdings (select UTXOs)
+	console.log(`deposit: preparing ${depositAmount} ${assetId} for deposit...`);
+	const prepared = await prepareDepositHoldings(depositAmount, assetId);
+	if ("error" in prepared) {
+		return prepared;
+	}
+
+	// Step 2: Execute deposit (allocate holdings)
+	console.log(`deposit: submitting deposit with ${prepared.holdingCids.length} holding(s)...`);
+	const result = await depositFunds(prepared);
+	if (result?.error) {
+		return result;
+	}
+
+	console.log(`deposit: ${depositAmount} ${assetId} deposited successfully`);
+	return result;
+}
+
+/**
+ * Create a CIP-56 Allocation.
+ * Fetches the AllocationFactory, then exercises AllocationFactory_Allocate
+ * to lock holdings for a settlement leg.
+ *
+ * Three resolution paths:
+ * 1. Localhost: resolve factory and context from ledger directly
+ * 2. Amulet via disclosures (FE/proxy path — no Scan API access)
+ * 3. Remote: Scan API / Registry API
+ */
+export async function depositFunds(
+	opts: DepositFundsOpts,
+	returnCommand = false,
+): Promise<Record<string, unknown>> {
+	const { sender, receiver, amount, holdingCids = [], settlementId, transferLegId, allocateBefore, settleBefore, disclosures, userId } = opts;
+	const assetId = normalizeAssetId(opts.assetId);
+
+	if (!sender || !assetId || !amount) {
+		const msg = "depositFunds: sender, assetId, and amount are required";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	const isAmulet = assetId === "Amulet";
+
+	// --- 1. Resolve admin and factory ---
+	let admin: string;
+	let factoryContractId: string | undefined;
+	let choiceContextData: Record<string, unknown> = {};
+	let disclosedContracts: DisclosedContract[] = [];
+
+	if (isAmulet) {
+		admin = config.VALIDATOR_DSO_PARTY_ID;
+	} else {
+		const instrumentDef = resolveInstrumentDefinition(assetId);
+		const networkContracts = instrumentDef?.[config.NETWORK] as Record<string, unknown> | undefined;
+		admin = (networkContracts?.registrar as string) || getInstrumentRegistrar(assetId) || config.VALIDATOR_REGISTRAR_PARTY_ID;
+	}
+
+	// --- 2. Build the choice arguments upfront ---
+	const now = new Date();
+	const allocateDeadline = allocateBefore || new Date(now.getTime() + 60 * 60 * 1000).toISOString();
+	const settleDeadline = settleBefore || new Date(now.getTime() + 2 * 60 * 60 * 1000).toISOString();
+	const executor = config.TEMPLE_PARTY_ID;
+	const resolvedTransferLegId = transferLegId || randomUUID();
+	const resolvedSettlementId = settlementId || `SR-${randomUUID()}`;
+
+	const choiceArgument: Record<string, unknown> = {
+		expectedAdmin: admin,
+		allocation: {
+			settlement: {
+				executor: executor,
+				settlementRef: {
+					id: resolvedSettlementId,
+					cid: null,
+				},
+				requestedAt: now.toISOString(),
+				allocateBefore: allocateDeadline,
+				settleBefore: settleDeadline,
+				meta: { values: config.ALLOCATION_META_TAG ? { tag: config.ALLOCATION_META_TAG } : {} },
+			},
+			transferLegId: resolvedTransferLegId,
+			transferLeg: {
+				sender: sender,
+				receiver: receiver || sender,
+				amount: parseFloat(parseFloat(String(amount)).toFixed(10)).toString(),
+				instrumentId: {
+					admin: admin,
+					id: assetId,
+				},
+				meta: { values: {} },
+			},
+		},
+		requestedAt: now.toISOString(),
+		inputHoldingCids: holdingCids.map(normalizeContractId),
+		extraArgs: {
+			context: { values: {} } as Record<string, unknown>,
+			meta: { values: {} },
+		},
+	};
+
+	// --- 3. Fetch AllocationFactory ---
+	if (shouldUseLedgerForMetadata()) {
+		// Localhost: resolve factory and context from ledger directly
+		if (isAmulet) {
+			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: holdingCids, transferAmount: Number(amount) });
+			if (!amuletCtx) {
+				const msg = "depositFunds: 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;
+
+			factoryContractId = normalizeContractId(externalAmuletRules.contractCid) as string;
+			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 },
+				},
+			};
+			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 {
+			// Utility token: resolve from ledger
+			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 (!allocFactory) {
+				const msg = `depositFunds: no AllocationFactory found on ledger for ${assetId}`;
+				console.error(msg);
+				return { error: msg };
+			}
+			factoryContractId = normalizeContractId(allocFactory.contractCid) as string;
+			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: [] },
+					},
+				};
+				disclosedContracts.push({
+					templateId: null,
+					contractId: instConfig.contractCid,
+					createdEventBlob: instConfig.disclosureCid,
+					synchronizerId: instConfig.synchronizerId,
+				});
+			}
+			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)
+		const factoryData = (disclosures as Record<string, unknown>)?.disclosures || disclosures || null;
+		let resolvedFactoryData = factoryData as Record<string, unknown> | null;
+
+		if (!resolvedFactoryData?.factoryId) {
+			const disclosuresResult = (await getDisclosures(sender)) as unknown as Record<string, unknown>;
+			resolvedFactoryData = disclosuresResult?.disclosures as Record<string, unknown>;
+			if (disclosuresResult?.error || !resolvedFactoryData?.factoryId) {
+				const detail = (disclosuresResult?.message as string) || (disclosuresResult?.error as string) || "missing factoryId in response";
+				const msg = `depositFunds: failed to resolve Amulet disclosures. Pass disclosures directly or ensure API access: ${detail}`;
+				console.error(msg);
+				return { error: msg };
+			}
+		}
+
+		factoryContractId = normalizeContractId(resolvedFactoryData.factoryId as string) as string;
+		const choiceContext = resolvedFactoryData.choiceContext as Record<string, unknown> | undefined;
+		choiceContextData = (choiceContext?.choiceContextData as Record<string, unknown>) || {};
+		disclosedContracts = ((choiceContext?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+	} else {
+		// Remote: use Scan API (Amulet) or Registry API (utility)
+		let factoryUrl: string;
+		let factoryHeaders: Record<string, string> = {};
+
+		if (isAmulet) {
+			factoryUrl = `${config.VALIDATOR_SCAN_API_URL}/registry/allocation-instruction/v1/allocation-factory`;
+			factoryHeaders = 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 = `depositFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
+				console.error(msg);
+				return { error: msg };
+			}
+			factoryUrl = `${registryAPI}/allocation-instruction/v1/allocation-factory`;
+		}
+
+		const factoryBody = {
+			choiceArguments: isAmulet ? {} : choiceArgument,
+			excludeDebugFields: true,
+		};
+		let factoryData: Record<string, unknown>;
+		try {
+			const factoryResponse = await axios.post(factoryUrl, factoryBody, Object.keys(factoryHeaders).length > 0 ? { headers: factoryHeaders } : undefined);
+			factoryData = factoryResponse.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 = `depositFunds: error fetching allocation factory from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
+			console.error(msg);
+			return { error: msg };
+		}
+
+		factoryContractId = normalizeContractId(factoryData?.factoryId as string) as string;
+		const choiceContext = factoryData?.choiceContext as Record<string, unknown> | undefined;
+		choiceContextData = (choiceContext?.choiceContextData as Record<string, unknown>) || {};
+		disclosedContracts = ((choiceContext?.disclosedContracts as DisclosedContract[]) || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+	}
+
+	if (!factoryContractId) {
+		const msg = "depositFunds: allocation factory response missing factoryId";
+		console.error(msg);
+		return { error: msg };
+	}
+
+	// --- 4. Build the ExerciseCommand for AllocationFactory_Allocate ---
+	(choiceArgument.extraArgs as Record<string, unknown>).context = choiceContextData;
+
+	const command = {
+		commands: [
+			{
+				ExerciseCommand: {
+					templateId: "#splice-api-token-allocation-instruction-v1:Splice.Api.Token.AllocationInstructionV1:AllocationFactory",
+					contractId: factoryContractId,
+					choice: "AllocationFactory_Allocate",
+					choiceArgument: choiceArgument,
+				},
+			},
+		],
+		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 = `depositFunds: 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 = `depositFunds: error submitting command: ${errorDetail}`;
+		console.error(msg);
+		return { error: msg };
+	}
+}