@arkade-os/sdk 0.3.13 → 0.4.0-next.1

package/dist/esm/wallet/asset.js

@@ -0,0 +1,111 @@
+import { AssetGroup, AssetId, AssetInput, AssetOutput, Packet, } from '../asset/index.js';
+/**
+ * Creates an asset packet from asset inputs and receivers.
+ * Groups inputs and outputs by asset ID and creates the Packet object
+ * @param assetInputs - map input index -> assets
+ * @param receivers - array of recipients with their asset allocations
+ * @param changeReceiver - (optional) change receiver containing remaining assets
+ * @returns packet containing all asset groups
+ */
+export function createAssetPacket(assetInputs, receivers, changeReceiver) {
+    // map inputs by asset id
+    const inputsByAssetId = new Map();
+    for (const [inputIndex, assets] of assetInputs) {
+        for (const asset of assets) {
+            const existing = inputsByAssetId.get(asset.assetId);
+            inputsByAssetId.set(asset.assetId, [
+                ...(existing ?? []),
+                AssetInput.create(inputIndex, BigInt(asset.amount)),
+            ]);
+        }
+    }
+    // map outputs by asset id
+    const outputsByAssetId = new Map();
+    // track tx output index
+    let outputIndex = 0;
+    for (const receiver of receivers) {
+        if (receiver.assets) {
+            for (const asset of receiver.assets) {
+                const existing = outputsByAssetId.get(asset.assetId);
+                outputsByAssetId.set(asset.assetId, [
+                    ...(existing ?? []),
+                    AssetOutput.create(outputIndex, BigInt(asset.amount)),
+                ]);
+            }
+        }
+        outputIndex++;
+    }
+    // add change receiver assets if present
+    if (changeReceiver?.assets) {
+        for (const asset of changeReceiver.assets) {
+            const existing = outputsByAssetId.get(asset.assetId);
+            outputsByAssetId.set(asset.assetId, [
+                ...(existing ?? []),
+                AssetOutput.create(outputIndex, BigInt(asset.amount)),
+            ]);
+        }
+    }
+    const groups = [];
+    // get all unique asset ids from both inputs and outputs
+    const allAssetIds = new Set([
+        ...inputsByAssetId.keys(),
+        ...outputsByAssetId.keys(),
+    ]);
+    for (const assetIdStr of allAssetIds) {
+        const inputs = inputsByAssetId.get(assetIdStr);
+        const outputs = outputsByAssetId.get(assetIdStr);
+        const assetId = AssetId.fromString(assetIdStr);
+        const group = AssetGroup.create(assetId, null, inputs ?? [], outputs ?? [], []);
+        groups.push(group);
+    }
+    return Packet.create(groups);
+}
+/**
+ * Selects coins that contain a specific asset.
+ * Returns coins sorted by amount (smallest first for better coin selection).
+ */
+export function selectCoinsWithAsset(coins, assetId, requiredAmount) {
+    // filter only coins that have the specified asset
+    const coinsWithAsset = coins.filter((coin) => coin.assets?.some((a) => a.assetId === assetId));
+    // sort by asset amount (smallest first for better selection)
+    coinsWithAsset.sort((a, b) => {
+        const amountA = a.assets?.find((asset) => asset.assetId === assetId)?.amount ?? 0;
+        const amountB = b.assets?.find((asset) => asset.assetId === assetId)?.amount ?? 0;
+        return amountA - amountB;
+    });
+    const selected = [];
+    let totalAssetAmount = 0n;
+    for (const coin of coinsWithAsset) {
+        if (totalAssetAmount >= requiredAmount)
+            break;
+        selected.push(coin);
+        const assetAmount = coin.assets?.find((a) => a.assetId === assetId)?.amount ?? 0;
+        totalAssetAmount += BigInt(assetAmount);
+    }
+    if (totalAssetAmount < requiredAmount) {
+        throw new Error(`Insufficient asset balance: have ${totalAssetAmount}, need ${requiredAmount}`);
+    }
+    return { selected, totalAssetAmount };
+}
+export function computeAssetChange(inputAssets, outputAssets) {
+    const change = new Map();
+    for (const [assetId, inputAmount] of inputAssets) {
+        const outputAmount = outputAssets.get(assetId) ?? 0n;
+        const changeAmount = inputAmount - outputAmount;
+        if (changeAmount > 0n) {
+            change.set(assetId, changeAmount);
+        }
+    }
+    return change;
+}
+export function selectedCoinsToAssetInputs(selectedCoins) {
+    const assetInputs = new Map();
+    for (let inputIndex = 0; inputIndex < selectedCoins.length; inputIndex++) {
+        const coin = selectedCoins[inputIndex];
+        if (!coin.assets || coin.assets.length === 0) {
+            continue;
+        }
+        assetInputs.set(inputIndex, coin.assets);
+    }
+    return assetInputs;
+}

package/dist/esm/wallet/batch.js

@@ -8,7 +8,7 @@ import { hex } from "@scure/base";
  * @example
  * ```typescript
  * // use wallet handler or create a custom one
- * const handler = wallet.createBatchHandler(intentId, inputs, musig2session);
+ * const handler = wallet.createBatchHandler(intentId, inputs, expectedRecipients, musig2session);
  *
  * const abortController = new AbortController();
  * // Get event stream from Ark provider

package/dist/esm/wallet/delegator.js

@@ -0,0 +1,231 @@
+import { ArkAddress, decodeTapscript, Estimator, Intent, isRecoverable, MultisigTapscript, VtxoScript, } from '../index.js';
+import { base64, hex } from "@scure/base";
+import { scriptFromTapLeafScript } from '../script/base.js';
+import { buildForfeitTxWithOutput } from '../forfeit.js';
+import { Address, OutScript, SigHash } from "@scure/btc-signer";
+import { getNetwork } from '../networks.js';
+export class DelegatorManagerImpl {
+    constructor(delegatorProvider, arkInfoProvider, identity) {
+        this.delegatorProvider = delegatorProvider;
+        this.arkInfoProvider = arkInfoProvider;
+        this.identity = identity;
+    }
+    async delegate(vtxos, destination, delegateAt) {
+        if (vtxos.length === 0) {
+            return { delegated: [], failed: [] };
+        }
+        const destinationScript = ArkAddress.decode(destination).pkScript;
+        // if explicit delegateAt is provided, delegate all vtxos at once without sorting
+        if (delegateAt) {
+            try {
+                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxos, destinationScript, delegateAt);
+            }
+            catch (error) {
+                return { delegated: [], failed: [{ outpoints: vtxos, error }] };
+            }
+            return { delegated: vtxos, failed: [] };
+        }
+        // if no explicit delegateAt is provided, sort vtxos by expiry and delegate in groups of the same expiry day
+        const groupByExpiry = new Map();
+        let recoverableVtxos = [];
+        for (const vtxo of vtxos) {
+            if (isRecoverable(vtxo)) {
+                recoverableVtxos.push(vtxo);
+                continue;
+            }
+            const expiry = vtxo.virtualStatus.batchExpiry;
+            if (!expiry)
+                continue;
+            const dayKey = getDayTimestamp(expiry);
+            groupByExpiry.set(dayKey, [
+                ...(groupByExpiry.get(dayKey) ?? []),
+                vtxo,
+            ]);
+        }
+        // if no groups, it means we only need to delegate the recoverable vtxos
+        if (groupByExpiry.size === 0) {
+            try {
+                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, recoverableVtxos, destinationScript, delegateAt);
+            }
+            catch (error) {
+                return {
+                    delegated: [],
+                    failed: [{ outpoints: recoverableVtxos, error }],
+                };
+            }
+            return { delegated: recoverableVtxos, failed: [] };
+        }
+        // search for the earliest group, include recoverable vtxos into it
+        const earliestGroup = Math.min(...groupByExpiry.keys());
+        groupByExpiry.set(earliestGroup, [
+            ...(groupByExpiry.get(earliestGroup) ?? []),
+            ...recoverableVtxos,
+        ]);
+        const groupsList = Array.from(groupByExpiry.entries());
+        const result = await Promise.allSettled(groupsList.map(async ([, vtxosGroup]) => delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxosGroup, destinationScript)));
+        const delegated = [];
+        const failed = [];
+        for (const [index, resultItem] of result.entries()) {
+            const vtxos = groupsList[index][1];
+            if (resultItem.status === "rejected") {
+                failed.push({ outpoints: vtxos, error: resultItem.reason });
+                continue;
+            }
+            delegated.push(...vtxos);
+        }
+        return { delegated, failed };
+    }
+}
+/**
+ * Delegates virtual coins to a delegator provider, allowing them to manage the coins renewal
+ * on behalf of the wallet.
+ * @param vtxos - Array of extended virtual coins to delegate. Must not be empty.
+ * @param delegateAt - Optional Date specifying when the delegation
+ *                     should occur. If not provided, defaults to 12 hours before the earliest
+ *                     expiry time of the provided vtxos.
+ */
+async function delegate(identity, delegatorProvider, arkInfoProvider, vtxos, destinationScript, delegateAt) {
+    if (vtxos.length === 0) {
+        throw new Error("unable to delegate: no vtxos provided");
+    }
+    if (!delegatorProvider) {
+        throw new Error("unable to delegate: delegator provider not configured");
+    }
+    if (!delegateAt) {
+        const expiryTimestamp = vtxos
+            .filter((coin) => !isRecoverable(coin) && coin.virtualStatus.batchExpiry)
+            .reduce((min, coin) => Math.min(min, coin.virtualStatus.batchExpiry), Number.MAX_SAFE_INTEGER);
+        if (!expiryTimestamp || expiryTimestamp === Number.MAX_SAFE_INTEGER) {
+            // if no expiry (recoverable vtxos), delegate 1 minute from now
+            delegateAt = new Date(Date.now() + 1 * 60 * 1000);
+        }
+        else {
+            const remainingTimeMs = expiryTimestamp - Date.now();
+            if (remainingTimeMs <= 0) {
+                delegateAt = new Date(Date.now() + 1 * 60 * 1000);
+            }
+            else {
+                // delegate 10% before the expiry
+                delegateAt = new Date(expiryTimestamp - remainingTimeMs * 0.1);
+            }
+        }
+    }
+    const { fees, dust, forfeitAddress, network } = await arkInfoProvider.getInfo();
+    const delegateAtSeconds = delegateAt.getTime() / 1000;
+    const estimator = new Estimator({
+        ...fees.intentFee,
+        // replace now() function with the delegateAt timestamp
+        offchainInput: fees.intentFee.offchainInput?.replace("now()", `double(${delegateAtSeconds})`),
+        offchainOutput: fees.intentFee.offchainOutput?.replace("now()", `double(${delegateAtSeconds})`),
+    });
+    let amount = 0n;
+    for (const coin of vtxos) {
+        const inputFee = estimator.evalOffchainInput({
+            amount: BigInt(coin.value),
+            type: "vtxo",
+            weight: 0,
+            birth: coin.createdAt,
+            expiry: coin.virtualStatus.batchExpiry
+                ? new Date(coin.virtualStatus.batchExpiry)
+                : undefined,
+        });
+        if (inputFee.value >= coin.value) {
+            continue;
+        }
+        amount += BigInt(coin.value) - BigInt(inputFee.value);
+    }
+    const { delegatorAddress, pubkey, fee } = await delegatorProvider.getDelegateInfo();
+    const outputs = [];
+    const delegatorFee = BigInt(Number(fee));
+    if (delegatorFee > 0n) {
+        outputs.push({
+            script: ArkAddress.decode(delegatorAddress).pkScript,
+            amount: delegatorFee,
+        });
+    }
+    const outputFee = outputs.reduce((fee, output) => {
+        if (!output.amount || !output.script)
+            return fee;
+        return (fee +
+            estimator.evalOffchainOutput({
+                amount: output.amount,
+                script: hex.encode(output.script),
+            }).satoshis);
+    }, 0);
+    if (amount - BigInt(outputFee) <= dust) {
+        throw new Error("Amount is below dust limit, cannot delegate");
+    }
+    amount -= BigInt(outputFee);
+    amount -= delegatorFee;
+    if (amount <= dust) {
+        throw new Error("Amount is below dust limit, cannot delegate");
+    }
+    outputs.push({
+        script: destinationScript,
+        amount: amount,
+    });
+    const registerIntent = await makeSignedDelegateIntent(identity, vtxos, outputs, [], [pubkey], delegateAtSeconds);
+    const forfeitOutputScript = OutScript.encode(Address(getNetwork(network)).decode(forfeitAddress));
+    const forfeits = await Promise.all(vtxos
+        .filter((v) => !isRecoverable(v))
+        .map(async (coin) => {
+        const forfeit = await makeDelegateForfeitTx(coin, dust, pubkey, forfeitOutputScript, identity);
+        return base64.encode(forfeit.toPSBT());
+    }));
+    await delegatorProvider.delegate(registerIntent, forfeits);
+}
+async function makeDelegateForfeitTx(input, connectorAmount, delegatePubkey, forfeitOutputScript, identity) {
+    if (delegatePubkey.length === 66) {
+        delegatePubkey = delegatePubkey.slice(2);
+    }
+    const vtxoScript = VtxoScript.decode(input.tapTree);
+    const delegateTapLeaf = vtxoScript.leaves.find((tapLeaf) => {
+        const arkTapscript = decodeTapscript(scriptFromTapLeafScript(tapLeaf));
+        if (!MultisigTapscript.is(arkTapscript))
+            return false;
+        if (!arkTapscript.params.pubkeys
+            .map(hex.encode)
+            .includes(delegatePubkey))
+            return false;
+        return true;
+    });
+    if (!delegateTapLeaf) {
+        throw new Error(`delegate tap leaf not found for input: ${input.txid}:${input.vout}`);
+    }
+    const tx = buildForfeitTxWithOutput([
+        {
+            txid: input.txid,
+            index: input.vout,
+            witnessUtxo: {
+                amount: BigInt(input.value),
+                script: VtxoScript.decode(input.tapTree).pkScript,
+            },
+            sighashType: SigHash.ALL_ANYONECANPAY,
+            tapLeafScript: [delegateTapLeaf],
+        },
+    ], {
+        script: forfeitOutputScript,
+        amount: BigInt(input.value) + connectorAmount,
+    });
+    return identity.sign(tx);
+}
+async function makeSignedDelegateIntent(identity, coins, outputs, onchainOutputsIndexes, cosignerPubKeys, validAt) {
+    const message = {
+        type: "register",
+        onchain_output_indexes: onchainOutputsIndexes,
+        valid_at: Math.floor(validAt),
+        expire_at: 0,
+        cosigners_public_keys: cosignerPubKeys,
+    };
+    const proof = Intent.create(message, coins, outputs);
+    const signedProof = await identity.sign(proof);
+    return {
+        proof: base64.encode(signedProof.toPSBT()),
+        message,
+    };
+}
+function getDayTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    date.setUTCHours(0, 0, 0, 0);
+    return date.getTime();
+}

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

@@ -0,0 +1,128 @@
+import { hex } from "@scure/base";
+import { runTasks } from '../../worker/expo/taskRunner.js';
+import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
+import { DefaultVtxo } from '../../script/default.js';
+import { ExpoArkProvider } from '../../providers/expoArk.js';
+import { ExpoIndexerProvider } from '../../providers/expoIndexer.js';
+import { extendVirtualCoin, extendVtxoFromContract, getRandomId, } from '../utils.js';
+function requireTaskManager() {
+    try {
+        return require("expo-task-manager");
+    }
+    catch {
+        throw new Error("expo-task-manager is required for background tasks. " +
+            "Install it with: npx expo install expo-task-manager");
+    }
+}
+function requireBackgroundTask() {
+    try {
+        return require("expo-background-task");
+    }
+    catch {
+        throw new Error("expo-background-task is required for background tasks. " +
+            "Install it with: npx expo install expo-background-task");
+    }
+}
+/**
+ * Define the Expo background task handler.
+ *
+ * **Must be called at module/global scope** (before React mounts).
+ * Internally calls `TaskManager.defineTask()`.
+ *
+ * @example
+ * ```ts
+ * // At the top of your app entry file
+ * import { defineExpoBackgroundTask } from "@arkade-os/sdk/wallet/expo";
+ * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ *
+ * const taskQueue = new AsyncStorageTaskQueue(AsyncStorage);
+ * defineExpoBackgroundTask("ark-background-poll", {
+ *     taskQueue,
+ *     walletRepository: new IndexedDBWalletRepository(),
+ *     contractRepository: new IndexedDBContractRepository(),
+ * });
+ * ```
+ */
+export function defineExpoBackgroundTask(taskName, options) {
+    const TaskManager = requireTaskManager();
+    const BackgroundTask = requireBackgroundTask();
+    const { taskQueue, walletRepository, contractRepository, processors = [contractPollProcessor], } = options;
+    TaskManager.defineTask(taskName, async () => {
+        try {
+            const config = await taskQueue.loadConfig();
+            if (!config) {
+                // No config persisted yet — ExpoWallet.setup() hasn't run.
+                // Nothing to do.
+                return BackgroundTask.BackgroundTaskResult.Success;
+            }
+            // Reconstruct providers
+            const indexerProvider = new ExpoIndexerProvider(config.arkServerUrl);
+            const arkProvider = new ExpoArkProvider(config.arkServerUrl);
+            // Reconstruct default offchainTapscript as fallback
+            // for VTXOs not associated with a contract.
+            const defaultTapscript = new DefaultVtxo.Script({
+                pubKey: hex.decode(config.pubkeyHex),
+                serverPubKey: hex.decode(config.serverPubKeyHex),
+                csvTimelock: {
+                    value: BigInt(config.exitTimelockValue),
+                    type: config.exitTimelockType,
+                },
+            });
+            await runTasks(taskQueue, processors, {
+                walletRepository,
+                contractRepository,
+                indexerProvider,
+                arkProvider,
+                extendVtxo: (vtxo, contract) => {
+                    if (contract) {
+                        return extendVtxoFromContract(vtxo, contract);
+                    }
+                    return extendVirtualCoin({ offchainTapscript: defaultTapscript }, vtxo);
+                },
+            });
+            // Acknowledge outbox results (no foreground to consume them)
+            const results = await taskQueue.getResults();
+            if (results.length > 0) {
+                await taskQueue.acknowledgeResults(results.map((r) => r.id));
+            }
+            // Re-seed the contract-poll task for the next OS wake
+            const existing = await taskQueue.getTasks(CONTRACT_POLL_TASK_TYPE);
+            if (existing.length === 0) {
+                const task = {
+                    id: getRandomId(),
+                    type: CONTRACT_POLL_TASK_TYPE,
+                    data: {},
+                    createdAt: Date.now(),
+                };
+                await taskQueue.addTask(task);
+            }
+            return BackgroundTask.BackgroundTaskResult.Success;
+        }
+        catch (error) {
+            console.error("[ark-sdk] Background task failed:", error instanceof Error ? error.message : error);
+            return BackgroundTask.BackgroundTaskResult.Failed;
+        }
+    });
+}
+/**
+ * Activate the OS-level background task scheduler.
+ *
+ * Call this after {@link defineExpoBackgroundTask} (typically inside
+ * {@link ExpoWallet.setup} or in a React component after wallet init).
+ *
+ * @param minimumInterval - Minimum interval in minutes (default 15).
+ */
+export async function registerExpoBackgroundTask(taskName, options) {
+    const BackgroundTask = requireBackgroundTask();
+    await BackgroundTask.registerTaskAsync(taskName, {
+        minimumInterval: (options?.minimumInterval ?? 15) * 60,
+    });
+}
+/**
+ * Unregister the background task from the OS scheduler.
+ */
+export async function unregisterExpoBackgroundTask(taskName) {
+    const BackgroundTask = requireBackgroundTask();
+    await BackgroundTask.unregisterTaskAsync(taskName);
+}

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

@@ -0,0 +1,2 @@
+export { ExpoWallet } from './wallet.js';
+export { defineExpoBackgroundTask, registerExpoBackgroundTask, unregisterExpoBackgroundTask, } from './background.js';

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

@@ -0,0 +1,194 @@
+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 { extendVirtualCoin, extendVtxoFromContract, getRandomId, } from '../utils.js';
+import { DefaultVtxo } from '../../script/default.js';
+/**
+ * Expo/React Native wallet with built-in background task processing.
+ *
+ * Wraps a standard {@link 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: SingleKey.fromHex(privateKey),
+ *     arkServerUrl,
+ *     esploraUrl,
+ *     storage: { walletRepository, contractRepository },
+ *     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 {@link Wallet} via `Wallet.create()`.
+     * 2. Wires up processors (defaults to {@link 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) => {
+                if (contract) {
+                    return extendVtxoFromContract(vtxo, contract);
+                }
+                return extendVirtualCoin(wallet, vtxo);
+            },
+        };
+        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");
+                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");
+            await unregisterExpoBackgroundTask(this.taskName);
+        }
+        catch {
+            // expo-background-task not installed — nothing to unregister
+        }
+    }
+    // ── 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();
+    }
+    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;
+    }
+}