@temple-digital-group/temple-canton-js 1.0.39 → 1.0.40

package/dist/canton/deposits.d.ts

@@ -0,0 +1,52 @@
+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[];
+}
+/**
+ * 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 declare function prepareDepositHoldings(amount: number | string, symbol: string): Promise<PreparedDeposit | {
+    error: string;
+    data?: Record<string, unknown>;
+}>;
+/**
+ * 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 declare function deposit(amount: number | string, symbol: string): Promise<Record<string, unknown>>;
+/**
+ * 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 declare function depositFunds(opts: DepositFundsOpts, returnCommand?: boolean): Promise<Record<string, unknown>>;

package/dist/canton/deposits.js

@@ -0,0 +1,466 @@
+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 { resolveAmuletContext, resolveUtilityInstrumentConfiguration, resolveUtilityAllocationFactory, getAmuletHoldingsForParty, getUtilityHoldingsForParty, getUtxoCount, } from "../../src/canton/index.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const CC_FEE_RESERVE = 10;
+// ─── 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, symbol) {
+    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.length === 0) {
+        return { error: `prepareDepositHoldings: no holdings found for party ${party}` };
+    }
+    // Parse holdings into { contractId, quantity } and filter out locked
+    const parsed = [];
+    for (const h of holdings) {
+        const contractEntry = h.contractEntry;
+        const jsActive = contractEntry?.JsActiveContract;
+        const createdEvent = jsActive?.createdEvent;
+        if (!createdEvent)
+            continue;
+        const createArg = createdEvent.createArgument;
+        // Skip asset types that don't match the requested symbol
+        const instrument = createArg?.instrument;
+        const createdAssetId = instrument?.id || (isAmulet ? "Amulet" : null);
+        if (createdAssetId !== assetId)
+            continue;
+        // Skip locked utility holdings
+        if (!isAmulet && createArg?.lock)
+            continue;
+        const amountField = createArg?.amount;
+        const quantity = isAmulet
+            ? parseFloat(amountField?.initialAmount || "0")
+            : parseFloat(amountField || "0");
+        if (quantity <= 0)
+            continue;
+        parsed.push({
+            contractId: normalizeContractId(createdEvent.contractId),
+            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 = [];
+    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, symbol) {
+    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, returnCommand = false) {
+    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;
+    let factoryContractId;
+    let choiceContextData = {};
+    let disclosedContracts = [];
+    if (isAmulet) {
+        admin = config.VALIDATOR_DSO_PARTY_ID;
+    }
+    else {
+        const instrumentDef = resolveInstrumentDefinition(assetId);
+        const networkContracts = instrumentDef?.[config.NETWORK];
+        admin = networkContracts?.registrar || 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 = {
+        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: {} },
+            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;
+            const contextKeys = ctx.contextKeys;
+            const amuletRules = ctx.amuletRules;
+            const openMiningRound = ctx.openMiningRound;
+            const featuredAppRight = ctx.featuredAppRight;
+            const externalAmuletRules = ctx.externalAmuletRules;
+            factoryContractId = normalizeContractId(externalAmuletRules.contractCid);
+            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];
+            const registrar = networkDef?.registrar || 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);
+            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?.disclosures || disclosures || null;
+        let resolvedFactoryData = factoryData;
+        if (!resolvedFactoryData?.factoryId) {
+            const disclosuresResult = (await getDisclosures(sender));
+            resolvedFactoryData = disclosuresResult?.disclosures;
+            if (disclosuresResult?.error || !resolvedFactoryData?.factoryId) {
+                const detail = disclosuresResult?.message || disclosuresResult?.error || "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);
+        const choiceContext = resolvedFactoryData.choiceContext;
+        choiceContextData = choiceContext?.choiceContextData || {};
+        disclosedContracts = (choiceContext?.disclosedContracts || []).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;
+        let factoryHeaders = {};
+        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];
+            const registryAPI = networkContracts?.registryAPI;
+            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;
+        try {
+            const factoryResponse = await axios.post(factoryUrl, factoryBody, Object.keys(factoryHeaders).length > 0 ? { headers: factoryHeaders } : undefined);
+            factoryData = factoryResponse.data;
+        }
+        catch (error) {
+            const axiosErr = error;
+            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);
+        const choiceContext = factoryData?.choiceContext;
+        choiceContextData = choiceContext?.choiceContextData || {};
+        disclosedContracts = (choiceContext?.disclosedContracts || []).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.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));
+        }
+        catch (error) {
+            const msg = `depositFunds: wallet adapter submission failed: ${error.message}`;
+            console.error(msg);
+            return { error: msg };
+        }
+    }
+    const headers = await buildHeaders();
+    try {
+        const response = await axios.post(endpoint, command, { headers });
+        return response.data;
+    }
+    catch (error) {
+        const axiosErr = error;
+        const errorData = axiosErr?.response?.data;
+        const errorDetail = errorData ? JSON.stringify(errorData, null, 2) : axiosErr.message;
+        const msg = `depositFunds: error submitting command: ${errorDetail}`;
+        console.error(msg);
+        return { error: msg };
+    }
+}

package/dist/canton/withdrawals.js

@@ -16,7 +16,8 @@ import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
  * 3. Remote: Scan API / Registry API
  */
 export async function finalizeWithdrawFunds(opts, returnCommand = false) {
-    const { allocationId, sender: senderOpt, assetId, disclosures, userId } = opts;
+    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";

package/package.json

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

package/src/canton/index.js

@@ -2915,8 +2915,8 @@ export async function mergeAmuletHoldingsForParty(party, returnCommand = false,
 		return null;
 	}
 
-	// Sort by quantity ascending (smallest first) and apply maxUtxos limit
-	contracts.sort((a, b) => a.quantity - b.quantity);
+	// Sort by quantity descending (largest first) and apply maxUtxos limit
+	contracts.sort((a, b) => b.quantity - a.quantity);
 	const selectedContracts = maxUtxos && maxUtxos < contracts.length ? contracts.slice(0, maxUtxos) : contracts;
 
 	if (selectedContracts.length < 2) {
@@ -3217,9 +3217,9 @@ export async function mergeUtilityHoldingsForParty(party, utilityAsset, returnCo
 	const finalHolders = [...new Set(contracts.map(c => c.holder).filter(Boolean))];
 	const holder = finalHolders[0] || party; // Use the holder from filtered holdings
 
-	// Sort ascending by quantity so smallest UTXOs are merged first
+	// Sort descending by quantity so largest UTXOs are merged first
 	if (maxUtxos) {
-		contracts.sort((a, b) => a.quantity - b.quantity);
+		contracts.sort((a, b) => b.quantity - a.quantity);
 		if (contracts.length > maxUtxos) {
 			contracts.length = maxUtxos;
 		}