@arkade-os/sdk 0.3.12 → 0.4.0-next.0

package/dist/cjs/wallet/asset.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAssetPacket = createAssetPacket;
+exports.selectCoinsWithAsset = selectCoinsWithAsset;
+exports.computeAssetChange = computeAssetChange;
+exports.selectedCoinsToAssetInputs = selectedCoinsToAssetInputs;
+const asset_1 = require("../asset");
+/**
+ * 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
+ */
+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 ?? []),
+                asset_1.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 ?? []),
+                    asset_1.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 ?? []),
+                asset_1.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 = asset_1.AssetId.fromString(assetIdStr);
+        const group = asset_1.AssetGroup.create(assetId, null, inputs ?? [], outputs ?? [], []);
+        groups.push(group);
+    }
+    return asset_1.Packet.create(groups);
+}
+/**
+ * Selects coins that contain a specific asset.
+ * Returns coins sorted by amount (smallest first for better coin selection).
+ */
+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 };
+}
+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;
+}
+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/cjs/wallet/batch.js

@@ -11,7 +11,7 @@ const base_1 = require("@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/cjs/wallet/delegator.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegatorManagerImpl = void 0;
+const __1 = require("..");
+const base_1 = require("@scure/base");
+const base_2 = require("../script/base");
+const forfeit_1 = require("../forfeit");
+const btc_signer_1 = require("@scure/btc-signer");
+const networks_1 = require("../networks");
+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 = __1.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 ((0, __1.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 };
+    }
+}
+exports.DelegatorManagerImpl = DelegatorManagerImpl;
+/**
+ * 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) => !(0, __1.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 __1.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: __1.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: base_1.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 = btc_signer_1.OutScript.encode((0, btc_signer_1.Address)((0, networks_1.getNetwork)(network)).decode(forfeitAddress));
+    const forfeits = await Promise.all(vtxos
+        .filter((v) => !(0, __1.isRecoverable)(v))
+        .map(async (coin) => {
+        const forfeit = await makeDelegateForfeitTx(coin, dust, pubkey, forfeitOutputScript, identity);
+        return base_1.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 = __1.VtxoScript.decode(input.tapTree);
+    const delegateTapLeaf = vtxoScript.leaves.find((tapLeaf) => {
+        const arkTapscript = (0, __1.decodeTapscript)((0, base_2.scriptFromTapLeafScript)(tapLeaf));
+        if (!__1.MultisigTapscript.is(arkTapscript))
+            return false;
+        if (!arkTapscript.params.pubkeys
+            .map(base_1.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 = (0, forfeit_1.buildForfeitTxWithOutput)([
+        {
+            txid: input.txid,
+            index: input.vout,
+            witnessUtxo: {
+                amount: BigInt(input.value),
+                script: __1.VtxoScript.decode(input.tapTree).pkScript,
+            },
+            sighashType: btc_signer_1.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 = __1.Intent.create(message, coins, outputs);
+    const signedProof = await identity.sign(proof);
+    return {
+        proof: base_1.base64.encode(signedProof.toPSBT()),
+        message,
+    };
+}
+function getDayTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    date.setUTCHours(0, 0, 0, 0);
+    return date.getTime();
+}

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

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineExpoBackgroundTask = defineExpoBackgroundTask;
+exports.registerExpoBackgroundTask = registerExpoBackgroundTask;
+exports.unregisterExpoBackgroundTask = unregisterExpoBackgroundTask;
+const base_1 = require("@scure/base");
+const taskRunner_1 = require("../../worker/expo/taskRunner");
+const processors_1 = require("../../worker/expo/processors");
+const default_1 = require("../../script/default");
+const expoArk_1 = require("../../providers/expoArk");
+const expoIndexer_1 = require("../../providers/expoIndexer");
+const utils_1 = require("../utils");
+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(),
+ * });
+ * ```
+ */
+function defineExpoBackgroundTask(taskName, options) {
+    const TaskManager = requireTaskManager();
+    const BackgroundTask = requireBackgroundTask();
+    const { taskQueue, walletRepository, contractRepository, processors = [processors_1.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 expoIndexer_1.ExpoIndexerProvider(config.arkServerUrl);
+            const arkProvider = new expoArk_1.ExpoArkProvider(config.arkServerUrl);
+            // Reconstruct default offchainTapscript as fallback
+            // for VTXOs not associated with a contract.
+            const defaultTapscript = new default_1.DefaultVtxo.Script({
+                pubKey: base_1.hex.decode(config.pubkeyHex),
+                serverPubKey: base_1.hex.decode(config.serverPubKeyHex),
+                csvTimelock: {
+                    value: BigInt(config.exitTimelockValue),
+                    type: config.exitTimelockType,
+                },
+            });
+            await (0, taskRunner_1.runTasks)(taskQueue, processors, {
+                walletRepository,
+                contractRepository,
+                indexerProvider,
+                arkProvider,
+                extendVtxo: (vtxo, contract) => {
+                    if (contract) {
+                        return (0, utils_1.extendVtxoFromContract)(vtxo, contract);
+                    }
+                    return (0, utils_1.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(processors_1.CONTRACT_POLL_TASK_TYPE);
+            if (existing.length === 0) {
+                const task = {
+                    id: (0, utils_1.getRandomId)(),
+                    type: processors_1.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).
+ */
+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.
+ */
+async function unregisterExpoBackgroundTask(taskName) {
+    const BackgroundTask = requireBackgroundTask();
+    await BackgroundTask.unregisterTaskAsync(taskName);
+}

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unregisterExpoBackgroundTask = exports.registerExpoBackgroundTask = exports.defineExpoBackgroundTask = exports.ExpoWallet = void 0;
+var wallet_1 = require("./wallet");
+Object.defineProperty(exports, "ExpoWallet", { enumerable: true, get: function () { return wallet_1.ExpoWallet; } });
+var background_1 = require("./background");
+Object.defineProperty(exports, "defineExpoBackgroundTask", { enumerable: true, get: function () { return background_1.defineExpoBackgroundTask; } });
+Object.defineProperty(exports, "registerExpoBackgroundTask", { enumerable: true, get: function () { return background_1.registerExpoBackgroundTask; } });
+Object.defineProperty(exports, "unregisterExpoBackgroundTask", { enumerable: true, get: function () { return background_1.unregisterExpoBackgroundTask; } });