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

package/dist/esm/utils/txSizeEstimator.js

@@ -1,3 +1,20 @@
+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;
@@ -38,16 +55,16 @@ export class TxWeightEstimator {
             1 +
             leafControlBlockSize;
         this.inputCount++;
-        this.inputWitnessSize += leafWitnessSize + controlBlockWitnessSize;
+        this.inputWitnessSize += leafWitnessSize + 1 + controlBlockWitnessSize;
         this.inputSize += TxWeightEstimator.INPUT_SIZE;
         this.hasWitness = true;
-        this.inputCount++;
         return this;
     }
-    addP2WKHOutput() {
+    addP2WPKHOutput() {
         this.outputCount++;
         this.outputSize +=
-            TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2WKH_OUTPUT_SIZE;
+            TxWeightEstimator.OUTPUT_SIZE +
+                TxWeightEstimator.P2WPKH_OUTPUT_SIZE;
         return this;
     }
     addP2TROutput() {
@@ -56,16 +73,24 @@ export class TxWeightEstimator {
             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 getVarIntSize = (n) => {
-            if (n < 0xfd)
-                return 1;
-            if (n < 0xffff)
-                return 3;
-            if (n < 0xffffffff)
-                return 5;
-            return 9;
-        };
         const inputCount = getVarIntSize(this.inputCount);
         const outputCount = getVarIntSize(this.outputCount);
         // Calculate the size of the transaction without witness data
@@ -89,7 +114,7 @@ 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.P2WKH_OUTPUT_SIZE = 1 + 1 + 20;
+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;

package/dist/esm/wallet/asset-manager.js

@@ -0,0 +1,333 @@
+import { AssetGroup, AssetId, AssetInput, AssetOutput, AssetRef, Metadata, Packet, } from '../asset/index.js';
+import { ArkAddress } from '../script/address.js';
+import { selectedCoinsToAssetInputs, selectCoinsWithAsset } from './asset.js';
+import { selectVirtualCoins } from './wallet.js';
+export class ReadonlyAssetManager {
+    constructor(indexer) {
+        this.indexer = indexer;
+    }
+    async getAssetDetails(assetId) {
+        // TODO: rely on db, and fallback to indexer if not found
+        return this.indexer.getAssetDetails(assetId);
+    }
+}
+export class AssetManager extends ReadonlyAssetManager {
+    constructor(wallet) {
+        super(wallet.indexerProvider);
+        this.wallet = wallet;
+    }
+    /**
+     * Issue a new asset.
+     * @param params - Parameters for asset issuance
+     * @param params.amount - Amount of asset units to issue
+     * @param params.controlAsset - Optional control asset (for reissuable assets)
+     * @param params.metadata - Optional metadata to attach to the asset
+     * @returns Promise resolving to the ark transaction ID and asset ID
+     *
+     * @example
+     * ```typescript
+     * // Issue a simple non-reissuable asset
+     * const result = await wallet.issueAsset({ amount: 1000 });
+     * console.log('Asset ID:', result.assetId);
+     *
+     * // Issue a reissuable asset with a new control asset
+     * const result = await wallet.issueAsset({
+     *   amount: 1000,
+     *   controlAsset: 1 // creates new control asset with amount 1
+     * });
+     * console.log('Control Asset ID:', result.controlAssetId);
+     * console.log('Asset ID:', result.assetId);
+     *
+     * // Issue a reissuable asset with an existing control asset
+     * const result = await wallet.issueAsset({
+     *   amount: 1000,
+     *   controlAsset: 'controlAssetId'
+     * });
+     * console.log('Control Asset ID:', result.controlAssetId);
+     * console.log('Asset ID:', result.assetId);
+     * ```
+     */
+    async issue(params) {
+        if (params.amount <= 0) {
+            throw new Error(`Issue amount must be greater than 0, got ${params.amount}`);
+        }
+        const metadata = castMetadata(params.metadata);
+        const virtualCoins = await this.wallet.getVtxos({
+            withRecoverable: false,
+        });
+        const controlAssetRef = params.controlAssetId
+            ? AssetRef.fromId(AssetId.fromString(params.controlAssetId))
+            : null;
+        const coinSelection = selectVirtualCoins(virtualCoins, Number(this.wallet.dustAmount));
+        let totalBtcSelected = 0n;
+        // keep track of asset changes
+        const assetChanges = new Map();
+        for (const coin of coinSelection.inputs) {
+            totalBtcSelected += BigInt(coin.value);
+            if (!coin.assets)
+                continue;
+            for (const { assetId, amount } of coin.assets) {
+                const existing = assetChanges.get(assetId) ?? 0n;
+                assetChanges.set(assetId, existing + BigInt(amount));
+            }
+        }
+        const groups = [];
+        // issued asset group
+        const issuedAssetOutput = AssetOutput.create(0, BigInt(params.amount));
+        const issuedAssetGroup = AssetGroup.create(null, controlAssetRef, [], [issuedAssetOutput], metadata);
+        groups.push(issuedAssetGroup);
+        // add asset groups for each asset change
+        if (assetChanges.size > 0) {
+            const assetInputs = selectedCoinsToAssetInputs(coinSelection.inputs);
+            for (const [assetId, amount] of assetChanges) {
+                const changeInputs = [];
+                // collect all inputs for the asset change
+                for (const [inputIndex, assets] of assetInputs) {
+                    for (const asset of assets) {
+                        if (asset.assetId !== assetId)
+                            continue;
+                        changeInputs.push(AssetInput.create(inputIndex, BigInt(asset.amount)));
+                    }
+                }
+                // add the change asset group
+                groups.push(AssetGroup.create(AssetId.fromString(assetId), null, changeInputs, [AssetOutput.create(0, amount)], []));
+            }
+        }
+        // build transaction outputs
+        const address = await this.wallet.getAddress();
+        const outputAddress = ArkAddress.decode(address);
+        const outputs = [
+            {
+                script: outputAddress.pkScript,
+                amount: BigInt(totalBtcSelected),
+            },
+            Packet.create(groups).txOut(),
+        ];
+        const { arkTxid } = await this.wallet.buildAndSubmitOffchainTx(coinSelection.inputs, outputs);
+        return {
+            arkTxId: arkTxid,
+            assetId: AssetId.create(arkTxid, 0).toString(),
+        };
+    }
+    /**
+     * Reissue more units of an existing asset.
+     * Requires ownership of the control asset.
+     *
+     * @param params - Parameters for asset reissuance
+     * @param params.assetId - The asset ID to reissue (control asset ID is resolved via getAssetDetails)
+     * @param params.amount - Amount of additional units to issue
+     * @returns Promise resolving to the ark transaction ID
+     *
+     * @example
+     * ```typescript
+     * const txid = await wallet.assetManager.reissue({
+     *   assetId: 'def456...',
+     *   amount: 500
+     * });
+     * ```
+     */
+    async reissue(params) {
+        if (params.amount <= 0) {
+            throw new Error(`Reissuance amount must be greater than 0, got ${params.amount}`);
+        }
+        const { controlAssetId } = await this.getAssetDetails(params.assetId);
+        if (!controlAssetId) {
+            throw new Error(`Asset ${params.assetId} is not reissuable`);
+        }
+        const virtualCoins = await this.wallet.getVtxos({
+            withRecoverable: false,
+        });
+        const assetChanges = new Map();
+        // select control asset inputs
+        const { selected: controlCoins } = selectCoinsWithAsset(virtualCoins, controlAssetId, 1n);
+        let selectedCoins = [...controlCoins];
+        let assetToReissueAmount = 0n;
+        // all control inputs assets go to asset changes, including the control asset itself
+        for (const coin of controlCoins) {
+            if (!coin.assets)
+                continue;
+            for (const { assetId, amount } of coin.assets) {
+                if (assetId === params.assetId) {
+                    assetToReissueAmount += BigInt(amount);
+                    continue;
+                }
+                const existing = assetChanges.get(assetId) ?? 0n;
+                assetChanges.set(assetId, existing + BigInt(amount));
+            }
+        }
+        // select at least dust amount
+        const minBtcNeeded = Number(this.wallet.dustAmount);
+        let totalBtcSelected = selectedCoins.reduce((sum, c) => sum + c.value, 0);
+        if (totalBtcSelected < minBtcNeeded) {
+            const remainingCoins = virtualCoins.filter((c) => !selectedCoins.find((sc) => sc.txid === c.txid && sc.vout === c.vout));
+            const additional = selectVirtualCoins(remainingCoins, minBtcNeeded - totalBtcSelected);
+            for (const coin of additional.inputs) {
+                // additional inputs assets go to asset changes
+                if (!coin.assets)
+                    continue;
+                for (const { assetId, amount } of coin.assets) {
+                    if (assetId === params.assetId) {
+                        assetToReissueAmount += BigInt(amount);
+                        continue;
+                    }
+                    const existing = assetChanges.get(assetId) ?? 0n;
+                    assetChanges.set(assetId, existing + BigInt(amount));
+                }
+            }
+            selectedCoins = [...selectedCoins, ...additional.inputs];
+            totalBtcSelected += additional.inputs.reduce((sum, c) => sum + c.value, 0);
+        }
+        const assetInputs = selectedCoinsToAssetInputs(selectedCoins);
+        // collect all inputs for the asset to reissue
+        const reissueInputs = [];
+        for (const [inputIndex, assets] of assetInputs) {
+            for (const asset of assets) {
+                if (asset.assetId !== params.assetId)
+                    continue;
+                reissueInputs.push(AssetInput.create(inputIndex, BigInt(asset.amount)));
+            }
+        }
+        // the total output amount of the asset to reissue = new + (optional) selected amount
+        const totalAssetAmount = assetToReissueAmount + BigInt(params.amount);
+        const reissueAssetIdObj = AssetId.fromString(params.assetId);
+        // create the reissuance asset group
+        const reissueAssetGroup = AssetGroup.create(reissueAssetIdObj, null, reissueInputs, [AssetOutput.create(0, totalAssetAmount)], []);
+        const groups = [reissueAssetGroup];
+        // for each asset change, create a new asset group
+        for (const [assetId, amount] of assetChanges) {
+            const changeInputs = [];
+            for (const [inputIndex, assets] of assetInputs) {
+                for (const asset of assets) {
+                    if (asset.assetId !== assetId)
+                        continue;
+                    changeInputs.push(AssetInput.create(inputIndex, BigInt(asset.amount)));
+                }
+            }
+            groups.push(AssetGroup.create(AssetId.fromString(assetId), null, changeInputs, [AssetOutput.create(0, amount)], []));
+        }
+        // build transaction outputs
+        const address = await this.wallet.getAddress();
+        const outputAddress = ArkAddress.decode(address);
+        const outputs = [
+            {
+                script: outputAddress.pkScript,
+                amount: BigInt(totalBtcSelected),
+            },
+            Packet.create(groups).txOut(),
+        ];
+        const { arkTxid } = await this.wallet.buildAndSubmitOffchainTx(selectedCoins, outputs);
+        return arkTxid;
+    }
+    /**
+     * Burn assets.
+     * @param params - Parameters for burning
+     * @param params.assetId - The asset ID to burn
+     * @param params.amount - Amount of units to burn
+     * @returns Promise resolving to the ark transaction ID
+     *
+     * @example
+     * ```typescript
+     * const txid = await wallet.assetManager.burn({
+     *   assetId: 'abc123...',
+     *   amount: 100
+     * });
+     * ```
+     */
+    async burn(params) {
+        if (params.amount <= 0) {
+            throw new Error(`Burn amount must be greater than 0, got ${params.amount}`);
+        }
+        const virtualCoins = await this.wallet.getVtxos({
+            withRecoverable: false,
+        });
+        const assetChanges = new Map();
+        // select vtxos with the asset to burn
+        const { selected: assetCoins } = selectCoinsWithAsset(virtualCoins, params.assetId, BigInt(params.amount));
+        const selectedCoins = [...assetCoins];
+        let totalBtcSelected = 0;
+        // add the selected coins to asset changes, including the asset to burn
+        for (const coin of assetCoins) {
+            totalBtcSelected += coin.value;
+            if (!coin.assets)
+                continue;
+            for (const { assetId, amount } of coin.assets) {
+                const existing = assetChanges.get(assetId) ?? 0n;
+                assetChanges.set(assetId, existing + BigInt(amount));
+            }
+        }
+        // subtract the amount to burn from the asset change
+        assetChanges.set(params.assetId, (assetChanges.get(params.assetId) ?? 0n) - BigInt(params.amount));
+        const minBtcNeeded = Number(this.wallet.dustAmount);
+        // we need to ensure at least dust amount is selected
+        // if not, select additional coins
+        if (totalBtcSelected < minBtcNeeded) {
+            const remainingCoins = virtualCoins.filter((c) => !selectedCoins.find((sc) => sc.txid === c.txid && sc.vout === c.vout));
+            const additional = selectVirtualCoins(remainingCoins, minBtcNeeded - totalBtcSelected);
+            // additional inputs assets go to asset changes
+            for (const coin of additional.inputs) {
+                totalBtcSelected += coin.value;
+                if (!coin.assets)
+                    continue;
+                for (const { assetId, amount } of coin.assets) {
+                    const existing = assetChanges.get(assetId) ?? 0n;
+                    assetChanges.set(assetId, existing + BigInt(amount));
+                }
+            }
+            selectedCoins.push(...additional.inputs);
+        }
+        const groups = [];
+        const assetInputs = selectedCoinsToAssetInputs(selectedCoins);
+        // for each asset, create a new asset group
+        for (const [assetId, amount] of assetChanges) {
+            const changeInputs = [];
+            for (const [inputIndex, assets] of assetInputs) {
+                for (const asset of assets) {
+                    if (asset.assetId !== assetId)
+                        continue;
+                    changeInputs.push(AssetInput.create(inputIndex, BigInt(asset.amount)));
+                }
+            }
+            groups.push(AssetGroup.create(AssetId.fromString(assetId), null, changeInputs, amount > 0n ? [AssetOutput.create(0, amount)] : [], []));
+        }
+        // build transaction outputs
+        const address = await this.wallet.getAddress();
+        const outputAddress = ArkAddress.decode(address);
+        const outputs = [
+            {
+                script: outputAddress.pkScript,
+                amount: BigInt(totalBtcSelected),
+            },
+            Packet.create(groups).txOut(),
+        ];
+        const { arkTxid } = await this.wallet.buildAndSubmitOffchainTx(selectedCoins, outputs);
+        return arkTxid;
+    }
+}
+function castMetadata(metadata) {
+    if (!metadata) {
+        return [];
+    }
+    const md = [];
+    const textEncoder = new TextEncoder();
+    for (const [key, value] of Object.entries(metadata)) {
+        // convert value to bytes
+        let valueBytes;
+        if (typeof value === "string") {
+            valueBytes = textEncoder.encode(value);
+        }
+        else if (typeof value === "number") {
+            valueBytes = textEncoder.encode(String(value));
+        }
+        else if (value instanceof Uint8Array) {
+            valueBytes = value;
+        }
+        else if (value instanceof ArrayBuffer) {
+            valueBytes = new Uint8Array(value);
+        }
+        else {
+            throw new Error("Invalid metadata value type");
+        }
+        md.push(Metadata.create(textEncoder.encode(key), valueBytes));
+    }
+    return md;
+}

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