@arkade-os/sdk 0.4.27 → 0.4.28

package/dist/esm/utils/bip21.js

@@ -1,123 +0,0 @@
-export var BIP21Error;
-(function (BIP21Error) {
-    BIP21Error["INVALID_URI"] = "Invalid BIP21 URI";
-    BIP21Error["INVALID_ADDRESS"] = "Invalid address";
-})(BIP21Error || (BIP21Error = {}));
-export class BIP21 {
-    /**
-     * Create a BIP21 URI from the provided parameters.
-     *
-     * @param params - BIP21 parameters to encode
-     * @returns Encoded BIP21 URI
-     */
-    static create(params) {
-        const { address, ...options } = params;
-        // Build query string
-        const queryParams = {};
-        for (const [key, value] of Object.entries(options)) {
-            if (value === undefined)
-                continue;
-            if (key === "amount") {
-                if (!isFinite(value)) {
-                    console.warn("Invalid amount");
-                    continue;
-                }
-                if (value < 0) {
-                    continue;
-                }
-                queryParams[key] = value;
-            }
-            else if (key === "ark") {
-                // Validate Arkade address format
-                if (typeof value === "string" &&
-                    (value.startsWith("ark") || value.startsWith("tark"))) {
-                    queryParams[key] = value;
-                }
-                else {
-                    console.warn("Invalid ARK address format");
-                }
-            }
-            else if (key === "sp") {
-                // Validate Silent Payment address format (placeholder)
-                if (typeof value === "string" && value.startsWith("sp")) {
-                    queryParams[key] = value;
-                }
-                else {
-                    console.warn("Invalid Silent Payment address format");
-                }
-            }
-            else if (typeof value === "string" || typeof value === "number") {
-                queryParams[key] = value;
-            }
-        }
-        const query = Object.keys(queryParams).length > 0
-            ? "?" +
-                new URLSearchParams(Object.fromEntries(Object.entries(queryParams).map(([k, v]) => [
-                    k,
-                    String(v),
-                ]))).toString()
-            : "";
-        return `bitcoin:${address ? address.toLowerCase() : ""}${query}`;
-    }
-    /**
-     * Parse a BIP21 URI and return its decoded parameters.
-     *
-     * @param uri - BIP21 URI to parse
-     * @returns Parsed BIP21 URI data
-     * @throws Error if the URI does not start with the `bitcoin:` scheme
-     */
-    static parse(uri) {
-        if (!uri.toLowerCase().startsWith("bitcoin:")) {
-            throw new Error(BIP21Error.INVALID_URI);
-        }
-        // Remove the `bitcoin:` prefix while preserving the case of the rest.
-        const withoutPrefix = uri.slice(uri.toLowerCase().indexOf("bitcoin:") + 8);
-        const [address, query] = withoutPrefix.split("?");
-        const params = {};
-        if (address) {
-            params.address = address.toLowerCase();
-        }
-        if (query) {
-            const queryParams = new URLSearchParams(query);
-            for (const [key, value] of queryParams.entries()) {
-                if (!value)
-                    continue;
-                if (key === "amount") {
-                    const amount = Number(value);
-                    if (!isFinite(amount)) {
-                        continue;
-                    }
-                    if (amount < 0) {
-                        continue;
-                    }
-                    params[key] = amount;
-                }
-                else if (key === "ark") {
-                    // Validate Arkade address format
-                    if (value.startsWith("ark") || value.startsWith("tark")) {
-                        params[key] = value;
-                    }
-                    else {
-                        console.warn("Invalid ARK address format");
-                    }
-                }
-                else if (key === "sp") {
-                    // Validate Silent Payment address format (placeholder)
-                    if (value.startsWith("sp")) {
-                        params[key] = value;
-                    }
-                    else {
-                        console.warn("Invalid Silent Payment address format");
-                    }
-                }
-                else {
-                    params[key] = value;
-                }
-            }
-        }
-        return {
-            originalString: uri,
-            params,
-        };
-    }
-}

package/dist/esm/utils/syncCursors.js

@@ -1,119 +0,0 @@
-/** Lag behind real-time to avoid racing with indexer writes. */
-export const SAFETY_LAG_MS = 30000;
-/** Overlap window so boundary virtual outputs are never missed. */
-export const OVERLAP_MS = 24 * 60 * 60 * 1000;
-/**
- * Per-repository mutex that serializes wallet-state mutations so that
- * concurrent read-modify-write cycles never silently overwrite
- * each other's changes.
- */
-const walletStateLocks = new WeakMap();
-/**
- * Atomically read, mutate, and persist wallet state.
- * All callers that modify wallet state should go through this helper
- * to avoid lost-update races between interleaved async operations.
- */
-export async function updateWalletState(repo, updater) {
-    const prev = walletStateLocks.get(repo) ?? Promise.resolve();
-    const op = prev.then(async () => {
-        const state = (await repo.getWalletState()) ?? {};
-        await repo.saveWalletState(updater(state));
-    });
-    // Store a version that never rejects so the chain doesn't break.
-    walletStateLocks.set(repo, op.catch(() => { }));
-    return op;
-}
-/**
- * Settings key that gates interpretation of the `lastSyncTime` field.
- *
- * The `lastSyncTime` column existed pre-PR with a different semantic
- * (wall-clock at sync completion, written by the buggy sync loop this
- * PR fixes). On upgrade we cannot trust any pre-existing value, so the
- * cursor is only honoured after the first successful post-upgrade
- * advance writes this marker into the `settings` JSON blob. Reusing
- * `settings` avoids any schema migration.
- */
-const CURSOR_MIGRATED_KEY = "vtxoCursorMigrated";
-function hasMigrationMarker(state) {
-    return state?.settings?.[CURSOR_MIGRATED_KEY] === true;
-}
-/**
- * Read the global high-water mark for VTXO indexer syncs.
- *
- * Returns `0` when:
- *  - the wallet has never been synced (bootstrap case), or
- *  - the stored `lastSyncTime` was written by pre-PR code and is not
- *    safe to reuse under the new semantics (see {@link CURSOR_MIGRATED_KEY}).
- */
-export async function getSyncCursor(repo) {
-    const state = await repo.getWalletState();
-    if (!hasMigrationMarker(state))
-        return 0;
-    return state?.lastSyncTime ?? 0;
-}
-/**
- * Advance the global cursor after a successful full-scope delta sync.
- *
- * Clamped with `Math.max` against the current value so concurrent syncs
- * that finish out of order can't rewind the cursor: `lastUpdatedAt` is
- * captured before each sync enters the `updateWalletState` mutex, and
- * the later-started sync would otherwise overwrite the earlier-captured
- * one with a smaller value. The legacy value is discarded on the first
- * advance if the migration marker is absent so pre-PR data doesn't
- * survive the upgrade.
- */
-export async function advanceSyncCursor(repo, lastUpdatedAt) {
-    await updateWalletState(repo, (state) => {
-        const current = hasMigrationMarker(state)
-            ? (state.lastSyncTime ?? 0)
-            : 0;
-        return {
-            ...state,
-            lastSyncTime: Math.max(current, lastUpdatedAt),
-            settings: {
-                ...(state.settings ?? {}),
-                [CURSOR_MIGRATED_KEY]: true,
-            },
-        };
-    });
-}
-/**
- * Remove the sync cursor, forcing a full re-bootstrap on next sync.
- *
- * Also clears the migration marker so any stored `lastSyncTime` is
- * treated as untrusted on the next read.
- */
-export async function clearSyncCursor(repo) {
-    await updateWalletState(repo, (state) => {
-        const { [CURSOR_MIGRATED_KEY]: _, ...restSettings } = state.settings ?? {};
-        return {
-            ...state,
-            lastSyncTime: undefined,
-            settings: restSettings,
-        };
-    });
-}
-/**
- * Compute the `after` lower-bound for a delta sync query.
- *
- * No upper bound (`before`) is applied to the query so that freshly
- * created virtual outputs are never excluded. The safety lag is applied only
- * when advancing the cursor (see @see cursorCutoff).
- */
-export function computeSyncWindow(cursor) {
-    const after = Math.max(0, cursor - OVERLAP_MS);
-    return { after };
-}
-/**
- * The safe high-water mark for cursor advancement.
- * Lags behind real-time by @see SAFETY_LAG_MS so that virtual outputs still
- * being indexed are re-queried on the next sync.
- *
- * When `requestStartedAt` is provided the cutoff is frozen to the
- * request start rather than wall-clock at commit time, preventing
- * long-running paginated fetches from advancing the cursor past the
- * data they actually observed.
- */
-export function cursorCutoff(requestStartedAt) {
-    return (requestStartedAt ?? Date.now()) - SAFETY_LAG_MS;
-}

package/dist/esm/utils/timelock.js

@@ -1,22 +0,0 @@
-import * as bip68 from "bip68";
-/**
- * Convert RelativeTimelock to BIP68 sequence number.
- */
-export function timelockToSequence(timelock) {
-    return bip68.encode(timelock.type === "blocks"
-        ? { blocks: Number(timelock.value) }
-        : { seconds: Number(timelock.value) });
-}
-/**
- * Convert BIP68 sequence number back to RelativeTimelock.
- */
-export function sequenceToTimelock(sequence) {
-    const decoded = bip68.decode(sequence);
-    if ("blocks" in decoded && decoded.blocks !== undefined) {
-        return { type: "blocks", value: BigInt(decoded.blocks) };
-    }
-    if ("seconds" in decoded && decoded.seconds !== undefined) {
-        return { type: "seconds", value: BigInt(decoded.seconds) };
-    }
-    throw new Error(`Invalid BIP68 sequence: ${sequence}`);
-}

package/dist/esm/utils/transaction.js

@@ -1,24 +0,0 @@
-import { Transaction as BtcSignerTransaction } from "@scure/btc-signer";
-/**
- * Transaction is a wrapper around the @scure/btc-signer Transaction class.
- * It adds the Arkade protocol specific options to the transaction.
- */
-export class Transaction extends BtcSignerTransaction {
-    constructor(opts) {
-        super(withArkOpts(opts));
-    }
-    static fromPSBT(psbt_, opts) {
-        return BtcSignerTransaction.fromPSBT(psbt_, withArkOpts(opts));
-    }
-    static fromRaw(raw, opts) {
-        return BtcSignerTransaction.fromRaw(raw, withArkOpts(opts));
-    }
-}
-Transaction.ARK_TX_OPTS = {
-    allowUnknown: true,
-    allowUnknownOutputs: true,
-    allowUnknownInputs: true,
-};
-function withArkOpts(opts) {
-    return { ...Transaction.ARK_TX_OPTS, ...opts };
-}

package/dist/esm/utils/transactionHistory.js

@@ -1,180 +0,0 @@
-import { TxType } from "../wallet/index.js";
-const txKey = {
-    commitmentTxid: "",
-    boardingTxid: "",
-    arkTxid: "",
-};
-function collectAssets(vtxos) {
-    const map = new Map();
-    for (const vtxo of vtxos) {
-        if (vtxo.assets) {
-            for (const a of vtxo.assets) {
-                map.set(a.assetId, (map.get(a.assetId) ?? 0n) + a.amount);
-            }
-        }
-    }
-    if (map.size === 0)
-        return undefined;
-    return Array.from(map, ([assetId, amount]) => ({ assetId, amount }));
-}
-function subtractAssets(spent, change) {
-    const map = new Map();
-    for (const vtxo of change) {
-        if (vtxo.assets) {
-            for (const a of vtxo.assets) {
-                map.set(a.assetId, (map.get(a.assetId) ?? 0n) + a.amount);
-            }
-        }
-    }
-    for (const vtxo of spent) {
-        if (vtxo.assets) {
-            for (const a of vtxo.assets) {
-                const current = map.get(a.assetId) ?? 0n;
-                const remaining = current - a.amount;
-                if (remaining !== 0n) {
-                    map.set(a.assetId, remaining);
-                }
-                else {
-                    map.delete(a.assetId);
-                }
-            }
-        }
-    }
-    if (map.size === 0)
-        return undefined;
-    return Array.from(map, ([assetId, amount]) => ({ assetId, amount }));
-}
-/**
- * Builds the transaction history by analyzing virtual outputs, boarding transactions, and ignored commitments.
- * History is sorted from newest to oldest and is composed only of SENT and RECEIVED transactions.
- *
- * @param {VirtualCoin[]} vtxos - An array of virtual outputs representing the user's transactions and balances.
- * @param {ArkTransaction[]} allBoardingTxs - An array of boarding transactions to include in the history.
- * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
- * @return {ExtendedArkTransaction[]} A sorted array of extended Arkade transactions, representing the transaction history.
- */
-export async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
-    const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
-    const sent = [];
-    let received = [];
-    for (const vtxo of fromOldestVtxo) {
-        if (vtxo.status.isLeaf) {
-            // If this virtual output is a leaf and it's not the settlement of a boarding or there's no virtual output refreshed by it,
-            // it's translated into a received batch transaction
-            if (!commitmentsToIgnore.has(vtxo.virtualStatus.commitmentTxIds[0]) &&
-                fromOldestVtxo.filter((v) => v.settledBy === vtxo.virtualStatus.commitmentTxIds[0]).length === 0) {
-                const assets = collectAssets([vtxo]);
-                received.push({
-                    key: {
-                        ...txKey,
-                        commitmentTxid: vtxo.virtualStatus.commitmentTxIds[0],
-                    },
-                    tag: "batch",
-                    type: TxType.TxReceived,
-                    amount: vtxo.value,
-                    settled: vtxo.status.isLeaf || vtxo.isSpent,
-                    createdAt: vtxo.createdAt.getTime(),
-                    ...(assets && { assets }),
-                });
-            }
-        }
-        else if (fromOldestVtxo.filter((v) => v.arkTxId === vtxo.txid).length === 0) {
-            // If this virtual output is preconfirmed and does not spend any other virtual outputs,
-            // it's translated into a received offchain transaction
-            const assets = collectAssets([vtxo]);
-            received.push({
-                key: { ...txKey, arkTxid: vtxo.txid },
-                tag: "offchain",
-                type: TxType.TxReceived,
-                amount: vtxo.value,
-                settled: vtxo.status.isLeaf || vtxo.isSpent,
-                createdAt: vtxo.createdAt.getTime(),
-                ...(assets && { assets }),
-            });
-        }
-        // If the virtual output is spent, it's translated into a sent transaction unless:
-        // - it's been refreshed (we don't want to add any record in this case)
-        // - a sent transaction has been already added to avoid duplicates (can happen if many virtual outputs have been spent in the same tx or forfeited in the same batch)
-        if (vtxo.isSpent) {
-            // If the virtual output is spent offchain, it's translated into an offchain sent tx
-            if (vtxo.arkTxId &&
-                !sent.some((s) => s.key.arkTxid === vtxo.arkTxId)) {
-                const changes = fromOldestVtxo.filter((_) => _.txid === vtxo.arkTxId);
-                // We want to find all the other virtual outputs spent by the same transaction to
-                // calculate the full amount of the change.
-                const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
-                const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
-                let txAmount = 0;
-                let txTime = 0;
-                if (changes.length > 0) {
-                    const changeAmount = changes.reduce((acc, v) => acc + v.value, 0);
-                    txAmount = spentAmount - changeAmount;
-                    txTime = changes[0].createdAt.getTime();
-                }
-                else {
-                    txAmount = spentAmount;
-                    // TODO: fetch the virtual output with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
-                    txTime = getTxCreatedAt
-                        ? ((await getTxCreatedAt(vtxo.arkTxId)) ??
-                            vtxo.createdAt.getTime() + 1)
-                        : vtxo.createdAt.getTime() + 1;
-                }
-                const assets = subtractAssets(allSpent, changes);
-                sent.push({
-                    key: { ...txKey, arkTxid: vtxo.arkTxId },
-                    tag: "offchain",
-                    type: TxType.TxSent,
-                    amount: txAmount,
-                    settled: true,
-                    createdAt: txTime,
-                    ...(assets && { assets }),
-                });
-            }
-            // If the virtual output is forfeited in a batch and the total sum of forfeited virtual outputs is bigger than the sum of new virtual outputs,
-            // it's translated into an exit sent tx
-            if (vtxo.settledBy &&
-                !commitmentsToIgnore.has(vtxo.settledBy) &&
-                !sent.some((s) => s.key.commitmentTxid === vtxo.settledBy)) {
-                const changes = fromOldestVtxo.filter((v) => v.status.isLeaf &&
-                    v.virtualStatus.commitmentTxIds?.every((_) => vtxo.settledBy === _));
-                const forfeitVtxos = fromOldestVtxo.filter((v) => v.settledBy === vtxo.settledBy);
-                const forfeitAmount = forfeitVtxos.reduce((acc, v) => acc + v.value, 0);
-                if (changes.length > 0) {
-                    const settledAmount = changes.reduce((acc, v) => acc + v.value, 0);
-                    // forfeitAmount > settledAmount --> collaborative exit with offchain change
-                    // TODO: make this support fees!
-                    if (forfeitAmount > settledAmount) {
-                        const assets = subtractAssets(forfeitVtxos, changes);
-                        sent.push({
-                            key: { ...txKey, commitmentTxid: vtxo.settledBy },
-                            tag: "exit",
-                            type: TxType.TxSent,
-                            amount: forfeitAmount - settledAmount,
-                            settled: true,
-                            createdAt: changes[0].createdAt.getTime(),
-                            ...(assets && { assets }),
-                        });
-                    }
-                }
-                else {
-                    // forfeitAmount > 0 && settledAmount == 0 --> collaborative exit without any offchain change
-                    const assets = subtractAssets(forfeitVtxos, []);
-                    sent.push({
-                        key: { ...txKey, commitmentTxid: vtxo.settledBy },
-                        tag: "exit",
-                        type: TxType.TxSent,
-                        amount: forfeitAmount,
-                        settled: true,
-                        // TODO: fetch commitment tx with /v1/indexer/commitmentTx/<commitmentTxid> to know when the tx was made
-                        createdAt: vtxo.createdAt.getTime() + 1,
-                        ...(assets && { assets }),
-                    });
-                }
-            }
-        }
-    }
-    // Boardings are always inbound amounts, and we only hide the ones to ignore.
-    const boardingTx = allBoardingTxs.map((tx) => ({ ...tx, tag: "boarding" }));
-    const sorted = [...boardingTx, ...sent, ...received].sort((a, b) => b.createdAt - a.createdAt);
-    return sorted;
-}

package/dist/esm/utils/txSizeEstimator.js

@@ -1,128 +0,0 @@
-import { Address, OutScript } from "@scure/btc-signer";
-/**
- * Calculates the byte size required to store a variable-length integer (VarInt).
- * Bitcoin uses VarInts to compact integer data (like array lengths).
- *
- * @param n - The integer value to check
- * @returns The size in bytes (1, 3, 5, or 9)
- */
-const getVarIntSize = (n) => {
-    if (n < 0xfd)
-        return 1;
-    if (n <= 0xffff)
-        return 3;
-    if (n <= 0xffffffff)
-        return 5;
-    return 9;
-};
-export class TxWeightEstimator {
-    constructor(hasWitness, inputCount, outputCount, inputSize, inputWitnessSize, outputSize) {
-        this.hasWitness = hasWitness;
-        this.inputCount = inputCount;
-        this.outputCount = outputCount;
-        this.inputSize = inputSize;
-        this.inputWitnessSize = inputWitnessSize;
-        this.outputSize = outputSize;
-    }
-    static create() {
-        return new TxWeightEstimator(false, 0, 0, 0, 0, 0);
-    }
-    addP2AInput() {
-        this.inputCount++;
-        this.inputSize += TxWeightEstimator.INPUT_SIZE;
-        return this;
-    }
-    addKeySpendInput(isDefault = true) {
-        this.inputCount++;
-        this.inputWitnessSize += 64 + 1 + (isDefault ? 0 : 1);
-        this.inputSize += TxWeightEstimator.INPUT_SIZE;
-        this.hasWitness = true;
-        return this;
-    }
-    addP2PKHInput() {
-        this.inputCount++;
-        this.inputWitnessSize++;
-        this.inputSize +=
-            TxWeightEstimator.INPUT_SIZE +
-                TxWeightEstimator.P2PKH_SCRIPT_SIG_SIZE;
-        return this;
-    }
-    addTapscriptInput(leafWitnessSize, leafScriptSize, leafControlBlockSize) {
-        const controlBlockWitnessSize = 1 +
-            TxWeightEstimator.BASE_CONTROL_BLOCK_SIZE +
-            1 +
-            leafScriptSize +
-            1 +
-            leafControlBlockSize;
-        this.inputCount++;
-        this.inputWitnessSize += leafWitnessSize + 1 + controlBlockWitnessSize;
-        this.inputSize += TxWeightEstimator.INPUT_SIZE;
-        this.hasWitness = true;
-        return this;
-    }
-    addP2WPKHOutput() {
-        this.outputCount++;
-        this.outputSize +=
-            TxWeightEstimator.OUTPUT_SIZE +
-                TxWeightEstimator.P2WPKH_OUTPUT_SIZE;
-        return this;
-    }
-    addP2TROutput() {
-        this.outputCount++;
-        this.outputSize +=
-            TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2TR_OUTPUT_SIZE;
-        return this;
-    }
-    /**
-     * Adds an output given a raw script.
-     * Cost = 8 bytes (amount) + varint(scriptLen) + scriptLen
-     */
-    addOutputScript(script) {
-        this.outputCount++;
-        this.outputSize += 8 + getVarIntSize(script.length) + script.length;
-        return this;
-    }
-    /**
-     * Adds an output by decoding the address to get the exact script size.
-     */
-    addOutputAddress(address, network) {
-        const payment = Address(network).decode(address);
-        const script = OutScript.encode(payment);
-        return this.addOutputScript(script);
-    }
-    vsize() {
-        const inputCount = getVarIntSize(this.inputCount);
-        const outputCount = getVarIntSize(this.outputCount);
-        // Calculate the size of the transaction without witness data
-        const txSizeStripped = TxWeightEstimator.BASE_TX_SIZE +
-            inputCount +
-            this.inputSize +
-            outputCount +
-            this.outputSize;
-        // Calculate the total weight
-        let weight = txSizeStripped * TxWeightEstimator.WITNESS_SCALE_FACTOR;
-        // Add witness data if present
-        if (this.hasWitness) {
-            weight +=
-                TxWeightEstimator.WITNESS_HEADER_SIZE + this.inputWitnessSize;
-        }
-        // Convert weight to vsize (weight / 4, rounded up)
-        return vsize(weight);
-    }
-}
-TxWeightEstimator.P2PKH_SCRIPT_SIG_SIZE = 1 + 73 + 1 + 33;
-TxWeightEstimator.INPUT_SIZE = 32 + 4 + 1 + 4;
-TxWeightEstimator.BASE_CONTROL_BLOCK_SIZE = 1 + 32;
-TxWeightEstimator.OUTPUT_SIZE = 8 + 1;
-TxWeightEstimator.P2WPKH_OUTPUT_SIZE = 1 + 1 + 20;
-TxWeightEstimator.BASE_TX_SIZE = 8 + 2; // Version + LockTime
-TxWeightEstimator.WITNESS_HEADER_SIZE = 2; // Flag + Marker
-TxWeightEstimator.WITNESS_SCALE_FACTOR = 4;
-TxWeightEstimator.P2TR_OUTPUT_SIZE = 1 + 1 + 32;
-const vsize = (weight) => {
-    const value = BigInt(Math.ceil(weight / TxWeightEstimator.WITNESS_SCALE_FACTOR));
-    return {
-        value,
-        fee: (feeRate) => feeRate * value,
-    };
-};