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

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";

package/dist/canton/helpers.d.ts

@@ -66,7 +66,11 @@ export declare function shouldUseLedgerForMetadata(): boolean;
 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 = {
@@ -89,9 +89,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",
   "description": "JavaScript library for interacting with Temple Canton blockchain",
   "type": "module",
   "main": "index.js",

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,

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 ───────────────────────────────────────────────────────────────
@@ -141,9 +141,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 {

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>;

package/src/canton/walletAdapter.js

@@ -1,112 +0,0 @@
-/**
- * Wallet Adapter Module
- *
- * Provides a unified interface for wallet interactions (reads and writes).
- * Currently supports Loop Wallet. Designed to support additional wallets in the future.
- *
- * Server-side (Loop): uses executeTransaction() — signs locally with private key
- * Client-side (Loop): uses submitTransaction() — delegates signing to Loop Wallet via WebSocket
- *
- * Detection: Loop server-side has null connection.ticketId and connection.ws
- */
-
-let _adapter = null;
-let _isServer = false;
-
-/**
- * Set the wallet adapter (e.g., Loop SDK instance).
- * Auto-detects server vs client mode.
- */
-export function setWalletAdapter(adapter) {
-	_adapter = adapter;
-	_isServer = adapter ? detectServerSide(adapter) : false;
-}
-
-/**
- * Get the current wallet adapter.
- */
-export function getWalletAdapter() {
-	return _adapter;
-}
-
-/**
- * Returns the provider sub-object used for read operations (getActiveContracts).
- * For Loop, this is adapter.provider.
- */
-export function getAdapterProvider() {
-	if (!_adapter) return null;
-	return _adapter.provider || _adapter;
-}
-
-/**
- * Check if running in server mode.
- */
-export function isServerMode() {
-	return _isServer;
-}
-
-/**
- * Detect if the adapter is server-side.
- * Loop-specific: server-side has null connection.ticketId and connection.ws
- */
-function detectServerSide(adapter) {
-	if (adapter?.connection) {
-		return adapter.connection.ticketId == null && adapter.connection.ws == null;
-	}
-	// If no connection object, assume server-side (e.g., headless/API usage)
-	return true;
-}
-
-/**
- * Get the party ID from the wallet adapter.
- * For Loop, this is on adapter.connection.partyId or adapter.partyId.
- */
-export function getAdapterPartyId() {
-	if (!_adapter) return null;
-	return _adapter.provider?.party_id || _adapter.session?.partyId || null;
-}
-
-/**
- * Pay any outstanding network gas before submitting a transaction or reading balances.
- * Server-side only — client-side gas is handled by the Loop Wallet UI.
- */
-export async function payDueGasIfAny() {
-	if (!_isServer || !_adapter) return;
-	if (typeof _adapter.checkDueGas !== "function" || typeof _adapter.payGas !== "function") return;
-
-	try {
-		const dueGas = await _adapter.checkDueGas();
-		if (dueGas?.pending && dueGas?.tracking_id) {
-			console.log(`[Temple SDK] Paying outstanding network gas (tracking_id=${dueGas.tracking_id})`);
-			await _adapter.payGas(dueGas.tracking_id);
-		}
-	} catch (error) {
-		console.warn(`[Temple SDK] checkDueGas/payGas failed: ${error?.message || error}`);
-	}
-}
-
-/**
- * Submit a command via the wallet adapter.
- * Server-side: calls adapter.executeTransaction(command)
- * Client-side: calls adapter.provider.submitTransaction(command)
- *
- * Note: callers of deposit/withdrawal/delegation should call payDueGasIfAny()
- * at the start of their action to ensure any outstanding gas is paid before
- * pulling UTXOs or submitting the command.
- */
-export async function submitCommand(command) {
-	if (!_adapter) {
-		throw new Error("[Temple SDK] No wallet adapter configured. Call initialize() with WALLET_ADAPTER or setWalletAdapter() first.");
-	}
-
-	if (_isServer && typeof _adapter.executeTransaction === 'function') {
-		return _adapter.executeTransaction(command);
-	}
-
-	const provider = _adapter.provider || _adapter;
-	if (typeof provider.submitTransaction === 'function') {
-		return provider.submitTransaction(command);
-	}
-
-	throw new Error("[Temple SDK] Wallet adapter does not support transaction submission.");
-}