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

package/src/canton/helpers.ts

@@ -1,266 +1,266 @@
-import config from "../../src/config/index.js";
-import axios from "axios";
-import { getJWTToken } from "../../src/auth0/index.js";
-import { getAdapterProvider } from "../../src/canton/walletAdapter.js";
-import { instrumentCatalog, normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
-
-// ─── Constants ───────────────────────────────────────────────────────────────
-
-export const DEFAULT_AMULET_CONTEXT_KEYS = {
-	amuletRules: "amulet-rules",
-	featuredAppRight: "featured-app-right",
-	openRound: "open-round",
-	expireLock: "expire-lock",
-} as const;
-
-export const DEFAULT_UTILITY_CONTEXT_KEYS = {
-	instrumentConfiguration: "instrument-configuration",
-	instrumentConfigurationPrefixed: "utility.digitalasset.com/instrument-configuration",
-	senderCredentials: "sender-credentials",
-	senderCredentialsPrefixed: "utility.digitalasset.com/sender-credentials",
-	receiverCredentials: "receiver-credentials",
-	receiverCredentialsPrefixed: "utility.digitalasset.com/receiver-credentials",
-	appRewardConfiguration: "app-reward-configuration",
-	appRewardConfigurationPrefixed: "utility.digitalasset.com/app-reward-configuration",
-	featuredAppRight: "featured-app-right",
-	featuredAppRightPrefixed: "utility.digitalasset.com/featured-app-right",
-} as const;
-
-export const LOCAL_VALIDATOR_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
-
-export const FORCE_LEDGER_METADATA: boolean =
-	typeof process !== "undefined" && process.env
-		? String(process.env.FORCE_LEDGER_METADATA || "").toLowerCase() === "true"
-		: false;
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface DisclosedContract {
-	templateId: string | null;
-	contractId: string;
-	createdEventBlob: string;
-	synchronizerId: string | null;
-}
-
-export interface LedgerCommand {
-	commands: unknown[];
-	commandId: string;
-	userId: string;
-	applicationId: string;
-	actAs: string[];
-	disclosedContracts: DisclosedContract[];
-}
-
-export interface ContractMetadata {
-	contractCid: string;
-	disclosureCid: string;
-	synchronizerId: string | null;
-	templateId?: string | null;
-	payload?: Record<string, unknown>;
-}
-
-export interface ActiveContractEntry {
-	contractEntry?: {
-		JsActiveContract?: {
-			createdEvent?: {
-				contractId?: string;
-				createdEventBlob?: string;
-				templateId?: string;
-				createArgument?: Record<string, unknown>;
-			};
-			synchronizerId?: string;
-			templateId?: string;
-		};
-	};
-	createdEvent?: Record<string, unknown>;
-	contractId?: string;
-	[key: string]: unknown;
-}
-
-// ─── Pure Utilities ──────────────────────────────────────────────────────────
-
-/** Cross-platform UUID generation. */
-export const randomUUID = (): string => {
-	if (typeof crypto !== "undefined" && crypto.randomUUID) {
-		return crypto.randomUUID();
-	}
-	if (typeof require !== "undefined") {
-		const nodeCrypto = require("crypto");
-		return nodeCrypto.randomUUID();
-	}
-	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-		const r = (Math.random() * 16) | 0;
-		const v = c === "x" ? r : (r & 0x3) | 0x8;
-		return v.toString(16);
-	});
-};
-
-/** Check if a validator URL points to localhost. */
-export function isLocalValidatorUrl(urlValue: string | undefined | null): boolean {
-	if (!urlValue) return false;
-	try {
-		const parsed = new URL(urlValue);
-		return LOCAL_VALIDATOR_HOSTNAMES.has(parsed.hostname.toLowerCase());
-	} catch {
-		return false;
-	}
-}
-
-/** Determine if ledger should be used for metadata resolution. */
-export function shouldUseLedgerForMetadata(): boolean {
-	if (FORCE_LEDGER_METADATA) return true;
-	if (!config.VALIDATOR_API_URL) return false;
-	return isLocalValidatorUrl(config.VALIDATOR_API_URL);
-}
-
-/** Trim a contract ID string. */
-export function normalizeContractId(value: unknown): unknown {
-	if (typeof value !== "string") return value;
-	return value.trim();
-}
-
-/** Recursively normalize contract references in an object. */
-export function normalizeContractReferences(value: unknown): unknown {
-	if (Array.isArray(value)) {
-		return value.map(normalizeContractReferences);
-	}
-	if (value && typeof value === "object") {
-		const normalized: Record<string, unknown> = {};
-		for (const [key, entryValue] of Object.entries(value)) {
-			if (typeof entryValue === "string") {
-				normalized[key] = entryValue;
-				continue;
-			}
-			normalized[key] = normalizeContractReferences(entryValue);
-		}
-		return normalized;
-	}
-	if (typeof value === "string") {
-		return normalizeContractId(value);
-	}
-	return value;
-}
-
-/** Resolve provider: use the passed value, or fall back to the wallet adapter's provider. */
-export function resolveProvider(provider: unknown): unknown {
-	return provider || getAdapterProvider() || null;
-}
-
-// ─── Instrument Catalog ──────────────────────────────────────────────────────
-
-/** Resolve an instrument definition from the catalog. */
-export function resolveInstrumentDefinition(assetId: string): Record<string, unknown> | null {
-	if (!assetId || typeof assetId !== "string") return null;
-	return (instrumentCatalog as Record<string, Record<string, unknown>>)[normalizeAssetId(assetId)] || null;
-}
-
-/** Get the registrar for a utility instrument from the catalog. */
-export function getInstrumentRegistrar(assetId: string): string | null {
-	const definition = resolveInstrumentDefinition(assetId);
-	const networkDef = definition?.[config.NETWORK] as Record<string, unknown> | undefined;
-	return (networkDef?.registrar as string) || null;
-}
-
-// ─── Contract Helpers ────────────────────────────────────────────────────────
-
-/** Extract active contracts from various ledger response shapes. */
-export function unwrapActiveContracts(responseData: unknown): unknown[] {
-	if (!responseData) return [];
-	if (Array.isArray(responseData)) return responseData;
-	const data = responseData as Record<string, unknown>;
-	if (Array.isArray(data.activeContracts)) return data.activeContracts;
-	if (Array.isArray(data.result)) return data.result;
-	if (Array.isArray(data.contracts)) return data.contracts;
-	return [];
-}
-
-/** Find a disclosed contract by template ID suffix. */
-export function findDisclosedContract(
-	disclosedContracts: DisclosedContract[],
-	templateSuffix: string,
-): DisclosedContract | null {
-	if (!Array.isArray(disclosedContracts)) return null;
-	return (
-		disclosedContracts.find((contract) => {
-			const templateId = contract?.templateId ?? "";
-			return templateId.endsWith(`:${templateSuffix}`);
-		}) || null
-	);
-}
-
-/** Map an active contract entry to a metadata structure. */
-export function mapActiveContractMetadata(entry: ActiveContractEntry): {
-	contractId: unknown;
-	createdEventBlob: string | undefined;
-	synchronizerId: string | undefined;
-	templateId: string | null;
-	payload: Record<string, unknown>;
-} | null {
-	const createdEvent = entry?.contractEntry?.JsActiveContract?.createdEvent;
-	if (!createdEvent) return null;
-	return {
-		contractId: normalizeContractId(createdEvent.contractId),
-		createdEventBlob: createdEvent.createdEventBlob,
-		synchronizerId: entry.contractEntry?.JsActiveContract?.synchronizerId,
-		templateId: createdEvent.templateId || entry.contractEntry?.JsActiveContract?.templateId || null,
-		payload: createdEvent.createArgument || {},
-	};
-}
-
-/** Convert a contract entry to metadata. */
-export function toContractMetadata(entry: {
-	contractId?: unknown;
-	createdEventBlob?: string;
-	synchronizerId?: string;
-	payload?: Record<string, unknown>;
-} | null): ContractMetadata | null {
-	if (!entry) return null;
-	return {
-		contractCid: entry.contractId as string,
-		disclosureCid: entry.createdEventBlob as string,
-		synchronizerId: entry.synchronizerId || null,
-		payload: entry.payload,
-	};
-}
-
-// ─── Disclosed Contracts ─────────────────────────────────────────────────────
-
-/** Deduplicate disclosed contracts in a command by contractId. */
-export function dedupeDisclosedContracts(command: LedgerCommand): void {
-	if (!command || !Array.isArray(command.disclosedContracts)) return;
-
-	const deduped: DisclosedContract[] = [];
-	const seen = new Set<string>();
-	for (const entry of command.disclosedContracts) {
-		if (!entry || !entry.contractId || !entry.createdEventBlob) continue;
-		if (seen.has(entry.contractId)) continue;
-		seen.add(entry.contractId);
-		deduped.push(entry);
-	}
-	command.disclosedContracts = deduped;
-}
-
-// ─── Ledger Helpers ──────────────────────────────────────────────────────────
-
-/** Build HTTP headers with JWT authorization. */
-export async function buildHeaders(): Promise<Record<string, string>> {
-	const headers: Record<string, string> = { "Content-Type": "application/json" };
-	const token = config.JWT_TOKEN || (config.AUTH0_TOKEN_URL ? await getJWTToken() : null);
-	if (token) {
-		headers.Authorization = `Bearer ${token}`;
-	}
-	return headers;
-}
-
-/** Get the current ledger end offset. */
-export async function getLedgerEnd(): Promise<string | null> {
-	const headers = await buildHeaders();
-	const url = `${config.VALIDATOR_API_URL}/v2/state/ledger-end`;
-	try {
-		const response = await axios.get(url, { headers });
-		return response.data.offset;
-	} catch (error) {
-		console.error(`Error fetching ledger end: ${error}`);
-		return null;
-	}
-}
+import config from "../../src/config/index.js";
+import axios from "axios";
+import { getJWTToken } from "../../src/auth0/index.js";
+import { getAdapterProvider } from "../../src/canton/walletAdapter.js";
+import { instrumentCatalog, normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const DEFAULT_AMULET_CONTEXT_KEYS = {
+	amuletRules: "amulet-rules",
+	featuredAppRight: "featured-app-right",
+	openRound: "open-round",
+	expireLock: "expire-lock",
+} as const;
+
+export const DEFAULT_UTILITY_CONTEXT_KEYS = {
+	instrumentConfiguration: "instrument-configuration",
+	instrumentConfigurationPrefixed: "utility.digitalasset.com/instrument-configuration",
+	senderCredentials: "sender-credentials",
+	senderCredentialsPrefixed: "utility.digitalasset.com/sender-credentials",
+	receiverCredentials: "receiver-credentials",
+	receiverCredentialsPrefixed: "utility.digitalasset.com/receiver-credentials",
+	appRewardConfiguration: "app-reward-configuration",
+	appRewardConfigurationPrefixed: "utility.digitalasset.com/app-reward-configuration",
+	featuredAppRight: "featured-app-right",
+	featuredAppRightPrefixed: "utility.digitalasset.com/featured-app-right",
+} as const;
+
+export const LOCAL_VALIDATOR_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
+
+export const FORCE_LEDGER_METADATA: boolean =
+	typeof process !== "undefined" && process.env
+		? String(process.env.FORCE_LEDGER_METADATA || "").toLowerCase() === "true"
+		: false;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface DisclosedContract {
+	templateId: string | null;
+	contractId: string;
+	createdEventBlob: string;
+	synchronizerId: string | null;
+}
+
+export interface LedgerCommand {
+	commands: unknown[];
+	commandId: string;
+	userId: string;
+	applicationId: string;
+	actAs: string[];
+	disclosedContracts: DisclosedContract[];
+}
+
+export interface ContractMetadata {
+	contractCid: string;
+	disclosureCid: string;
+	synchronizerId: string | null;
+	templateId?: string | null;
+	payload?: Record<string, unknown>;
+}
+
+export interface ActiveContractEntry {
+	contractEntry?: {
+		JsActiveContract?: {
+			createdEvent?: {
+				contractId?: string;
+				createdEventBlob?: string;
+				templateId?: string;
+				createArgument?: Record<string, unknown>;
+			};
+			synchronizerId?: string;
+			templateId?: string;
+		};
+	};
+	createdEvent?: Record<string, unknown>;
+	contractId?: string;
+	[key: string]: unknown;
+}
+
+// ─── Pure Utilities ──────────────────────────────────────────────────────────
+
+/** Cross-platform UUID generation. */
+export const randomUUID = (): string => {
+	if (typeof crypto !== "undefined" && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	if (typeof require !== "undefined") {
+		const nodeCrypto = require("crypto");
+		return nodeCrypto.randomUUID();
+	}
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = (Math.random() * 16) | 0;
+		const v = c === "x" ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+};
+
+/** Check if a validator URL points to localhost. */
+export function isLocalValidatorUrl(urlValue: string | undefined | null): boolean {
+	if (!urlValue) return false;
+	try {
+		const parsed = new URL(urlValue);
+		return LOCAL_VALIDATOR_HOSTNAMES.has(parsed.hostname.toLowerCase());
+	} catch {
+		return false;
+	}
+}
+
+/** Determine if ledger should be used for metadata resolution. */
+export function shouldUseLedgerForMetadata(): boolean {
+	if (FORCE_LEDGER_METADATA) return true;
+	if (!config.VALIDATOR_API_URL) return false;
+	return isLocalValidatorUrl(config.VALIDATOR_API_URL);
+}
+
+/** Trim a contract ID string. */
+export function normalizeContractId(value: unknown): unknown {
+	if (typeof value !== "string") return value;
+	return value.trim();
+}
+
+/** Recursively normalize contract references in an object. */
+export function normalizeContractReferences(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(normalizeContractReferences);
+	}
+	if (value && typeof value === "object") {
+		const normalized: Record<string, unknown> = {};
+		for (const [key, entryValue] of Object.entries(value)) {
+			if (typeof entryValue === "string") {
+				normalized[key] = entryValue;
+				continue;
+			}
+			normalized[key] = normalizeContractReferences(entryValue);
+		}
+		return normalized;
+	}
+	if (typeof value === "string") {
+		return normalizeContractId(value);
+	}
+	return value;
+}
+
+/** Resolve provider: use the passed value, or fall back to the wallet adapter's provider. */
+export function resolveProvider(provider: unknown): unknown {
+	return provider || getAdapterProvider() || null;
+}
+
+// ─── Instrument Catalog ──────────────────────────────────────────────────────
+
+/** Resolve an instrument definition from the catalog. */
+export function resolveInstrumentDefinition(assetId: string): Record<string, unknown> | null {
+	if (!assetId || typeof assetId !== "string") return null;
+	return (instrumentCatalog as Record<string, Record<string, unknown>>)[normalizeAssetId(assetId)] || null;
+}
+
+/** Get the registrar for a utility instrument from the catalog. */
+export function getInstrumentRegistrar(assetId: string): string | null {
+	const definition = resolveInstrumentDefinition(assetId);
+	const networkDef = definition?.[config.NETWORK] as Record<string, unknown> | undefined;
+	return (networkDef?.registrar as string) || null;
+}
+
+// ─── Contract Helpers ────────────────────────────────────────────────────────
+
+/** Extract active contracts from various ledger response shapes. */
+export function unwrapActiveContracts(responseData: unknown): unknown[] {
+	if (!responseData) return [];
+	if (Array.isArray(responseData)) return responseData;
+	const data = responseData as Record<string, unknown>;
+	if (Array.isArray(data.activeContracts)) return data.activeContracts;
+	if (Array.isArray(data.result)) return data.result;
+	if (Array.isArray(data.contracts)) return data.contracts;
+	return [];
+}
+
+/** Find a disclosed contract by template ID suffix. */
+export function findDisclosedContract(
+	disclosedContracts: DisclosedContract[],
+	templateSuffix: string,
+): DisclosedContract | null {
+	if (!Array.isArray(disclosedContracts)) return null;
+	return (
+		disclosedContracts.find((contract) => {
+			const templateId = contract?.templateId ?? "";
+			return templateId.endsWith(`:${templateSuffix}`);
+		}) || null
+	);
+}
+
+/** Map an active contract entry to a metadata structure. */
+export function mapActiveContractMetadata(entry: ActiveContractEntry): {
+	contractId: unknown;
+	createdEventBlob: string | undefined;
+	synchronizerId: string | undefined;
+	templateId: string | null;
+	payload: Record<string, unknown>;
+} | null {
+	const createdEvent = entry?.contractEntry?.JsActiveContract?.createdEvent;
+	if (!createdEvent) return null;
+	return {
+		contractId: normalizeContractId(createdEvent.contractId),
+		createdEventBlob: createdEvent.createdEventBlob,
+		synchronizerId: entry.contractEntry?.JsActiveContract?.synchronizerId,
+		templateId: createdEvent.templateId || entry.contractEntry?.JsActiveContract?.templateId || null,
+		payload: createdEvent.createArgument || {},
+	};
+}
+
+/** Convert a contract entry to metadata. */
+export function toContractMetadata(entry: {
+	contractId?: unknown;
+	createdEventBlob?: string;
+	synchronizerId?: string;
+	payload?: Record<string, unknown>;
+} | null): ContractMetadata | null {
+	if (!entry) return null;
+	return {
+		contractCid: entry.contractId as string,
+		disclosureCid: entry.createdEventBlob as string,
+		synchronizerId: entry.synchronizerId || null,
+		payload: entry.payload,
+	};
+}
+
+// ─── Disclosed Contracts ─────────────────────────────────────────────────────
+
+/** Deduplicate disclosed contracts in a command by contractId. */
+export function dedupeDisclosedContracts(command: LedgerCommand): void {
+	if (!command || !Array.isArray(command.disclosedContracts)) return;
+
+	const deduped: DisclosedContract[] = [];
+	const seen = new Set<string>();
+	for (const entry of command.disclosedContracts) {
+		if (!entry || !entry.contractId || !entry.createdEventBlob) continue;
+		if (seen.has(entry.contractId)) continue;
+		seen.add(entry.contractId);
+		deduped.push(entry);
+	}
+	command.disclosedContracts = deduped;
+}
+
+// ─── Ledger Helpers ──────────────────────────────────────────────────────────
+
+/** Build HTTP headers with JWT authorization. */
+export async function buildHeaders(): Promise<Record<string, string>> {
+	const headers: Record<string, string> = { "Content-Type": "application/json" };
+	const token = config.JWT_TOKEN || (config.AUTH0_TOKEN_URL ? await getJWTToken() : null);
+	if (token) {
+		headers.Authorization = `Bearer ${token}`;
+	}
+	return headers;
+}
+
+/** Get the current ledger end offset. */
+export async function getLedgerEnd(): Promise<string | null> {
+	const headers = await buildHeaders();
+	const url = `${config.VALIDATOR_API_URL}/v2/state/ledger-end`;
+	try {
+		const response = await axios.get(url, { headers });
+		return response.data.offset;
+	} catch (error) {
+		console.error(`Error fetching ledger end: ${error}`);
+		return null;
+	}
+}

package/src/canton/index.d.ts

@@ -1,41 +1,41 @@
-import type { ContractMetadata } from "./helpers.js";
-
-export function resolveAmuletContext(opts: {
-	investor: string;
-	holdingIds?: string[];
-	transferAmount?: number;
-}): Promise<Record<string, unknown> | null>;
-
-export function resolveUtilityInstrumentConfiguration(
-	utilityAsset: string,
-	registrar: string | null,
-): Promise<ContractMetadata | null>;
-
-export function resolveUtilityAllocationFactory(
-	registrar: string,
-	holder?: string | null,
-): Promise<ContractMetadata | null>;
-
-export function getAmuletHoldingsForParty(
-	party: string,
-	returnCommand?: boolean,
-	provider?: unknown,
-): Promise<unknown[]>;
-
-export function getUtilityHoldingsForParty(
-	party: string,
-	returnCommand?: boolean,
-	provider?: unknown,
-): Promise<unknown[]>;
-
-export function getUtxoCount(
-	party: string,
-	assetId: string,
-	provider?: unknown,
-): Promise<{
-	total: number;
-	unlocked: number;
-	locked: number;
-	largestUnlocked: number;
-	unlockedBalance: number;
-}>;
+import type { ContractMetadata } from "./helpers.js";
+
+export function resolveAmuletContext(opts: {
+	investor: string;
+	holdingIds?: string[];
+	transferAmount?: number;
+}): Promise<Record<string, unknown> | null>;
+
+export function resolveUtilityInstrumentConfiguration(
+	utilityAsset: string,
+	registrar: string | null,
+): Promise<ContractMetadata | null>;
+
+export function resolveUtilityAllocationFactory(
+	registrar: string,
+	holder?: string | null,
+): Promise<ContractMetadata | null>;
+
+export function getAmuletHoldingsForParty(
+	party: string,
+	returnCommand?: boolean,
+	provider?: unknown,
+): Promise<unknown[]>;
+
+export function getUtilityHoldingsForParty(
+	party: string,
+	returnCommand?: boolean,
+	provider?: unknown,
+): Promise<unknown[]>;
+
+export function getUtxoCount(
+	party: string,
+	assetId: string,
+	provider?: unknown,
+): Promise<{
+	total: number;
+	unlocked: number;
+	locked: number;
+	largestUnlocked: number;
+	unlockedBalance: number;
+}>;