@temple-digital-group/temple-canton-js 2.0.3 → 2.0.4-beta.0

package/dist/canton/deposits.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Compute the maximum safe lock-expiration time for an Amulet allocation,
+ * given the amulet amount and current network parameters.
+ *
+ * Mirrors Splice.Expiry.isAmuletExpired + MaxLockExpirationForFreshAmulet.
+ *
+ * @param amount             Amulet amount being locked (e.g. 0.001)
+ * @param cfg.holdingFeeRate Per-round holding fee rate (e.g. 0.00002)
+ * @param cfg.tickDurationSec Round duration in seconds (e.g. 600)
+ * @param cfg.currentRound   Current open mining round number
+ * @param cfg.currentRoundOpensAt When that round opened
+ * @param cfg.safetyTicks    Subtract this many ticks as buffer (default 1)
+ * @returns Latest safe lock expiry Date, or null if already unsafe.
+ */
+export declare function maxLockExpirationForFreshAmulet(amount: number | string, cfg: {
+    holdingFeeRate: number | string;
+    tickDurationSec: number;
+    currentRound: number | bigint;
+    currentRoundOpensAt: Date | string | number;
+    safetyTicks?: number;
+}): Date | null;
 export interface DepositFundsOpts {
     sender: string;
     receiver?: string;

package/dist/canton/deposits.js

@@ -5,9 +5,109 @@ import { getUserId } from "../api/tokenStore.js";
 import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "../../src/canton/walletAdapter.js";
 import { normalizeAssetId, instrumentCatalog, instrumentIdToSymbol, resolveOnChainInstrumentId } 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";
+import { resolveAmuletContext, resolveUtilityInstrumentConfiguration, resolveUtilityAllocationFactory, getAmuletHoldingsForParty, getUtilityHoldingsForParty, getUtxoCount, getAmuletRules, getOpenMiningRounds, } from "../../src/canton/index.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const CC_FEE_RESERVE = 10;
+// ─── Amulet Expiry Helpers ───────────────────────────────────────────────────
+/**
+ * Compute the maximum safe lock-expiration time for an Amulet allocation,
+ * given the amulet amount and current network parameters.
+ *
+ * Mirrors Splice.Expiry.isAmuletExpired + MaxLockExpirationForFreshAmulet.
+ *
+ * @param amount             Amulet amount being locked (e.g. 0.001)
+ * @param cfg.holdingFeeRate Per-round holding fee rate (e.g. 0.00002)
+ * @param cfg.tickDurationSec Round duration in seconds (e.g. 600)
+ * @param cfg.currentRound   Current open mining round number
+ * @param cfg.currentRoundOpensAt When that round opened
+ * @param cfg.safetyTicks    Subtract this many ticks as buffer (default 1)
+ * @returns Latest safe lock expiry Date, or null if already unsafe.
+ */
+export function maxLockExpirationForFreshAmulet(amount, cfg) {
+    const amt = Number(amount);
+    const rate = Number(cfg.holdingFeeRate);
+    const tickSec = Number(cfg.tickDurationSec);
+    const currentRound = Number(cfg.currentRound);
+    const opensAt = new Date(cfg.currentRoundOpensAt).getTime();
+    const safetyTicks = cfg.safetyTicks ?? 1;
+    if (!(amt > 0) || !(rate > 0) || !(tickSec > 0))
+        return null;
+    // Rounds the amulet can survive holding-fee drain
+    const roundsUntilExpired = Math.ceil(amt / rate);
+    // DAML: amulet is "definitely expired" once currentRound >= expiresAtRound + 2.
+    // Assume freshly minted → createdAtRound = currentRound.
+    const expiresAtRound = currentRound + roundsUntilExpired;
+    const effectiveExpiringRound = expiresAtRound + 2;
+    if (effectiveExpiringRound <= currentRound)
+        return null;
+    // Time at which `effectiveExpiringRound` opens:
+    //   opensAt(current) + (target - current - 1) * tickDuration
+    const roundsInFuture = Math.max(0, effectiveExpiringRound - currentRound - 1);
+    const expirationMs = opensAt + roundsInFuture * tickSec * 1000;
+    // Safety buffer: lock must end strictly before amulet would expire
+    const safeMs = expirationMs - safetyTicks * tickSec * 1000;
+    if (safeMs <= Date.now())
+        return null;
+    return new Date(safeMs);
+}
+/**
+ * Fetch the parameters needed for maxLockExpirationForFreshAmulet from on-chain data.
+ * AmuletRules is long-lived and cached internally; OpenMiningRound should be refreshed per round.
+ * Returns null if data cannot be fetched.
+ */
+async function fetchAmuletExpiryParams(dso) {
+    try {
+        const [amuletRulesData, miningRoundsData] = await Promise.all([
+            getAmuletRules(dso),
+            getOpenMiningRounds(dso),
+        ]);
+        const payload = amuletRulesData?.amulet_rules?.contract;
+        const transferConfig = payload?.payload?.transferConfig;
+        if (!transferConfig)
+            return null;
+        const holdingFeeRate = Number(transferConfig?.holdingFee?.rate);
+        // tickDuration may be { microseconds: "N" } (DAML RelTime) or a plain seconds number
+        const rawTick = transferConfig?.tickDuration;
+        let tickDurationSec;
+        if (rawTick && typeof rawTick === "object" && "microseconds" in rawTick) {
+            tickDurationSec = Number(rawTick.microseconds) / 1000000;
+        }
+        else {
+            tickDurationSec = Number(rawTick);
+        }
+        if (!holdingFeeRate || !tickDurationSec)
+            return null;
+        // Find the currently open mining round
+        const now = new Date();
+        const rounds = miningRoundsData?.open_mining_rounds ?? [];
+        let selectedRoundPayload = null;
+        for (const entry of rounds) {
+            const rPayload = entry.contract?.payload;
+            const opensAt = new Date(rPayload?.opensAt);
+            const targetClosesAt = new Date(rPayload?.targetClosesAt);
+            if (now >= opensAt && now <= targetClosesAt) {
+                selectedRoundPayload = rPayload;
+                break;
+            }
+        }
+        if (!selectedRoundPayload && rounds.length > 0) {
+            selectedRoundPayload = rounds[0].contract?.payload;
+        }
+        if (!selectedRoundPayload)
+            return null;
+        const roundField = selectedRoundPayload?.round;
+        const currentRound = Number(typeof roundField === "object" && roundField !== null
+            ? roundField.number
+            : roundField);
+        const currentRoundOpensAt = selectedRoundPayload?.opensAt;
+        if (!currentRoundOpensAt)
+            return null;
+        return { holdingFeeRate, tickDurationSec, currentRound, currentRoundOpensAt };
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Deposit Functions ───────────────────────────────────────────────────────
 /**
  * Prepare holdings for a deposit by selecting UTXOs from the wallet provider.
@@ -213,8 +313,34 @@ export async function depositFunds(opts, returnCommand = false) {
     }
     // --- 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 ONE_DAY_MS = 24 * 60 * 60 * 1000;
+    let allocateDeadline;
+    let settleDeadline;
+    if (isAmulet && (!allocateBefore || !settleBefore)) {
+        // Compute the safe deadline from on-chain fee params to avoid
+        // "amulet expires before lock" errors on small amounts.
+        const expiryParams = await fetchAmuletExpiryParams(config.VALIDATOR_DSO_PARTY_ID);
+        const maxExpiry = expiryParams ? maxLockExpirationForFreshAmulet(amount, expiryParams) : null;
+        if (maxExpiry) {
+            // settleBefore = safe max expiry; allocateBefore = halfway between now and settleBefore
+            const midMs = now.getTime() + (maxExpiry.getTime() - now.getTime()) / 2;
+            allocateDeadline = allocateBefore || new Date(midMs).toISOString();
+            settleDeadline = settleBefore || maxExpiry.toISOString();
+        }
+        else {
+            // Fallback heuristic if on-chain params are unavailable
+            const isSmallAmulet = parseFloat(String(amount)) <= 10;
+            const defaultWindowMs = isSmallAmulet ? 2 * ONE_DAY_MS : 60 * ONE_DAY_MS;
+            allocateDeadline = allocateBefore || new Date(now.getTime() + defaultWindowMs / 2).toISOString();
+            settleDeadline = settleBefore || new Date(now.getTime() + defaultWindowMs).toISOString();
+        }
+    }
+    else {
+        // Utility tokens or caller-supplied deadlines — use fixed window or provided values
+        const defaultWindowMs = 60 * ONE_DAY_MS;
+        allocateDeadline = allocateBefore || new Date(now.getTime() + defaultWindowMs / 2).toISOString();
+        settleDeadline = settleBefore || new Date(now.getTime() + defaultWindowMs).toISOString();
+    }
     const executor = config.TEMPLE_PARTY_ID;
     const resolvedTransferLegId = transferLegId || randomUUID();
     const resolvedSettlementId = settlementId || `SR-${randomUUID()}`;

package/package.json

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

package/src/canton/deposits.ts

@@ -23,12 +23,140 @@ import {
 	getAmuletHoldingsForParty,
 	getUtilityHoldingsForParty,
 	getUtxoCount,
+	getAmuletRules,
+	getOpenMiningRounds,
 } from "../../src/canton/index.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 const CC_FEE_RESERVE = 10;
 
+// ─── Amulet Expiry Helpers ───────────────────────────────────────────────────
+
+/**
+ * Compute the maximum safe lock-expiration time for an Amulet allocation,
+ * given the amulet amount and current network parameters.
+ *
+ * Mirrors Splice.Expiry.isAmuletExpired + MaxLockExpirationForFreshAmulet.
+ *
+ * @param amount             Amulet amount being locked (e.g. 0.001)
+ * @param cfg.holdingFeeRate Per-round holding fee rate (e.g. 0.00002)
+ * @param cfg.tickDurationSec Round duration in seconds (e.g. 600)
+ * @param cfg.currentRound   Current open mining round number
+ * @param cfg.currentRoundOpensAt When that round opened
+ * @param cfg.safetyTicks    Subtract this many ticks as buffer (default 1)
+ * @returns Latest safe lock expiry Date, or null if already unsafe.
+ */
+export function maxLockExpirationForFreshAmulet(
+	amount: number | string,
+	cfg: {
+		holdingFeeRate: number | string;
+		tickDurationSec: number;
+		currentRound: number | bigint;
+		currentRoundOpensAt: Date | string | number;
+		safetyTicks?: number;
+	},
+): Date | null {
+	const amt = Number(amount);
+	const rate = Number(cfg.holdingFeeRate);
+	const tickSec = Number(cfg.tickDurationSec);
+	const currentRound = Number(cfg.currentRound);
+	const opensAt = new Date(cfg.currentRoundOpensAt).getTime();
+	const safetyTicks = cfg.safetyTicks ?? 1;
+
+	if (!(amt > 0) || !(rate > 0) || !(tickSec > 0)) return null;
+
+	// Rounds the amulet can survive holding-fee drain
+	const roundsUntilExpired = Math.ceil(amt / rate);
+
+	// DAML: amulet is "definitely expired" once currentRound >= expiresAtRound + 2.
+	// Assume freshly minted → createdAtRound = currentRound.
+	const expiresAtRound = currentRound + roundsUntilExpired;
+	const effectiveExpiringRound = expiresAtRound + 2;
+
+	if (effectiveExpiringRound <= currentRound) return null;
+
+	// Time at which `effectiveExpiringRound` opens:
+	//   opensAt(current) + (target - current - 1) * tickDuration
+	const roundsInFuture = Math.max(0, effectiveExpiringRound - currentRound - 1);
+	const expirationMs = opensAt + roundsInFuture * tickSec * 1000;
+
+	// Safety buffer: lock must end strictly before amulet would expire
+	const safeMs = expirationMs - safetyTicks * tickSec * 1000;
+
+	if (safeMs <= Date.now()) return null;
+	return new Date(safeMs);
+}
+
+interface AmuletExpiryParams {
+	holdingFeeRate: number;
+	tickDurationSec: number;
+	currentRound: number;
+	currentRoundOpensAt: string;
+}
+
+/**
+ * Fetch the parameters needed for maxLockExpirationForFreshAmulet from on-chain data.
+ * AmuletRules is long-lived and cached internally; OpenMiningRound should be refreshed per round.
+ * Returns null if data cannot be fetched.
+ */
+async function fetchAmuletExpiryParams(dso: string): Promise<AmuletExpiryParams | null> {
+	try {
+		const [amuletRulesData, miningRoundsData] = await Promise.all([
+			getAmuletRules(dso) as Promise<Record<string, unknown>>,
+			getOpenMiningRounds(dso) as Promise<Record<string, unknown>>,
+		]);
+
+		const payload = (amuletRulesData?.amulet_rules as Record<string, unknown>)?.contract as Record<string, unknown>;
+		const transferConfig = (payload?.payload as Record<string, unknown>)?.transferConfig as Record<string, unknown>;
+		if (!transferConfig) return null;
+
+		const holdingFeeRate = Number((transferConfig?.holdingFee as Record<string, unknown>)?.rate);
+
+		// tickDuration may be { microseconds: "N" } (DAML RelTime) or a plain seconds number
+		const rawTick = transferConfig?.tickDuration;
+		let tickDurationSec: number;
+		if (rawTick && typeof rawTick === "object" && "microseconds" in (rawTick as object)) {
+			tickDurationSec = Number((rawTick as Record<string, unknown>).microseconds) / 1_000_000;
+		} else {
+			tickDurationSec = Number(rawTick);
+		}
+
+		if (!holdingFeeRate || !tickDurationSec) return null;
+
+		// Find the currently open mining round
+		const now = new Date();
+		const rounds = (miningRoundsData?.open_mining_rounds as Record<string, unknown>[]) ?? [];
+		let selectedRoundPayload: Record<string, unknown> | null = null;
+		for (const entry of rounds) {
+			const rPayload = (entry.contract as Record<string, unknown>)?.payload as Record<string, unknown>;
+			const opensAt = new Date(rPayload?.opensAt as string);
+			const targetClosesAt = new Date(rPayload?.targetClosesAt as string);
+			if (now >= opensAt && now <= targetClosesAt) {
+				selectedRoundPayload = rPayload;
+				break;
+			}
+		}
+		if (!selectedRoundPayload && rounds.length > 0) {
+			selectedRoundPayload = (rounds[0].contract as Record<string, unknown>)?.payload as Record<string, unknown>;
+		}
+		if (!selectedRoundPayload) return null;
+
+		const roundField = selectedRoundPayload?.round;
+		const currentRound = Number(
+			typeof roundField === "object" && roundField !== null
+				? (roundField as Record<string, unknown>).number
+				: roundField,
+		);
+		const currentRoundOpensAt = selectedRoundPayload?.opensAt as string;
+		if (!currentRoundOpensAt) return null;
+
+		return { holdingFeeRate, tickDurationSec, currentRound, currentRoundOpensAt };
+	} catch {
+		return null;
+	}
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 export interface DepositFundsOpts {
@@ -296,8 +424,33 @@ export async function depositFunds(
 
 	// --- 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 ONE_DAY_MS = 24 * 60 * 60 * 1000;
+	let allocateDeadline: string;
+	let settleDeadline: string;
+
+	if (isAmulet && (!allocateBefore || !settleBefore)) {
+		// Compute the safe deadline from on-chain fee params to avoid
+		// "amulet expires before lock" errors on small amounts.
+		const expiryParams = await fetchAmuletExpiryParams(config.VALIDATOR_DSO_PARTY_ID);
+		const maxExpiry = expiryParams ? maxLockExpirationForFreshAmulet(amount, expiryParams) : null;
+		if (maxExpiry) {
+			// settleBefore = safe max expiry; allocateBefore = halfway between now and settleBefore
+			const midMs = now.getTime() + (maxExpiry.getTime() - now.getTime()) / 2;
+			allocateDeadline = allocateBefore || new Date(midMs).toISOString();
+			settleDeadline = settleBefore || maxExpiry.toISOString();
+		} else {
+			// Fallback heuristic if on-chain params are unavailable
+			const isSmallAmulet = parseFloat(String(amount)) <= 10;
+			const defaultWindowMs = isSmallAmulet ? 2 * ONE_DAY_MS : 60 * ONE_DAY_MS;
+			allocateDeadline = allocateBefore || new Date(now.getTime() + defaultWindowMs / 2).toISOString();
+			settleDeadline = settleBefore || new Date(now.getTime() + defaultWindowMs).toISOString();
+		}
+	} else {
+		// Utility tokens or caller-supplied deadlines — use fixed window or provided values
+		const defaultWindowMs = 60 * ONE_DAY_MS;
+		allocateDeadline = allocateBefore || new Date(now.getTime() + defaultWindowMs / 2).toISOString();
+		settleDeadline = settleBefore || new Date(now.getTime() + defaultWindowMs).toISOString();
+	}
 	const executor = config.TEMPLE_PARTY_ID;
 	const resolvedTransferLegId = transferLegId || randomUUID();
 	const resolvedSettlementId = settlementId || `SR-${randomUUID()}`;

package/src/canton/index.d.ts

@@ -39,3 +39,7 @@ export function getUtxoCount(
 	largestUnlocked: number;
 	unlockedBalance: number;
 }>;
+
+export function getAmuletRules(dso: string, returnCommand?: boolean): Promise<Record<string, unknown> | null>;
+
+export function getOpenMiningRounds(dso: string, returnCommand?: boolean): Promise<Record<string, unknown> | null>;