@temple-digital-group/temple-canton-js 2.0.5 → 2.0.6-beta-1

package/src/canton/deposits.ts

@@ -2,7 +2,7 @@ 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 { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "./walletAdapter.js";
 import { normalizeAssetId, instrumentCatalog, instrumentIdToSymbol, resolveOnChainInstrumentId } from "../../src/canton/instrumentCatalog.js";
 import {
 	randomUUID,
@@ -407,6 +407,7 @@ export async function depositFunds(
 	}
 
 	const isAmulet = assetId === "Amulet";
+	const usingWalletAdapter = Boolean(getWalletAdapter());
 
 	// --- 1. Resolve admin and factory ---
 	let admin: string;
@@ -431,7 +432,7 @@ export async function depositFunds(
 	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 expiryParams = usingWalletAdapter ? null : 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

package/src/canton/helpers.ts

@@ -1,7 +1,7 @@
 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 { getActiveContractReader } from "./wallet/service.js";
 import { instrumentCatalog, normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -26,8 +26,6 @@ export const DEFAULT_UTILITY_CONTEXT_KEYS = {
 	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"
@@ -95,22 +93,10 @@ export const randomUUID = (): string => {
 	});
 };
 
-/** 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);
+	return FORCE_LEDGER_METADATA;
 }
 
 /** Trim a contract ID string. */
@@ -141,9 +127,13 @@ export function normalizeContractReferences(value: unknown): unknown {
 	return value;
 }
 
-/** Resolve provider: use the passed value, or fall back to the wallet adapter's provider. */
+/**
+ * Resolve the active-contracts reader: the explicit provider override when given,
+ * otherwise the active wallet adapter (the universal wrapper). Returns null when
+ * no wallet source is available, so callers fall back to the ledger API.
+ */
 export function resolveProvider(provider: unknown): unknown {
-	return provider || getAdapterProvider() || null;
+	return getActiveContractReader(provider);
 }
 
 // ─── Instrument Catalog ──────────────────────────────────────────────────────

package/src/canton/index.js

@@ -2,7 +2,7 @@ import config, { NETWORK_LOCALHOST } from "../config/index.js";
 import axios from "axios";
 import { getDisclosures, getDelegation } from "../../dist/api/index.js";
 import { getUserId } from "../../dist/api/tokenStore.js";
-import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "./walletAdapter.js";
+import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "../../dist/canton/walletAdapter.js";
 
 // Import shared helpers from compiled TypeScript module
 import {
@@ -895,7 +895,7 @@ async function queryLedgerContractsByTemplate(templateId, returnCommand = false)
  * @returns {Promise<Object|null>} The AmuletRules contract data, or null on failure
  */
 export async function getAmuletRules(dso, returnCommand = false) {
-	if (!shouldUseLedgerForMetadata()) {
+	if (shouldUseLedgerForMetadata()) {
 		const headers = await buildHeaders();
 		const url = `${config.VALIDATOR_SCAN_API_URL}/amulet-rules?provider=${dso}`;
 		if (returnCommand) {
@@ -1012,7 +1012,7 @@ export async function getFeaturedAppRight(returnCommand = false) {
  * @returns {Promise<Object|null>} Mining rounds data with open_mining_rounds array, or null on failure
  */
 export async function getOpenMiningRounds(dso, returnCommand = false) {
-	if (!shouldUseLedgerForMetadata()) {
+	if (shouldUseLedgerForMetadata()) {
 		const headers = await buildHeaders();
 		const url = `${config.VALIDATOR_SCAN_API_URL}/open-and-issuing-mining-rounds?provider=${dso}`;
 		if (returnCommand) {

package/src/canton/wallet/adapter.ts

@@ -0,0 +1,150 @@
+/**
+ * Universal Wallet Adapter contract.
+ *
+ * Every wallet (Loop, and future providers such as Console or BitGo) is
+ * represented as a *normalized adapter* implementing the capability interface
+ * defined here. The rest of the SDK never talks to a wallet/provider SDK
+ * directly — it goes through the wallet service (./service.js), which dispatches
+ * to the active adapter.
+ *
+ * Capabilities are split into two tiers:
+ *
+ *  - REQUIRED: getPartyId, getActiveContracts, submitCommand.
+ *      A wallet that cannot provide these is not usable. `defineWalletAdapter`
+ *      throws if a factory omits one, and the service throws if a required
+ *      capability is invoked while no adapter is configured.
+ *
+ *  - OPTIONAL: payDueGasIfAny, getHolding, getAmuletRules, getOpenMiningRounds,
+ *      disconnect. Not every wallet supports these (e.g. a custodial wallet may
+ *      handle fees itself, a non-amulet wallet has no mining rounds). When a
+ *      factory omits an optional capability, it is filled with a safe no-op so
+ *      callers can invoke it unconditionally — it simply "passes".
+ *
+ * Add a new wallet by writing a `create<Name>WalletAdapter()` factory that
+ * builds a definition object and returns `defineWalletAdapter(definition)`.
+ */
+
+/** A normalized wallet adapter produced by {@link defineWalletAdapter}. */
+export interface WalletAdapter {
+	/** Provider id, e.g. "loop". */
+	readonly id: string;
+	/** True for server-side adapters that sign/submit locally. */
+	readonly isServer: boolean;
+
+	// ── Required capabilities ──
+	/** Resolve the wallet's primary party id. */
+	getPartyId(): string | null;
+	/** Read active contracts matching `args` via the wallet. */
+	getActiveContracts(args: unknown): Promise<unknown>;
+	/** Sign and submit a ledger command via the wallet. */
+	submitCommand(command: unknown): Promise<unknown>;
+
+	// ── Optional capabilities (always present after normalization) ──
+	/** Pay any outstanding network gas. No-op when unsupported. */
+	payDueGasIfAny(): Promise<void>;
+	/** Read a holding via the wallet. Resolves null when unsupported. */
+	getHolding(...args: unknown[]): Promise<unknown>;
+	/** Resolve amulet rules via the wallet. Resolves null when unsupported. */
+	getAmuletRules(...args: unknown[]): Promise<unknown>;
+	/** Resolve open mining rounds via the wallet. Resolves null when unsupported. */
+	getOpenMiningRounds(...args: unknown[]): Promise<unknown>;
+	/** Disconnect the wallet. No-op when unsupported. */
+	disconnect(): Promise<void>;
+
+	/** Raw provider object for legacy getAdapterProvider() consumers, or null. */
+	getRawProvider(): unknown;
+}
+
+/** Capability definition supplied by a `create<Name>WalletAdapter()` factory. */
+export interface WalletAdapterDefinition {
+	id?: string;
+	isServer?: boolean;
+	getPartyId(): string | null;
+	getActiveContracts(args: unknown): Promise<unknown> | unknown;
+	submitCommand(command: unknown): Promise<unknown> | unknown;
+	payDueGasIfAny?(): Promise<void> | void;
+	getHolding?(...args: unknown[]): Promise<unknown> | unknown;
+	getAmuletRules?(...args: unknown[]): Promise<unknown> | unknown;
+	getOpenMiningRounds?(...args: unknown[]): Promise<unknown> | unknown;
+	disconnect?(): Promise<void> | void;
+	getRawProvider?(): unknown;
+}
+
+/** Required capabilities — a usable wallet adapter must implement all of these. */
+export const REQUIRED_CAPABILITIES = ["getPartyId", "getActiveContracts", "submitCommand"] as const;
+
+/** Optional capabilities — filled with safe no-ops when a wallet does not support them. */
+export const OPTIONAL_CAPABILITIES = ["payDueGasIfAny", "getHolding", "getAmuletRules", "getOpenMiningRounds", "disconnect"] as const;
+
+/** Brand used to recognize objects produced by {@link defineWalletAdapter}. */
+const ADAPTER_BRAND = Symbol.for("temple.canton.walletAdapter");
+
+/**
+ * Safe no-op implementations for optional capabilities. Each returns a benign
+ * "nothing to do" value so a wallet that lacks the capability still passes when
+ * a caller invokes it. The comments explain why a no-op is the correct default.
+ */
+const OPTIONAL_NO_OPS = {
+	// Networks/wallets with no programmatic gas concept (or where fees are paid
+	// wallet-side, e.g. a custodial provider) have nothing to settle here.
+	payDueGasIfAny: async (): Promise<void> => undefined,
+	// Wallet does not expose its own holdings read — callers fall back to the
+	// ledger API, so "no wallet-side holdings" is represented as null.
+	getHolding: async (): Promise<unknown> => null,
+	// Amulet-specific context. A non-Canton-amulet wallet simply has no rules to
+	// provide; null lets callers fall back to the ledger/scan lookups.
+	getAmuletRules: async (): Promise<unknown> => null,
+	getOpenMiningRounds: async (): Promise<unknown> => null,
+	// Stateless/headless wallets hold no connection to tear down.
+	disconnect: async (): Promise<void> => undefined,
+};
+
+/** Returns true if `value` was produced by {@link defineWalletAdapter}. */
+export function isWalletAdapter(value: unknown): value is WalletAdapter {
+	return Boolean(value && (value as Record<symbol, unknown>)[ADAPTER_BRAND] === true);
+}
+
+/**
+ * Build a normalized wallet adapter from a factory definition.
+ *
+ * Validates that every required capability is implemented and fills any missing
+ * optional capability with a safe no-op. The returned object is branded so the
+ * service and facade can distinguish it from a raw provider SDK instance.
+ */
+export function defineWalletAdapter(definition: WalletAdapterDefinition): WalletAdapter {
+	if (!definition || typeof definition !== "object") {
+		throw new Error("[Temple SDK] Wallet adapter definition must be an object.");
+	}
+
+	const id = typeof definition.id === "string" && definition.id ? definition.id : "unknown";
+
+	for (const capability of REQUIRED_CAPABILITIES) {
+		if (typeof definition[capability] !== "function") {
+			throw new Error(`[Temple SDK] Wallet adapter "${id}" is missing required capability: ${capability}().`);
+		}
+	}
+
+	const adapter = {
+		[ADAPTER_BRAND]: true,
+		id,
+		isServer: Boolean(definition.isServer),
+
+		// Required capabilities (validated above).
+		getPartyId: definition.getPartyId,
+		getActiveContracts: definition.getActiveContracts,
+		submitCommand: definition.submitCommand,
+
+		// Optional capabilities — fall back to a safe no-op when a wallet omits them.
+		payDueGasIfAny: typeof definition.payDueGasIfAny === "function" ? definition.payDueGasIfAny : OPTIONAL_NO_OPS.payDueGasIfAny,
+		getHolding: typeof definition.getHolding === "function" ? definition.getHolding : OPTIONAL_NO_OPS.getHolding,
+		getAmuletRules: typeof definition.getAmuletRules === "function" ? definition.getAmuletRules : OPTIONAL_NO_OPS.getAmuletRules,
+		getOpenMiningRounds: typeof definition.getOpenMiningRounds === "function" ? definition.getOpenMiningRounds : OPTIONAL_NO_OPS.getOpenMiningRounds,
+		disconnect: typeof definition.disconnect === "function" ? definition.disconnect : OPTIONAL_NO_OPS.disconnect,
+
+		// Escape hatch: the raw provider object for legacy consumers of
+		// getAdapterProvider(). Defaults to null when a wallet exposes no such object.
+		getRawProvider: typeof definition.getRawProvider === "function" ? definition.getRawProvider : ((): unknown => null),
+	};
+
+	return adapter as unknown as WalletAdapter;
+}

package/src/canton/wallet/loop.ts

@@ -0,0 +1,116 @@
+/**
+ * Loop wallet adapter factory.
+ *
+ * Wraps a raw Loop SDK instance in the universal wallet adapter interface so the
+ * rest of the SDK interacts with Loop through the same contract as every other
+ * wallet. This preserves the exact behavior that previously lived inline in
+ * walletAdapter.js:
+ *
+ *   - Server-side (Loop): signs locally via executeTransaction().
+ *   - Client-side (Loop): delegates signing to the Loop Wallet via the provider's
+ *     submitTransaction().
+ *   - Reads go through the provider sub-object (loop.provider) when present.
+ *
+ * Server vs client is detected from the Loop connection: a server-side instance
+ * has a null connection.ticketId and connection.ws.
+ */
+
+import { defineWalletAdapter, type WalletAdapter } from "./adapter.js";
+
+/** The Loop read/submit provider sub-object (or the Loop instance itself). */
+interface LoopProvider {
+	party_id?: string | null;
+	getActiveContracts?: (args: unknown) => unknown;
+	submitTransaction?: (command: unknown) => unknown;
+}
+
+/** Outstanding-gas descriptor returned by Loop's checkDueGas(). */
+interface DueGas {
+	pending?: boolean;
+	tracking_id?: string;
+}
+
+/** Structural shape of the Loop SDK instance this adapter relies on. */
+interface LoopLike extends LoopProvider {
+	provider?: LoopProvider | null;
+	session?: { partyId?: string | null } | null;
+	connection?: { ticketId?: unknown; ws?: unknown } | null;
+	executeTransaction?: (command: unknown) => unknown;
+	checkDueGas?: () => Promise<DueGas | null | undefined> | DueGas | null | undefined;
+	payGas?: (trackingId: string) => Promise<unknown> | unknown;
+}
+
+/**
+ * Detect whether a Loop instance is server-side.
+ * Loop-specific: server-side has null connection.ticketId and connection.ws.
+ * With no connection object, assume server-side (headless/API usage).
+ */
+function detectServerSide(loop: LoopLike): boolean {
+	if (loop.connection) {
+		return loop.connection.ticketId == null && loop.connection.ws == null;
+	}
+	return true;
+}
+
+/**
+ * Create a universal wallet adapter backed by a Loop SDK instance.
+ */
+export function createLoopWalletAdapter(loop: unknown): WalletAdapter {
+	if (!loop || typeof loop !== "object") {
+		throw new Error("[Temple SDK] createLoopWalletAdapter requires a Loop wallet instance.");
+	}
+
+	const sdk = loop as LoopLike;
+	const isServer = detectServerSide(sdk);
+	// The provider sub-object handles reads (getActiveContracts) and client-side
+	// submission (submitTransaction). Fall back to the instance itself.
+	const provider: LoopProvider = sdk.provider || sdk;
+
+	return defineWalletAdapter({
+		id: "loop",
+		isServer,
+		getRawProvider: () => provider,
+
+		// ── Required capabilities ──
+		getPartyId: () => sdk.provider?.party_id || sdk.session?.partyId || null,
+
+		getActiveContracts: (args) => {
+			if (typeof provider.getActiveContracts !== "function") {
+				throw new Error("[Temple SDK] Loop provider does not support getActiveContracts().");
+			}
+			return provider.getActiveContracts(args);
+		},
+
+		submitCommand: (command) => {
+			// Server-side: sign locally with the private key.
+			if (isServer && typeof sdk.executeTransaction === "function") {
+				return sdk.executeTransaction(command);
+			}
+			// Client-side: delegate signing to the Loop Wallet via WebSocket.
+			if (typeof provider.submitTransaction === "function") {
+				return provider.submitTransaction(command);
+			}
+			throw new Error("[Temple SDK] Loop wallet adapter does not support transaction submission.");
+		},
+
+		// ── Optional capabilities ──
+		// Loop pays network gas programmatically only on the server side; the
+		// client-side flow is handled by the Loop Wallet UI, so it is a no-op here.
+		payDueGasIfAny: async () => {
+			if (!isServer) return;
+			if (typeof sdk.checkDueGas !== "function" || typeof sdk.payGas !== "function") return;
+			try {
+				const dueGas = await sdk.checkDueGas();
+				const trackingId = dueGas?.tracking_id;
+				if (dueGas?.pending && trackingId) {
+					console.log(`[Temple SDK] Paying outstanding network gas (tracking_id=${trackingId})`);
+					await sdk.payGas(trackingId);
+				}
+			} catch (error) {
+				console.warn(`[Temple SDK] checkDueGas/payGas failed: ${(error as Error)?.message || String(error)}`);
+			}
+		},
+		// getHolding / getAmuletRules / getOpenMiningRounds / disconnect: not
+		// provided by Loop here — the adapter inherits the safe no-op defaults.
+	});
+}

package/src/canton/wallet/service.ts

@@ -0,0 +1,82 @@
+/**
+ * Universal wallet service.
+ *
+ * Holds the single active wallet adapter and dispatches capability calls to it.
+ * This is the one chokepoint the rest of the SDK uses to reach a wallet — no
+ * module talks to a provider/wallet SDK directly.
+ *
+ *  - Required capabilities (getPartyId, submitCommand) throw a clear error when
+ *    invoked while no adapter is configured.
+ *  - Active-contract reads are resolved through `getActiveContractReader`, which
+ *    supports an explicit per-call provider override and returns null when no
+ *    wallet source is available so callers can fall back to the ledger API.
+ *  - Optional capabilities (payDueGasIfAny) become safe no-ops when no adapter
+ *    is set.
+ */
+
+import { isWalletAdapter, type WalletAdapter } from "./adapter.js";
+
+/** The single active, normalized wallet adapter (or null when none is set). */
+let _activeAdapter: WalletAdapter | null = null;
+
+/** Register the active wallet adapter. Pass null to clear it. */
+export function setActiveAdapter(adapter: WalletAdapter | null): void {
+	if (adapter && !isWalletAdapter(adapter)) {
+		throw new Error("[Temple SDK] setActiveAdapter expects a normalized wallet adapter created by a create*WalletAdapter() factory.");
+	}
+	_activeAdapter = adapter || null;
+}
+
+/** Get the active wallet adapter, or null when none is set. */
+export function getActiveAdapter(): WalletAdapter | null {
+	return _activeAdapter;
+}
+
+/** True when a wallet adapter is configured. */
+export function hasActiveAdapter(): boolean {
+	return _activeAdapter !== null;
+}
+
+function requireAdapter(): WalletAdapter {
+	if (!_activeAdapter) {
+		throw new Error("[Temple SDK] No wallet adapter configured. Call initialize() with WALLET_ADAPTER or setWalletAdapter() first.");
+	}
+	return _activeAdapter;
+}
+
+// ── Required capabilities ──────────────────────────────────────────────────
+
+/** Resolve the active wallet's party id. Throws when no adapter is configured. */
+export function getPartyId(): string | null {
+	return requireAdapter().getPartyId();
+}
+
+/** Sign and submit a ledger command. Throws when no adapter is configured. */
+export function submitCommand(command: unknown): Promise<unknown> {
+	return requireAdapter().submitCommand(command);
+}
+
+/**
+ * Resolve the object used to read active contracts.
+ *
+ * An explicit `providerOverride` wins (a caller intentionally bypassing the
+ * active wallet); otherwise the active adapter — the universal wrapper — is
+ * returned, exposing its normalized `getActiveContracts` capability. Returns
+ * null when neither is available, signalling callers to fall back to the
+ * ledger API.
+ */
+export function getActiveContractReader(providerOverride: unknown = null): unknown {
+	if (providerOverride) return providerOverride;
+	return _activeAdapter || null;
+}
+
+// ── Optional capabilities ──────────────────────────────────────────────────
+
+/**
+ * Pay any outstanding network gas before a read/submit. Safe no-op when no
+ * adapter is configured (e.g. pure ledger/server mode without a wallet).
+ */
+export async function payDueGasIfAny(): Promise<void> {
+	if (!_activeAdapter) return;
+	return _activeAdapter.payDueGasIfAny();
+}

package/src/canton/walletAdapter.ts

@@ -0,0 +1,93 @@
+/**
+ * Wallet Adapter Facade
+ *
+ * Backward-compatible public surface for wallet interactions. The real wallet
+ * architecture lives in ./wallet/ — a universal adapter contract (adapter.ts),
+ * a service registry that dispatches capability calls (service.ts), and one
+ * factory per wallet (loop.ts, and future providers). This module is a thin
+ * facade over that service so existing imports keep working unchanged.
+ *
+ * Adding a new wallet does not touch this file: write a create<Name>WalletAdapter()
+ * factory and pass its result to setWalletAdapter().
+ */
+
+import {
+	setActiveAdapter,
+	getActiveAdapter,
+	submitCommand as serviceSubmitCommand,
+	payDueGasIfAny as servicePayDueGasIfAny,
+} from "./wallet/service.js";
+import { isWalletAdapter } from "./wallet/adapter.js";
+import { createLoopWalletAdapter } from "./wallet/loop.js";
+import type { WalletAdapter } from "./wallet/adapter.js";
+
+// Re-export the adapter toolkit so consumers can build/register custom wallets.
+export { createLoopWalletAdapter } from "./wallet/loop.js";
+export { defineWalletAdapter, isWalletAdapter } from "./wallet/adapter.js";
+export type { WalletAdapter, WalletAdapterDefinition } from "./wallet/adapter.js";
+
+/**
+ * Set the active wallet adapter.
+ *
+ * Accepts either a normalized adapter (from a create*WalletAdapter() factory) or
+ * a raw Loop SDK instance, which is auto-wrapped for backward compatibility.
+ * Pass a falsy value to clear the adapter.
+ */
+export function setWalletAdapter(adapter: unknown): void {
+	if (!adapter) {
+		setActiveAdapter(null);
+		return;
+	}
+	const normalized = isWalletAdapter(adapter) ? adapter : createLoopWalletAdapter(adapter);
+	setActiveAdapter(normalized);
+}
+
+/**
+ * Get the active (normalized) wallet adapter, or null when none is set.
+ */
+export function getWalletAdapter(): WalletAdapter | null {
+	return getActiveAdapter();
+}
+
+/**
+ * Returns the provider sub-object used for read operations (getActiveContracts).
+ * Kept for backward compatibility; resolves the active adapter's raw provider.
+ */
+export function getAdapterProvider(): unknown {
+	const adapter = getActiveAdapter();
+	if (!adapter) return null;
+	return adapter.getRawProvider() || adapter;
+}
+
+/**
+ * Check if the active adapter runs in server mode.
+ */
+export function isServerMode(): boolean {
+	const adapter = getActiveAdapter();
+	return adapter ? Boolean(adapter.isServer) : false;
+}
+
+/**
+ * Get the party ID from the active wallet adapter, or null when none is set.
+ */
+export function getAdapterPartyId(): string | null {
+	const adapter = getActiveAdapter();
+	return adapter ? adapter.getPartyId() : null;
+}
+
+/**
+ * Pay any outstanding network gas before submitting a transaction or reading
+ * balances. Safe no-op when no adapter is configured or the wallet handles gas
+ * itself.
+ */
+export function payDueGasIfAny(): Promise<void> {
+	return servicePayDueGasIfAny();
+}
+
+/**
+ * Submit a command via the active wallet adapter.
+ * Throws when no adapter is configured.
+ */
+export function submitCommand(command: unknown): Promise<unknown> {
+	return serviceSubmitCommand(command);
+}

package/src/canton/withdrawals.ts

@@ -7,7 +7,7 @@ import {
 	getDelegation,
 } from "../api/index.js";
 import { getUserId } from "../api/tokenStore.js";
-import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "../../src/canton/walletAdapter.js";
+import { getAdapterPartyId, getWalletAdapter, submitCommand, payDueGasIfAny } from "./walletAdapter.js";
 import {
 	randomUUID,
 	shouldUseLedgerForMetadata,

package/src/config/index.d.ts

@@ -19,6 +19,9 @@ export function getConfigValue(key: any): any;
 export function setWalletAdapter(adapter: any): void;
 export function getWalletAdapter(): any;
 export function getAdapterProvider(): any;
+export function createLoopWalletAdapter(loop: any): any;
+export function defineWalletAdapter(definition: any): any;
+export function isWalletAdapter(value: any): boolean;
 export const NETWORK_LOCALHOST: "localhost";
 export const NETWORK_TESTNET: "testnet";
 export const NETWORK_MAINNET: "mainnet";

package/src/config/index.js

@@ -6,8 +6,15 @@ if (typeof process !== 'undefined' && process.env) {
 // Global config object that can be set by the consuming application
 let appConfig = null;
 
-// Re-export wallet adapter functions
-export { setWalletAdapter, getWalletAdapter, getAdapterProvider } from "../canton/walletAdapter.js";
+// Re-export wallet adapter functions and the adapter toolkit (factory + helpers).
+export {
+	setWalletAdapter,
+	getWalletAdapter,
+	getAdapterProvider,
+	createLoopWalletAdapter,
+	defineWalletAdapter,
+	isWalletAdapter,
+} from "../../dist/canton/walletAdapter.js";
 
 /**
  * Initialize the library with a configuration object.

package/src/canton/walletAdapter.d.ts

@@ -1,7 +0,0 @@
-export function setWalletAdapter(adapter: unknown): void;
-export function getWalletAdapter(): unknown;
-export function getAdapterProvider(): unknown;
-export function isServerMode(): boolean;
-export function getAdapterPartyId(): string | null;
-export function submitCommand(command: unknown): Promise<unknown>;
-export function payDueGasIfAny(): Promise<void>;