@arkade-os/sdk 0.3.0-alpha.8 → 0.3.0

package/README.md

@@ -108,26 +108,60 @@ const settleTxid = await wallet.settle({
 })
 ```
 
+### VTXO Management (Renewal & Recovery)
+
+VTXOs have an expiration time (batch expiry). The SDK provides the `VtxoManager` class to handle both:
+
+- **Renewal**: Renew VTXOs before they expire to maintain unilateral control of the funds.
+- **Recovery**: Reclaim swept or expired VTXOs back to the wallet in case renewal window was missed.
+
+```typescript
+import { VtxoManager } from '@arkade-os/sdk'
+
+// Create manager with optional renewal configuration
+const manager = new VtxoManager(wallet, {
+  enabled: true,           // Enable expiration monitoring
+  thresholdPercentage: 10  // Alert when 10% of lifetime remains (default)
+})
+```
+
+#### Renewal: Prevent Expiration
+
+Renew VTXOs before they expire to retain unilateral control of funds.
+This settles expiring and recoverable VTXOs back to your wallet, refreshing their expiration time.
+
+```typescript
+// Renew all VTXOs to prevent expiration
+const txid = await manager.renewVtxos()
+console.log('Renewed:', txid)
+
+// Check which VTXOs are expiring soon
+const expiringVtxos = await manager.getExpiringVtxos()
+// Override threshold percentage (e.g., renew when 5% of time remains)
+const urgentlyExpiring = await manager.getExpiringVtxos(5)
+```
+
+
+#### Recovery: Reclaim Swept VTXOs
+
+Recover VTXOs that have been swept by the server or consolidate small amounts (subdust).
+
+```typescript
+// Recover swept VTXOs and preconfirmed subdust
+const txid = await manager.recoverVtxos((event) => {
+  console.log('Settlement event:', event.type)
+})
+console.log('Recovered:', txid)
+// Check what's recoverable
+const balance = await manager.getRecoverableBalance()
+```
+
 
 ### Transaction History
 
 ```typescript
 // Get transaction history
 const history = await wallet.getTransactionHistory()
-console.log('History:', history)
-
-// Example history entry:
-{
-  key: {
-    boardingTxid: '...', // for boarding transactions
-    commitmentTxid: '...', // for commitment transactions
-    redeemTxid: '...'    // for regular transactions
-  },
-  type: TxType.TxReceived, // or TxType.TxSent
-  amount: 50000,
-  settled: true,
-  createdAt: 1234567890
-}
 ```
 
 ### Offboarding

package/dist/cjs/arknote/index.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArkNote = void 0;
 const base_1 = require("@scure/base");
-const base_2 = require("../script/base");
 const utils_js_1 = require("@scure/btc-signer/utils.js");
-const script_js_1 = require("@scure/btc-signer/script.js");
+const btc_signer_1 = require("@scure/btc-signer");
+const base_2 = require("../script/base");
 /**
  * ArkNotes are special virtual coins in the Ark protocol that can be created
  * and spent without requiring any transactions. The server mints them, and they
@@ -85,5 +85,5 @@ function readUInt32BE(array, offset) {
     return view.getUint32(0, false);
 }
 function noteTapscript(preimageHash) {
-    return script_js_1.Script.encode(["SHA256", preimageHash, "EQUAL"]);
+    return btc_signer_1.Script.encode(["SHA256", preimageHash, "EQUAL"]);
 }

package/dist/cjs/forfeit.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildForfeitTx = buildForfeitTx;
-const transaction_js_1 = require("@scure/btc-signer/transaction.js");
+const transaction_1 = require("./utils/transaction");
 const anchor_1 = require("./utils/anchor");
 function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
-    const tx = new transaction_js_1.Transaction({
+    const tx = new transaction_1.Transaction({
         version: 3,
         lockTime: txLocktime,
     });

package/dist/cjs/identity/singleKey.js

@@ -2,12 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SingleKey = void 0;
 const utils_js_1 = require("@scure/btc-signer/utils.js");
+const btc_signer_1 = require("@scure/btc-signer");
 const base_1 = require("@scure/base");
-const transaction_js_1 = require("@scure/btc-signer/transaction.js");
 const signingSession_1 = require("../tree/signingSession");
 const secp256k1_1 = require("@noble/secp256k1");
-const ZERO_32 = new Uint8Array(32).fill(0);
-const ALL_SIGHASH = Object.values(transaction_js_1.SigHash).filter((x) => typeof x === "number");
+const ALL_SIGHASH = Object.values(btc_signer_1.SigHash).filter((x) => typeof x === "number");
 /**
  * In-memory single key implementation for Bitcoin transaction signing.
  *
@@ -51,7 +50,7 @@ class SingleKey {
         const txCpy = tx.clone();
         if (!inputIndexes) {
             try {
-                if (!txCpy.sign(this.key, ALL_SIGHASH, ZERO_32)) {
+                if (!txCpy.sign(this.key, ALL_SIGHASH)) {
                     throw new Error("Failed to sign transaction");
                 }
             }
@@ -67,7 +66,7 @@ class SingleKey {
             return txCpy;
         }
         for (const inputIndex of inputIndexes) {
-            if (!txCpy.signIdx(this.key, inputIndex, ALL_SIGHASH, ZERO_32)) {
+            if (!txCpy.signIdx(this.key, inputIndex, ALL_SIGHASH)) {
                 throw new Error(`Failed to sign input #${inputIndex}`);
             }
         }
@@ -82,9 +81,10 @@ class SingleKey {
     signerSession() {
         return signingSession_1.TreeSignerSession.random();
     }
-    async signMessage(message) {
-        const msgBytes = new TextEncoder().encode(message);
-        return secp256k1_1.schnorr.sign((0, utils_js_1.sha256)(msgBytes), this.key);
+    async signMessage(message, signatureType = "schnorr") {
+        if (signatureType === "ecdsa")
+            return (0, secp256k1_1.sign)(message, this.key, { prehash: false });
+        return secp256k1_1.schnorr.sign(message, this.key);
     }
 }
 exports.SingleKey = SingleKey;

package/dist/cjs/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.BIP322 = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.networks = exports.ArkNote = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
-const transaction_js_1 = require("@scure/btc-signer/transaction.js");
-Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return transaction_js_1.Transaction; } });
+exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.Intent = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.networks = exports.ArkNote = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.verifyTapscriptSignatures = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.TapTreeCoder = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.VtxoManager = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
+exports.maybeArkError = exports.ArkError = void 0;
+const transaction_1 = require("./utils/transaction");
+Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return transaction_1.Transaction; } });
 const singleKey_1 = require("./identity/singleKey");
 Object.defineProperty(exports, "SingleKey", { enumerable: true, get: function () { return singleKey_1.SingleKey; } });
 const address_1 = require("./script/address");
@@ -13,6 +14,7 @@ const default_1 = require("./script/default");
 Object.defineProperty(exports, "DefaultVtxo", { enumerable: true, get: function () { return default_1.DefaultVtxo; } });
 const base_1 = require("./script/base");
 Object.defineProperty(exports, "VtxoScript", { enumerable: true, get: function () { return base_1.VtxoScript; } });
+Object.defineProperty(exports, "TapTreeCoder", { enumerable: true, get: function () { return base_1.TapTreeCoder; } });
 const wallet_1 = require("./wallet");
 Object.defineProperty(exports, "TxType", { enumerable: true, get: function () { return wallet_1.TxType; } });
 const wallet_2 = require("./wallet/wallet");
@@ -22,6 +24,8 @@ const txTree_1 = require("./tree/txTree");
 Object.defineProperty(exports, "TxTree", { enumerable: true, get: function () { return txTree_1.TxTree; } });
 const ramps_1 = require("./wallet/ramps");
 Object.defineProperty(exports, "Ramps", { enumerable: true, get: function () { return ramps_1.Ramps; } });
+const vtxo_manager_1 = require("./wallet/vtxo-manager");
+Object.defineProperty(exports, "VtxoManager", { enumerable: true, get: function () { return vtxo_manager_1.VtxoManager; } });
 const wallet_3 = require("./wallet/serviceWorker/wallet");
 Object.defineProperty(exports, "ServiceWorkerWallet", { enumerable: true, get: function () { return wallet_3.ServiceWorkerWallet; } });
 const onchain_1 = require("./wallet/onchain");
@@ -50,6 +54,7 @@ Object.defineProperty(exports, "MultisigTapscript", { enumerable: true, get: fun
 const arkTransaction_1 = require("./utils/arkTransaction");
 Object.defineProperty(exports, "hasBoardingTxExpired", { enumerable: true, get: function () { return arkTransaction_1.hasBoardingTxExpired; } });
 Object.defineProperty(exports, "buildOffchainTx", { enumerable: true, get: function () { return arkTransaction_1.buildOffchainTx; } });
+Object.defineProperty(exports, "verifyTapscriptSignatures", { enumerable: true, get: function () { return arkTransaction_1.verifyTapscriptSignatures; } });
 const unknownFields_1 = require("./utils/unknownFields");
 Object.defineProperty(exports, "VtxoTaprootTree", { enumerable: true, get: function () { return unknownFields_1.VtxoTaprootTree; } });
 Object.defineProperty(exports, "ConditionWitness", { enumerable: true, get: function () { return unknownFields_1.ConditionWitness; } });
@@ -59,8 +64,8 @@ Object.defineProperty(exports, "ArkPsbtFieldKey", { enumerable: true, get: funct
 Object.defineProperty(exports, "ArkPsbtFieldKeyType", { enumerable: true, get: function () { return unknownFields_1.ArkPsbtFieldKeyType; } });
 Object.defineProperty(exports, "CosignerPublicKey", { enumerable: true, get: function () { return unknownFields_1.CosignerPublicKey; } });
 Object.defineProperty(exports, "VtxoTreeExpiry", { enumerable: true, get: function () { return unknownFields_1.VtxoTreeExpiry; } });
-const bip322_1 = require("./bip322");
-Object.defineProperty(exports, "BIP322", { enumerable: true, get: function () { return bip322_1.BIP322; } });
+const intent_1 = require("./intent");
+Object.defineProperty(exports, "Intent", { enumerable: true, get: function () { return intent_1.Intent; } });
 const arknote_1 = require("./arknote");
 Object.defineProperty(exports, "ArkNote", { enumerable: true, get: function () { return arknote_1.ArkNote; } });
 const networks_1 = require("./networks");
@@ -77,3 +82,6 @@ const walletRepository_1 = require("./repositories/walletRepository");
 Object.defineProperty(exports, "WalletRepositoryImpl", { enumerable: true, get: function () { return walletRepository_1.WalletRepositoryImpl; } });
 const contractRepository_1 = require("./repositories/contractRepository");
 Object.defineProperty(exports, "ContractRepositoryImpl", { enumerable: true, get: function () { return contractRepository_1.ContractRepositoryImpl; } });
+const errors_1 = require("./providers/errors");
+Object.defineProperty(exports, "ArkError", { enumerable: true, get: function () { return errors_1.ArkError; } });
+Object.defineProperty(exports, "maybeArkError", { enumerable: true, get: function () { return errors_1.maybeArkError; } });

package/dist/cjs/{bip322 → intent}/index.js

@@ -1,26 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BIP322 = void 0;
-exports.craftToSpendTx = craftToSpendTx;
-const script_js_1 = require("@scure/btc-signer/script.js");
-const transaction_js_1 = require("@scure/btc-signer/transaction.js");
-const script_js_2 = require("@scure/btc-signer/script.js");
-const errors_1 = require("./errors");
+exports.Intent = void 0;
+const btc_signer_1 = require("@scure/btc-signer");
 const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
-const base_1 = require("@scure/base");
+const transaction_1 = require("../utils/transaction");
 /**
- * BIP-322 signature implementation for Bitcoin message signing.
+ * Intent proof implementation for Bitcoin message signing.
  *
- * BIP-322 defines a standard for signing Bitcoin messages as well as proving
+ * Intent proof defines a standard for signing Bitcoin messages as well as proving
  * ownership of coins. This namespace provides utilities for creating and
- * validating BIP-322.
+ * validating Intent proof.
  *
+ * it is greatly inspired by BIP322.
  * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
  *
  * @example
  * ```typescript
- * // Create a BIP-322 proof
- * const proof = BIP322.create(
+ * // Create a Intent proof
+ * const proof = Intent.create(
  *   "Hello Bitcoin!",
  *   [input],
  *   [output]
@@ -29,65 +26,46 @@ const base_1 = require("@scure/base");
  * // Sign the proof
  * const signedProof = await identity.sign(proof);
  *
- * // Extract the signature
- * const signature = BIP322.signature(signedProof);
- * ```
  */
-var BIP322;
-(function (BIP322) {
+var Intent;
+(function (Intent) {
     /**
-     * Creates a new BIP-322 "full" proof of funds unsigned transaction.
+     * Creates a new Intent proof unsigned transaction.
      *
      * This function constructs a special transaction that can be signed to prove
      * ownership of VTXOs and UTXOs. The proof includes the message to be
      * signed and the inputs/outputs that demonstrate ownership.
      *
-     * @param message - The BIP-322 message to be signed
+     * @param message - The Intent message to be signed
      * @param inputs - Array of transaction inputs to prove ownership of
      * @param outputs - Optional array of transaction outputs
-     * @returns An unsigned BIP-322 proof transaction
+     * @returns An unsigned Intent proof transaction
      */
     function create(message, inputs, outputs = []) {
         if (inputs.length == 0)
-            throw errors_1.ErrMissingInputs;
+            throw new Error("intent proof requires at least one input");
         if (!validateInputs(inputs))
-            throw errors_1.ErrMissingData;
+            throw new Error("invalid inputs");
         if (!validateOutputs(outputs))
-            throw errors_1.ErrMissingData;
+            throw new Error("invalid outputs");
         // create the initial transaction to spend
         const toSpend = craftToSpendTx(message, inputs[0].witnessUtxo.script);
         // create the transaction to sign
         return craftToSignTx(toSpend, inputs, outputs);
     }
-    BIP322.create = create;
-    /**
-     * Finalizes and extracts the FullProof transaction into a BIP-322 signature.
-     *
-     * This function takes a signed proof transaction and converts it into a
-     * base64-encoded signature string. If the proof's inputs have special
-     * spending conditions, a custom finalizer can be provided.
-     *
-     * @param signedProof - The signed BIP-322 proof transaction
-     * @param finalizer - Optional custom finalizer function
-     * @returns Base64-encoded BIP-322 signature
-     */
-    function signature(signedProof, finalizer = (tx) => tx.finalize()) {
-        finalizer(signedProof);
-        return base_1.base64.encode(signedProof.extract());
-    }
-    BIP322.signature = signature;
-})(BIP322 || (exports.BIP322 = BIP322 = {}));
-const OP_RETURN_EMPTY_PKSCRIPT = new Uint8Array([script_js_1.OP.RETURN]);
+    Intent.create = create;
+})(Intent || (exports.Intent = Intent = {}));
+const OP_RETURN_EMPTY_PKSCRIPT = new Uint8Array([btc_signer_1.OP.RETURN]);
 const ZERO_32 = new Uint8Array(32).fill(0);
 const MAX_INDEX = 0xffffffff;
-const TAG_BIP322 = "BIP0322-signed-message";
+const TAG_INTENT_PROOF = "ark-intent-proof-message";
 function validateInput(input) {
     if (input.index === undefined)
-        throw errors_1.ErrMissingData;
+        throw new Error("intent proof input requires index");
     if (input.txid === undefined)
-        throw errors_1.ErrMissingData;
+        throw new Error("intent proof input requires txid");
     if (input.witnessUtxo === undefined)
-        throw errors_1.ErrMissingWitnessUtxo;
+        throw new Error("intent proof input requires witness utxo");
     return true;
 }
 function validateInputs(inputs) {
@@ -96,9 +74,9 @@ function validateInputs(inputs) {
 }
 function validateOutput(output) {
     if (output.amount === undefined)
-        throw errors_1.ErrMissingData;
+        throw new Error("intent proof output requires amount");
     if (output.script === undefined)
-        throw errors_1.ErrMissingData;
+        throw new Error("intent proof output requires script");
     return true;
 }
 function validateOutputs(outputs) {
@@ -108,11 +86,8 @@ function validateOutputs(outputs) {
 // craftToSpendTx creates the initial transaction that will be spent in the proof
 function craftToSpendTx(message, pkScript) {
     const messageHash = hashMessage(message);
-    const tx = new transaction_js_1.Transaction({
+    const tx = new transaction_1.Transaction({
         version: 0,
-        allowUnknownOutputs: true,
-        allowUnknown: true,
-        allowUnknownInputs: true,
     });
     // add input with zero hash and max index
     tx.addInput({
@@ -126,18 +101,15 @@ function craftToSpendTx(message, pkScript) {
         script: pkScript,
     });
     tx.updateInput(0, {
-        finalScriptSig: script_js_2.Script.encode(["OP_0", messageHash]),
+        finalScriptSig: btc_signer_1.Script.encode(["OP_0", messageHash]),
     });
     return tx;
 }
 // craftToSignTx creates the transaction that will be signed for the proof
 function craftToSignTx(toSpend, inputs, outputs) {
     const firstInput = inputs[0];
-    const tx = new transaction_js_1.Transaction({
+    const tx = new transaction_1.Transaction({
         version: 2,
-        allowUnknownOutputs: outputs.length === 0,
-        allowUnknown: true,
-        allowUnknownInputs: true,
         lockTime: 0,
     });
     // add the first "toSpend" input
@@ -149,14 +121,19 @@ function craftToSignTx(toSpend, inputs, outputs) {
             script: firstInput.witnessUtxo.script,
             amount: 0n,
         },
-        sighashType: transaction_js_1.SigHash.ALL,
+        sighashType: btc_signer_1.SigHash.ALL,
     });
     // add other inputs
-    for (const input of inputs) {
+    for (const [i, input] of inputs.entries()) {
         tx.addInput({
             ...input,
-            sighashType: transaction_js_1.SigHash.ALL,
+            sighashType: btc_signer_1.SigHash.ALL,
         });
+        if (input.unknown?.length) {
+            tx.updateInput(i + 1, {
+                unknown: input.unknown,
+            });
+        }
     }
     // add the special OP_RETURN output if no outputs are provided
     if (outputs.length === 0) {
@@ -176,5 +153,5 @@ function craftToSignTx(toSpend, inputs, outputs) {
     return tx;
 }
 function hashMessage(message) {
-    return secp256k1_js_1.schnorr.utils.taggedHash(TAG_BIP322, new TextEncoder().encode(message));
+    return secp256k1_js_1.schnorr.utils.taggedHash(TAG_INTENT_PROOF, new TextEncoder().encode(message));
 }

package/dist/cjs/musig2/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.aggregateKeys = exports.sign = exports.PartialSig = exports.generateNonces = void 0;
+exports.aggregateKeys = exports.sign = exports.PartialSig = exports.aggregateNonces = exports.generateNonces = void 0;
 var nonces_1 = require("./nonces");
 Object.defineProperty(exports, "generateNonces", { enumerable: true, get: function () { return nonces_1.generateNonces; } });
+Object.defineProperty(exports, "aggregateNonces", { enumerable: true, get: function () { return nonces_1.aggregateNonces; } });
 var sign_1 = require("./sign");
 Object.defineProperty(exports, "PartialSig", { enumerable: true, get: function () { return sign_1.PartialSig; } });
 Object.defineProperty(exports, "sign", { enumerable: true, get: function () { return sign_1.sign; } });

package/dist/cjs/musig2/nonces.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateNonces = generateNonces;
+exports.aggregateNonces = aggregateNonces;
 const musig = __importStar(require("@scure/btc-signer/musig2.js"));
 /**
  * Generates a pair of public and secret nonces for MuSig2 signing
@@ -42,3 +43,6 @@ function generateNonces(publicKey) {
     const nonces = musig.nonceGen(publicKey);
     return { secNonce: nonces.secret, pubNonce: nonces.public };
 }
+function aggregateNonces(pubNonces) {
+    return musig.nonceAggregate(pubNonces);
+}