@arkade-os/sdk 0.4.26 → 0.4.28

package/dist/esm/wallet/expo/wallet.js

@@ -1,193 +0,0 @@
-import { hex } from "@scure/base";
-import { Wallet } from "../wallet.js";
-import { RestArkProvider } from "../../providers/ark.js";
-import { runTasks } from "../../worker/expo/taskRunner.js";
-import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from "../../worker/expo/processors/index.js";
-import { extendVirtualCoinForContract, getRandomId } from "../utils.js";
-import { DefaultVtxo } from "../../script/default.js";
-/**
- * Expo/React Native wallet with built-in background task processing.
- *
- * Wraps a standard @see Wallet and adds a lightweight task queue
- * for keeping contract/VTXO state fresh while the app is active and
- * across Expo BackgroundTask wakes.
- *
- * @example
- * ```ts
- * import { ExpoWallet } from "@arkade-os/sdk/wallet/expo";
- * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
- *
- * const wallet = await ExpoWallet.setup({
- *     identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *     arkServerUrl: 'https://arkade.computer',
- *     esploraUrl: 'https://mempool.space/api',
- *     storage: { ... },
- *     background: {
- *         taskName: "ark-background-poll",
- *         taskQueue: new AsyncStorageTaskQueue(AsyncStorage),
- *         foregroundIntervalMs: 20_000,
- *         minimumBackgroundInterval: 15,
- *     },
- * });
- *
- * const balance = await wallet.getBalance();
- * ```
- */
-export class ExpoWallet {
-    constructor(wallet, taskQueue, processors, deps, taskName, foregroundIntervalMs) {
-        this.wallet = wallet;
-        this.taskQueue = taskQueue;
-        this.processors = processors;
-        this.deps = deps;
-        this.identity = wallet.identity;
-        this.arkProvider = wallet.arkProvider;
-        this.indexerProvider = wallet.indexerProvider;
-        this.taskName = taskName;
-        if (foregroundIntervalMs && foregroundIntervalMs > 0) {
-            this.startForegroundPolling(foregroundIntervalMs);
-        }
-    }
-    /**
-     * Create an ExpoWallet with background task support.
-     *
-     * 1. Creates the inner @see Wallet via `Wallet.create()`.
-     * 2. Wires up processors (defaults to @see contractPollProcessor).
-     * 3. Persists background config for the background handler (if the queue supports it).
-     * 4. Seeds the task queue with a `contract-poll` task.
-     * 5. Registers the background task with the OS scheduler (if `minimumBackgroundInterval` is set).
-     * 6. Starts foreground polling if `foregroundIntervalMs` is set.
-     */
-    static async setup(config) {
-        const wallet = await Wallet.create(config);
-        const processors = config.background.processors ?? [
-            contractPollProcessor,
-        ];
-        const deps = {
-            walletRepository: wallet.walletRepository,
-            contractRepository: wallet.contractRepository,
-            indexerProvider: wallet.indexerProvider,
-            arkProvider: wallet.arkProvider,
-            extendVtxo: (vtxo, contract) => extendVirtualCoinForContract(vtxo, contract),
-        };
-        const { taskQueue } = config.background;
-        // Persist wallet params so the background handler can rehydrate
-        // without a network call. Only works with AsyncStorageTaskQueue.
-        if ("persistConfig" in taskQueue) {
-            const arkServerUrl = config.arkServerUrl ??
-                (wallet.arkProvider instanceof RestArkProvider
-                    ? wallet.arkProvider.serverUrl
-                    : undefined);
-            if (arkServerUrl) {
-                const timelock = wallet.offchainTapscript.options.csvTimelock ??
-                    DefaultVtxo.Script.DEFAULT_TIMELOCK;
-                const bgConfig = {
-                    arkServerUrl,
-                    pubkeyHex: hex.encode(wallet.offchainTapscript.options.pubKey),
-                    serverPubKeyHex: hex.encode(wallet.offchainTapscript.options.serverPubKey),
-                    exitTimelockValue: timelock.value.toString(),
-                    exitTimelockType: timelock.type,
-                };
-                await taskQueue.persistConfig(bgConfig);
-            }
-        }
-        const expoWallet = new ExpoWallet(wallet, taskQueue, processors, deps, config.background.taskName, config.background.foregroundIntervalMs);
-        // Seed the queue so the first tick (or background wake) has work to do
-        await expoWallet.seedContractPollTask();
-        // Activate OS-level background scheduling
-        if (config.background.minimumBackgroundInterval) {
-            try {
-                const { registerExpoBackgroundTask } = await import("./background.js");
-                await registerExpoBackgroundTask(config.background.taskName, {
-                    minimumInterval: config.background.minimumBackgroundInterval,
-                });
-            }
-            catch {
-                // expo-background-task not installed — foreground-only mode
-            }
-        }
-        return expoWallet;
-    }
-    // ── Foreground polling ───────────────────────────────────────────
-    startForegroundPolling(intervalMs) {
-        this.foregroundIntervalId = setInterval(() => {
-            this.runForegroundPoll().catch(console.error);
-        }, intervalMs);
-    }
-    async runForegroundPoll() {
-        await runTasks(this.taskQueue, this.processors, this.deps);
-        // Consume results immediately (no background handoff needed)
-        const results = await this.taskQueue.getResults();
-        if (results.length > 0) {
-            await this.taskQueue.acknowledgeResults(results.map((r) => r.id));
-        }
-        // Re-seed for the next tick
-        await this.seedContractPollTask();
-    }
-    async seedContractPollTask() {
-        const existing = await this.taskQueue.getTasks(CONTRACT_POLL_TASK_TYPE);
-        if (existing.length > 0)
-            return;
-        const task = {
-            id: getRandomId(),
-            type: CONTRACT_POLL_TASK_TYPE,
-            data: {},
-            createdAt: Date.now(),
-        };
-        await this.taskQueue.addTask(task);
-    }
-    // ── Lifecycle ────────────────────────────────────────────────────
-    /**
-     * Stop foreground polling and unregister the background task.
-     */
-    async dispose() {
-        if (this.foregroundIntervalId) {
-            clearInterval(this.foregroundIntervalId);
-            this.foregroundIntervalId = undefined;
-        }
-        try {
-            const { unregisterExpoBackgroundTask } = await import("./background.js");
-            await unregisterExpoBackgroundTask(this.taskName);
-        }
-        catch {
-            // expo-background-task not installed — nothing to unregister
-        }
-        await this.wallet.dispose();
-    }
-    // ── IWallet delegation ───────────────────────────────────────────
-    getAddress() {
-        return this.wallet.getAddress();
-    }
-    getBoardingAddress() {
-        return this.wallet.getBoardingAddress();
-    }
-    getBalance() {
-        return this.wallet.getBalance();
-    }
-    getVtxos(filter) {
-        return this.wallet.getVtxos(filter);
-    }
-    getBoardingUtxos() {
-        return this.wallet.getBoardingUtxos();
-    }
-    getTransactionHistory() {
-        return this.wallet.getTransactionHistory();
-    }
-    getContractManager() {
-        return this.wallet.getContractManager();
-    }
-    getDelegatorManager() {
-        return this.wallet.getDelegatorManager();
-    }
-    sendBitcoin(params) {
-        return this.wallet.sendBitcoin(params);
-    }
-    settle(params, eventCallback) {
-        return this.wallet.settle(params, eventCallback);
-    }
-    send(...recipients) {
-        return this.wallet.send(...recipients);
-    }
-    get assetManager() {
-        return this.wallet.assetManager;
-    }
-}

package/dist/esm/wallet/hdDescriptorProvider.js

@@ -1,155 +0,0 @@
-import { expand, networks } from "@bitcoinerlab/descriptors-scure";
-import { isMainnetDescriptor } from "../identity/descriptor.js";
-import { updateWalletState } from "../utils/syncCursors.js";
-/** Settings key under {@link WalletState.settings} where HD state lives. */
-const HD_SETTINGS_KEY = "hd";
-/**
- * HD-wallet {@link DescriptorProvider} that allocates a fresh signing
- * descriptor on every call. The provider holds no notion of "current" — it
- * is a pure rotating allocator. The question of "which descriptor is the
- * wallet currently bound to?" is answered by querying the contract
- * repository for active contracts, not by asking this provider.
- *
- * State is persisted under `WalletRepository.getWalletState().settings.hd` so
- * that no storage-schema migration is required when switching a wallet from
- * single-key to HD. The provider is backed by an {@link HDCapableIdentity},
- * which carries the wildcard account descriptor template (for derivation)
- * and the signing primitives.
- *
- * The read-modify-write of the persisted index runs inside the shared per-
- * repo `updateWalletState` mutex, so two `getNextSigningDescriptor` callers
- * — including those driving separate `HDDescriptorProvider` instances on
- * the same repo — can never observe the same index.
- *
- * @example
- * ```ts
- * const provider = await HDDescriptorProvider.create(identity, walletRepo);
- * const descriptor = await provider.getNextSigningDescriptor();
- * // descriptor: tr([fp/86'/0'/0']xpub/0/0)
- * const next = await provider.getNextSigningDescriptor();
- * // next: tr([fp/86'/0'/0']xpub/0/1)
- * ```
- */
-export class HDDescriptorProvider {
-    constructor(identity, walletRepository) {
-        this.identity = identity;
-        this.walletRepository = walletRepository;
-    }
-    /**
-     * Construct an HDDescriptorProvider. No I/O is performed here;
-     * persisted state is read lazily on the first call to
-     * `getNextSigningDescriptor`. A descriptor-mismatch error surfaces on
-     * first use rather than at boot.
-     */
-    static async create(identity, walletRepository) {
-        return new HDDescriptorProvider(identity, walletRepository);
-    }
-    /**
-     * Allocate the next descriptor and return it. The first call on a fresh
-     * wallet returns descriptor at index 0; subsequent calls return 1, 2, 3,
-     * ... in order. Each call is atomic with respect to other rotations on
-     * the same repo: two concurrent callers can never observe the same
-     * index.
-     */
-    async getNextSigningDescriptor() {
-        return this.mutate((settings) => {
-            const next = settings.lastIndexUsed === undefined
-                ? 0
-                : settings.lastIndexUsed + 1;
-            settings.lastIndexUsed = next;
-            return this.materializeAt(next);
-        });
-    }
-    /**
-     * Returns true when the given descriptor is derivable from this wallet's
-     * seed. Delegates to the underlying identity, which handles both HD and
-     * simple `tr(pubkey)` descriptors.
-     */
-    isOurs(descriptor) {
-        return this.identity.isOurs(descriptor);
-    }
-    /**
-     * Signs each request with the key derived from its descriptor. Delegates
-     * to the identity's signing primitives — the identity, not the provider,
-     * holds the seed.
-     */
-    async signWithDescriptor(requests) {
-        return this.identity.signWithDescriptor(requests);
-    }
-    /** Signs a message using the key derived from `descriptor`. */
-    async signMessageWithDescriptor(descriptor, message, signatureType = "schnorr") {
-        return this.identity.signMessageWithDescriptor(descriptor, message, signatureType);
-    }
-    // ── internals ────────────────────────────────────────────────────
-    /**
-     * Substitute the wildcard in the identity's account-descriptor template
-     * with a concrete index, going through the descriptors-scure parser
-     * rather than ad-hoc string substitution. The parser's `expand({ index })`
-     * call validates that the input is a ranged template AND produces a
-     * canonical materialized key expression at the given index.
-     */
-    materializeAt(index) {
-        const descriptor = this.identity.descriptor;
-        const network = isMainnetDescriptor(descriptor)
-            ? networks.bitcoin
-            : networks.testnet;
-        const expansion = expand({ descriptor, network, index });
-        const keyInfo = expansion.expansionMap?.["@0"];
-        if (!keyInfo?.keyExpression) {
-            throw new Error(`HDDescriptorProvider: cannot materialize descriptor at index ${index}`);
-        }
-        return `tr(${keyInfo.keyExpression})`;
-    }
-    /**
-     * Run the read-modify-write of HD settings inside the shared per-repo
-     * wallet-state mutex. The closure receives a freshly-validated settings
-     * snapshot, mutates it, and returns whatever value the caller wants to
-     * surface; the mutated settings are then persisted as part of the same
-     * atomic update.
-     *
-     * Doing the read inside the lock is what prevents two providers (or two
-     * concurrent callers on the same provider) from racing on a stale index.
-     */
-    async mutate(fn) {
-        let result;
-        await updateWalletState(this.walletRepository, (state) => {
-            const settings = this.parseSettings(state);
-            result = fn(settings);
-            return {
-                ...state,
-                settings: {
-                    ...(state.settings ?? {}),
-                    [HD_SETTINGS_KEY]: settings,
-                },
-            };
-        });
-        return result;
-    }
-    /**
-     * Validate the persisted HD settings (or initialize a fresh record when
-     * absent) and return a clone safe for the caller to mutate.
-     *
-     * The cast to `HDWalletSettings` trusts storage; a corrupted or
-     * partially-migrated repo could otherwise produce `NaN` descriptors.
-     * Fail loud rather than silently derive garbage.
-     */
-    parseSettings(state) {
-        const stored = state.settings?.[HD_SETTINGS_KEY];
-        const expected = this.identity.descriptor;
-        if (!stored) {
-            return { descriptor: expected };
-        }
-        if (stored.descriptor !== expected) {
-            throw new Error(`HD descriptor mismatch: stored "${stored.descriptor}", expected "${expected}". ` +
-                `Refusing to reuse HD state from a different identity.`);
-        }
-        if (stored.lastIndexUsed !== undefined &&
-            (typeof stored.lastIndexUsed !== "number" ||
-                !Number.isInteger(stored.lastIndexUsed) ||
-                stored.lastIndexUsed < 0)) {
-            throw new Error(`Corrupt HD settings: lastIndexUsed is not a non-negative integer (got ${String(stored.lastIndexUsed)}).`);
-        }
-        // Shallow clone so the closure may mutate without aliasing the repo's copy.
-        return { ...stored };
-    }
-}

package/dist/esm/wallet/index.js

@@ -1,75 +0,0 @@
-/** Defaults */
-export const DEFAULT_ARKADE_SERVER_URL = "https://arkade.computer";
-export const DEFAULT_ARKADE_HRP = "ark";
-export const DEFAULT_NETWORK_NAME = "bitcoin";
-/** Wallet transaction direction. */
-export var TxType;
-(function (TxType) {
-    TxType["TxSent"] = "SENT";
-    TxType["TxReceived"] = "RECEIVED";
-})(TxType || (TxType = {}));
-/**
- * Return whether a virtual output is still spendable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is not marked as spent
- *
- * @see isRecoverable
- * @see isExpired
- */
-export function isSpendable(vtxo) {
-    return !vtxo.isSpent;
-}
-/**
- * Return whether a virtual output is recoverable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept but still spendable
- *
- * @remarks
- * Recoverable virtual outputs are typically re-settled into fresh virtual outputs by the virtual output manager.
- *
- * @see isSpendable
- * @see isExpired
- */
-export function isRecoverable(vtxo) {
-    return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
-}
-/**
- * Return whether a virtual output should be treated as expired.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept or its batch expiry has passed
- * @remarks
- * On regtest-like environments the upstream expiry value may be expressed as a block
- * height instead of a timestamp. This helper intentionally ignores obviously non-time
- * values to avoid false positives.
- *
- * @see VirtualStatus.batchExpiry
- */
-export function isExpired(vtxo) {
-    if (vtxo.virtualStatus.state === "swept")
-        return true; // swept by server = expired
-    const expiry = vtxo.virtualStatus.batchExpiry;
-    if (!expiry)
-        return false;
-    // we use this as a workaround to avoid issue on regtest where expiry date is expressed in blockheight instead of timestamp
-    // if expiry, as Date, is before 2025, then we admit it's too small to be a timestamp
-    // TODO: API should return the expiry unit
-    const expireAt = new Date(expiry);
-    if (expireAt.getFullYear() < 2025)
-        return false;
-    return expiry <= Date.now();
-}
-/**
- * Return whether a virtual output is below the dust threshold.
- *
- * @param vtxo - virtual output to inspect
- * @param dust - dust threshold in satoshis
- * @returns `true` when the virtual output value is below `dust`
- *
- * @see isRecoverable
- */
-export function isSubdust(vtxo, dust) {
-    return vtxo.value < dust;
-}