@arkade-os/sdk 0.4.27 → 0.4.29

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,184 +0,0 @@
-import { expand, networks } from "@bitcoinerlab/descriptors-scure";
-import { isMainnetDescriptor } from "../identity/descriptor.js";
-import { updateWalletState } from "../utils/syncCursors.js";
-import { WalletReceiveRotator, } from "./walletReceiveRotator.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);
-        });
-    }
-    /**
-     * Re-derive the descriptor at the most recently allocated index
-     * WITHOUT advancing — i.e. read the same descriptor
-     * `getNextSigningDescriptor` last returned. Returns `undefined`
-     * when no descriptor has ever been allocated on this repo.
-     *
-     * Used by the boot path to keep the wallet's display address
-     * stable across restarts: when no tagged display contract exists
-     * (e.g. a fresh wallet that hasn't rotated yet, or a wallet whose
-     * baseline-only repo carries no rotation history), the boot should
-     * re-derive the existing index rather than burn a new one.
-     */
-    async getCurrentSigningDescriptor() {
-        const state = await this.walletRepository.getWalletState();
-        const settings = this.parseSettings(state ?? {});
-        if (settings.lastIndexUsed === undefined)
-            return undefined;
-        return this.materializeAt(settings.lastIndexUsed);
-    }
-    /**
-     * 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);
-    }
-    /**
-     * HD providers participate in receive rotation. The default
-     * factory boot (contract-repo lookup → allocate fresh descriptor)
-     * is exactly what we want, so this just delegates to
-     * {@link WalletReceiveRotator.defaultBoot}.
-     */
-    async createReceiveRotator(opts) {
-        return WalletReceiveRotator.defaultBoot(this, opts);
-    }
-    // ── 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;
-}

package/dist/esm/wallet/inputSignerRouter.js

@@ -1,94 +0,0 @@
-import { hex } from "@scure/base";
-import { DescriptorSigningProviderMissingError, MissingSigningDescriptorError, } from "./signingErrors.js";
-const DESCRIPTOR_CAPABLE_CONTRACT_TYPES = new Set(["default", "delegate"]);
-/**
- * Routes PSBT inputs to the correct signer based on the owning contract.
- * Inputs whose script matches a `default`/`delegate` contract with a
- * non-baseline owner are sent to {@link DescriptorProvider}; everything
- * else (baseline-owned contracts, non-default/non-delegate contracts,
- * and the boarding script) is sent to {@link Identity}. Inputs with no
- * matching contract and no boarding match are silently skipped, matching
- * how the wallet historically handled cosigner/connector inputs.
- */
-export class InputSignerRouter {
-    constructor(deps) {
-        this.deps = deps;
-    }
-    async sign(tx, jobs) {
-        if (jobs.length === 0)
-            return tx;
-        const distinctScripts = Array.from(new Set(jobs.map((j) => hex.encode(j.lookupScript))));
-        const contracts = await this.deps.contractRepository.getContracts({
-            script: distinctScripts,
-        });
-        // Repo may yield duplicates if seeded oddly; keep the first one
-        // for each script to match the wallet's historical behaviour.
-        const scriptToContract = new Map();
-        for (const contract of contracts) {
-            if (!scriptToContract.has(contract.script)) {
-                scriptToContract.set(contract.script, contract);
-            }
-        }
-        const baselinePubKeyHex = hex.encode(await this.deps.identity.xOnlyPublicKey());
-        const boardingScriptHex = hex.encode(this.deps.boardingPkScript);
-        const identityIndexes = [];
-        const descriptorGroups = new Map();
-        for (const job of jobs) {
-            const scriptHex = hex.encode(job.lookupScript);
-            const contract = scriptToContract.get(scriptHex);
-            if (!contract) {
-                if (scriptHex === boardingScriptHex) {
-                    identityIndexes.push(job.index);
-                }
-                continue;
-            }
-            if (!DESCRIPTOR_CAPABLE_CONTRACT_TYPES.has(contract.type)) {
-                identityIndexes.push(job.index);
-                continue;
-            }
-            // `baselinePubKeyHex` is freshly produced by `hex.encode`,
-            // so it is already lowercase. `contract.params.pubKey` is
-            // persisted data: a migration or custom repository adapter
-            // could legitimately store it uppercase, so canonicalize
-            // before comparing to match the legacy router behaviour.
-            const ownerPubKeyHex = contract.params.pubKey?.toLowerCase();
-            if (ownerPubKeyHex && ownerPubKeyHex === baselinePubKeyHex) {
-                identityIndexes.push(job.index);
-                continue;
-            }
-            const descriptor = contract.metadata?.signingDescriptor;
-            if (typeof descriptor !== "string" || descriptor.length === 0) {
-                throw new MissingSigningDescriptorError(contract.script, contract.type);
-            }
-            const bucket = descriptorGroups.get(descriptor);
-            if (bucket) {
-                bucket.push(job.index);
-            }
-            else {
-                descriptorGroups.set(descriptor, [job.index]);
-            }
-        }
-        let signed = tx;
-        if (identityIndexes.length > 0) {
-            signed = await this.deps.identity.sign(signed, identityIndexes);
-        }
-        if (descriptorGroups.size > 0) {
-            if (!this.deps.descriptorProvider) {
-                throw new DescriptorSigningProviderMissingError();
-            }
-            const sortedDescriptors = Array.from(descriptorGroups.keys()).sort();
-            for (const descriptor of sortedDescriptors) {
-                const indexes = descriptorGroups.get(descriptor);
-                const [next] = await this.deps.descriptorProvider.signWithDescriptor([
-                    {
-                        tx: signed,
-                        descriptor,
-                        inputIndexes: indexes,
-                    },
-                ]);
-                signed = next;
-            }
-        }
-        return signed;
-    }
-}