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

package/dist/canton/deposits.js

@@ -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, shouldUseLedgerForMetadata, normalizeContractId, resolveInstrumentDefinition, getInstrumentRegistrar, resolveProvider, dedupeDisclosedContracts, buildHeaders, DEFAULT_UTILITY_CONTEXT_KEYS, } from "./helpers.js";
 import { resolveAmuletContext, resolveUtilityInstrumentConfiguration, resolveUtilityAllocationFactory, getAmuletHoldingsForParty, getUtilityHoldingsForParty, getUtxoCount, getAmuletRules, getOpenMiningRounds, } from "../../src/canton/index.js";
@@ -298,6 +298,7 @@ export async function depositFunds(opts, returnCommand = false) {
         return { error: msg };
     }
     const isAmulet = assetId === "Amulet";
+    const usingWalletAdapter = Boolean(getWalletAdapter());
     // --- 1. Resolve admin and factory ---
     let admin;
     let factoryContractId;
@@ -319,7 +320,7 @@ export async function depositFunds(opts, returnCommand = false) {
     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/dist/canton/helpers.d.ts

@@ -16,7 +16,6 @@ export declare const DEFAULT_UTILITY_CONTEXT_KEYS: {
     readonly featuredAppRight: "featured-app-right";
     readonly featuredAppRightPrefixed: "utility.digitalasset.com/featured-app-right";
 };
-export declare const LOCAL_VALIDATOR_HOSTNAMES: Set<string>;
 export declare const FORCE_LEDGER_METADATA: boolean;
 export interface DisclosedContract {
     templateId: string | null;
@@ -58,15 +57,17 @@ export interface ActiveContractEntry {
 }
 /** Cross-platform UUID generation. */
 export declare const randomUUID: () => string;
-/** Check if a validator URL points to localhost. */
-export declare function isLocalValidatorUrl(urlValue: string | undefined | null): boolean;
 /** Determine if ledger should be used for metadata resolution. */
 export declare function shouldUseLedgerForMetadata(): boolean;
 /** Trim a contract ID string. */
 export declare function normalizeContractId(value: unknown): unknown;
 /** Recursively normalize contract references in an object. */
 export declare function normalizeContractReferences(value: unknown): unknown;
-/** 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 declare function resolveProvider(provider: unknown): unknown;
 /** Resolve an instrument definition from the catalog. */
 export declare function resolveInstrumentDefinition(assetId: string): Record<string, unknown> | null;

package/dist/canton/helpers.js

@@ -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 ───────────────────────────────────────────────────────────────
 export const DEFAULT_AMULET_CONTEXT_KEYS = {
@@ -22,7 +22,6 @@ export const DEFAULT_UTILITY_CONTEXT_KEYS = {
     featuredAppRight: "featured-app-right",
     featuredAppRightPrefixed: "utility.digitalasset.com/featured-app-right",
 };
-export const LOCAL_VALIDATOR_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 export const FORCE_LEDGER_METADATA = typeof process !== "undefined" && process.env
     ? String(process.env.FORCE_LEDGER_METADATA || "").toLowerCase() === "true"
     : false;
@@ -42,25 +41,11 @@ export const randomUUID = () => {
         return v.toString(16);
     });
 };
-/** Check if a validator URL points to localhost. */
-export function isLocalValidatorUrl(urlValue) {
-    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() {
-    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. */
 export function normalizeContractId(value) {
@@ -89,9 +74,13 @@ export function normalizeContractReferences(value) {
     }
     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) {
-    return provider || getAdapterProvider() || null;
+    return getActiveContractReader(provider);
 }
 // ─── Instrument Catalog ──────────────────────────────────────────────────────
 /** Resolve an instrument definition from the catalog. */

package/dist/canton/wallet/adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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;
+    /** 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>;
+    /** 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 declare const REQUIRED_CAPABILITIES: readonly ["getPartyId", "getActiveContracts", "submitCommand"];
+/** Optional capabilities — filled with safe no-ops when a wallet does not support them. */
+export declare const OPTIONAL_CAPABILITIES: readonly ["payDueGasIfAny", "getHolding", "getAmuletRules", "getOpenMiningRounds", "disconnect"];
+/** Returns true if `value` was produced by {@link defineWalletAdapter}. */
+export declare function isWalletAdapter(value: unknown): value is WalletAdapter;
+/**
+ * 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 declare function defineWalletAdapter(definition: WalletAdapterDefinition): WalletAdapter;

package/dist/canton/wallet/adapter.js

@@ -0,0 +1,91 @@
+/**
+ * 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)`.
+ */
+/** Required capabilities — a usable wallet adapter must implement all of these. */
+export const REQUIRED_CAPABILITIES = ["getPartyId", "getActiveContracts", "submitCommand"];
+/** Optional capabilities — filled with safe no-ops when a wallet does not support them. */
+export const OPTIONAL_CAPABILITIES = ["payDueGasIfAny", "getHolding", "getAmuletRules", "getOpenMiningRounds", "disconnect"];
+/** 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 () => 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 () => 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 () => null,
+    getOpenMiningRounds: async () => null,
+    // Stateless/headless wallets hold no connection to tear down.
+    disconnect: async () => undefined,
+};
+/** Returns true if `value` was produced by {@link defineWalletAdapter}. */
+export function isWalletAdapter(value) {
+    return Boolean(value && value[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) {
+    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 : (() => null),
+    };
+    return adapter;
+}

package/dist/canton/wallet/loop.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { type WalletAdapter } from "./adapter.js";
+/**
+ * Create a universal wallet adapter backed by a Loop SDK instance.
+ */
+export declare function createLoopWalletAdapter(loop: unknown): WalletAdapter;

package/dist/canton/wallet/loop.js

@@ -0,0 +1,87 @@
+/**
+ * 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 } from "./adapter.js";
+/**
+ * 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) {
+    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) {
+    if (!loop || typeof loop !== "object") {
+        throw new Error("[Temple SDK] createLoopWalletAdapter requires a Loop wallet instance.");
+    }
+    const sdk = loop;
+    const isServer = detectServerSide(sdk);
+    // The provider sub-object handles reads (getActiveContracts) and client-side
+    // submission (submitTransaction). Fall back to the instance itself.
+    const provider = 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?.message || String(error)}`);
+            }
+        },
+        // getHolding / getAmuletRules / getOpenMiningRounds / disconnect: not
+        // provided by Loop here — the adapter inherits the safe no-op defaults.
+    });
+}

package/dist/canton/wallet/service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { type WalletAdapter } from "./adapter.js";
+/** Register the active wallet adapter. Pass null to clear it. */
+export declare function setActiveAdapter(adapter: WalletAdapter | null): void;
+/** Get the active wallet adapter, or null when none is set. */
+export declare function getActiveAdapter(): WalletAdapter | null;
+/** True when a wallet adapter is configured. */
+export declare function hasActiveAdapter(): boolean;
+/** Resolve the active wallet's party id. Throws when no adapter is configured. */
+export declare function getPartyId(): string | null;
+/** Sign and submit a ledger command. Throws when no adapter is configured. */
+export declare function submitCommand(command: unknown): Promise<unknown>;
+/**
+ * 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 declare function getActiveContractReader(providerOverride?: unknown): unknown;
+/**
+ * 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 declare function payDueGasIfAny(): Promise<void>;

package/dist/canton/wallet/service.js

@@ -0,0 +1,72 @@
+/**
+ * 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 } from "./adapter.js";
+/** The single active, normalized wallet adapter (or null when none is set). */
+let _activeAdapter = null;
+/** Register the active wallet adapter. Pass null to clear it. */
+export function setActiveAdapter(adapter) {
+    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() {
+    return _activeAdapter;
+}
+/** True when a wallet adapter is configured. */
+export function hasActiveAdapter() {
+    return _activeAdapter !== null;
+}
+function requireAdapter() {
+    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() {
+    return requireAdapter().getPartyId();
+}
+/** Sign and submit a ledger command. Throws when no adapter is configured. */
+export function submitCommand(command) {
+    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 = null) {
+    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() {
+    if (!_activeAdapter)
+        return;
+    return _activeAdapter.payDueGasIfAny();
+}

package/dist/canton/walletAdapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 type { WalletAdapter } from "./wallet/adapter.js";
+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 declare function setWalletAdapter(adapter: unknown): void;
+/**
+ * Get the active (normalized) wallet adapter, or null when none is set.
+ */
+export declare function getWalletAdapter(): WalletAdapter | null;
+/**
+ * Returns the provider sub-object used for read operations (getActiveContracts).
+ * Kept for backward compatibility; resolves the active adapter's raw provider.
+ */
+export declare function getAdapterProvider(): unknown;
+/**
+ * Check if the active adapter runs in server mode.
+ */
+export declare function isServerMode(): boolean;
+/**
+ * Get the party ID from the active wallet adapter, or null when none is set.
+ */
+export declare function getAdapterPartyId(): string | 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 declare function payDueGasIfAny(): Promise<void>;
+/**
+ * Submit a command via the active wallet adapter.
+ * Throws when no adapter is configured.
+ */
+export declare function submitCommand(command: unknown): Promise<unknown>;

package/dist/canton/walletAdapter.js

@@ -0,0 +1,78 @@
+/**
+ * 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";
+// 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";
+/**
+ * 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) {
+    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() {
+    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() {
+    const adapter = getActiveAdapter();
+    if (!adapter)
+        return null;
+    return adapter.getRawProvider() || adapter;
+}
+/**
+ * Check if the active adapter runs in server mode.
+ */
+export function isServerMode() {
+    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() {
+    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() {
+    return servicePayDueGasIfAny();
+}
+/**
+ * Submit a command via the active wallet adapter.
+ * Throws when no adapter is configured.
+ */
+export function submitCommand(command) {
+    return serviceSubmitCommand(command);
+}

package/dist/canton/withdrawals.js

@@ -2,7 +2,7 @@ import config from "../../src/config/index.js";
 import axios from "axios";
 import { getDisclosures, createWithdrawalRequest, getWithdrawalRequestStatus, 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, normalizeContractId, resolveInstrumentDefinition, getInstrumentRegistrar, resolveProvider, dedupeDisclosedContracts, buildHeaders, DEFAULT_AMULET_CONTEXT_KEYS, DEFAULT_UTILITY_CONTEXT_KEYS, } from "./helpers.js";
 import { resolveAmuletContext, resolveUtilityInstrumentConfiguration, resolveUtilityAllocationFactory, getUtxoCount, } from "../../src/canton/index.js";
 import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";

package/package.json

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