beignet 0.2.0 → 0.3.0

package/dist/wallet/index.js

@@ -29,7 +29,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Wallet = void 0;
 const bip39 = __importStar(require("bip39"));
 const bitcoin = __importStar(require("bitcoinjs-lib"));
-const bitcoinjs_lib_1 = require("bitcoinjs-lib");
 const bip32_1 = __importDefault(require("bip32"));
 const ecc = __importStar(require("@bitcoinerlab/secp256k1"));
 const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
@@ -42,12 +41,12 @@ const constants_1 = require("./constants");
 const conversion_1 = require("../utils/conversion");
 const bip32 = (0, bip32_1.default)(ecc);
 class Wallet {
-    constructor({ mnemonic, passphrase, name, network = types_1.EAvailableNetworks.mainnet, addressType = types_1.EAddressType.p2wpkh, coinSelectPreference = types_1.ECoinSelectPreference.consolidate, storage, electrumOptions, onMessage = () => null, customGetAddress, customGetScriptHash, rbf = false, selectedFeeId = types_1.EFeeId.normal, disableMessages = false, disableMessagesOnCreate = false, addressTypesToMonitor = Object.values(types_1.EAddressType), gapLimitOptions = {
+    constructor({ mnemonic, xpub, passphrase, name, network = types_1.EAvailableNetworks.mainnet, addressType, account = 0, birthdayHeight, coinSelectPreference = types_1.ECoinSelectPreference.consolidate, storage, electrumOptions, onMessage = () => null, customGetAddress, customGetScriptHash, rbf = false, selectedFeeId = types_1.EFeeId.normal, feeEstimationSource = 'auto', disableMessages = false, disableMessagesOnCreate = false, addressTypesToMonitor = Object.values(types_1.EAddressType), gapLimitOptions = {
         lookBehind: constants_1.GAP_LIMIT,
         lookAhead: constants_1.GAP_LIMIT,
         lookBehindChange: constants_1.GAP_LIMIT_CHANGE,
         lookAheadChange: constants_1.GAP_LIMIT_CHANGE
-    } }) {
+    }, multisig }) {
         this._pendingRefreshPromises = [];
         this.savingOperations = {};
         this.getReceiveAddress = async ({ addressType = this.addressType }) => {
@@ -95,7 +94,9 @@ class Wallet {
         };
         this.getBip32Interface = async () => {
             try {
-                const network = bitcoinjs_lib_1.networks[this._network];
+                if (!this._mnemonic)
+                    return (0, utils_1.err)(new utils_1.WatchOnlySigningError());
+                const network = (0, utils_1.getBitcoinJsNetwork)(this._network);
                 const seed = await bip39.mnemonicToSeed(this._mnemonic, this._passphrase);
                 const root = bip32.fromSeed(seed, network);
                 return (0, utils_1.ok)(root);
@@ -104,17 +105,67 @@ class Wallet {
                 return (0, utils_1.err)(e);
             }
         };
-        if (!mnemonic)
+        if (!mnemonic && !xpub && !multisig) {
             throw new Error('No mnemonic specified.');
-        if (!(0, utils_1.validateMnemonic)(mnemonic))
-            throw new Error('Invalid mnemonic.');
+        }
         if (name && name.includes('-'))
             throw new Error('Wallet name cannot include a hyphen (-).');
+        if (!Number.isInteger(account) || account < 0) {
+            throw new Error('account must be a non-negative integer.');
+        }
+        if (birthdayHeight !== undefined &&
+            (!Number.isInteger(birthdayHeight) || birthdayHeight < 0)) {
+            throw new Error('birthdayHeight must be a non-negative integer.');
+        }
+        this._account = String(account);
+        this._birthdayHeightOption = birthdayHeight;
         this._network = network;
-        this._mnemonic = mnemonic;
         this._passphrase = passphrase ?? '';
-        this._seed = (0, utils_1.getSeed)(this._mnemonic, this._passphrase);
-        this._root = bip32.fromSeed(this._seed, this.getBitcoinNetwork(this._network));
+        this.isWatchOnly = !mnemonic;
+        if (mnemonic) {
+            if (!(0, utils_1.validateMnemonic)(mnemonic))
+                throw new Error('Invalid mnemonic.');
+            this._mnemonic = mnemonic;
+            this._seed = (0, utils_1.getSeed)(this._mnemonic, this._passphrase);
+            this._root = bip32.fromSeed(this._seed, this.getBitcoinNetwork(this._network));
+        }
+        if (multisig) {
+            if (addressType && addressType !== types_1.EAddressType.p2wsh) {
+                throw new Error('Multisig wallets only support the p2wsh address type.');
+            }
+            const setup = this._initMultisig(multisig);
+            this._multisig = setup.config;
+            this.id = setup.id;
+            this.addressType = types_1.EAddressType.p2wsh;
+            addressTypesToMonitor = [types_1.EAddressType.p2wsh];
+        }
+        else if (mnemonic) {
+            if (addressType === types_1.EAddressType.p2wsh) {
+                throw new Error('p2wsh is a multisig address type. Use Wallet.createMultisig.');
+            }
+            this.id = (0, utils_1.generateWalletId)(this._seed);
+            this.addressType = addressType ?? types_1.EAddressType.p2wpkh;
+        }
+        else {
+            const parseRes = (0, utils_1.parseExtendedPublicKey)(xpub, this._network);
+            if (parseRes.isErr())
+                throw parseRes.error;
+            const { node, addressType: inferredType } = parseRes.value;
+            if (addressType && inferredType && addressType !== inferredType) {
+                throw new Error(`The provided xpub prefix implies ${inferredType}, but addressType ${addressType} was requested.`);
+            }
+            const resolvedType = addressType ?? inferredType ?? types_1.EAddressType.p2wpkh;
+            if (resolvedType === types_1.EAddressType.p2wsh) {
+                throw new Error('p2wsh is a multisig address type. Use Wallet.createMultisig with every cosigner xpub.');
+            }
+            this._accountNode = node;
+            this.addressType = resolvedType;
+            this.id = (0, utils_1.generateWalletId)(Buffer.concat([node.publicKey, node.chainCode]));
+            addressTypesToMonitor = [this.addressType];
+        }
+        if (!this._multisig) {
+            addressTypesToMonitor = addressTypesToMonitor.filter((type) => type !== types_1.EAddressType.p2wsh);
+        }
         this._data = (0, utils_1.getDefaultWalletData)();
         this._getData = storage?.getData ?? utils_1.getDataFallback;
         this._setData = storage?.setData;
@@ -123,9 +174,7 @@ class Wallet {
             this._customGetAddress = customGetAddress;
         if (customGetScriptHash)
             this._customGetScriptHash = customGetScriptHash;
-        this.id = (0, utils_1.generateWalletId)(this._seed);
         this.name = name ?? this.id;
-        this.addressType = addressType;
         this.coinSelectPreference = coinSelectPreference;
         this.transaction = new transaction_1.Transaction({
             wallet: this
@@ -145,6 +194,7 @@ class Wallet {
         });
         this.rbf = rbf;
         this.selectedFeeId = selectedFeeId;
+        this.feeEstimationSource = feeEstimationSource;
         this.isRefreshing = false;
         this.isSwitchingNetworks = false;
         this.addressTypesToMonitor = addressTypesToMonitor;
@@ -185,6 +235,23 @@ class Wallet {
     get network() {
         return this._network;
     }
+    get account() {
+        return Number(this._account);
+    }
+    get birthdayHeight() {
+        return this._data.birthdayHeight ?? 0;
+    }
+    get isMultisig() {
+        return !!this._multisig;
+    }
+    get multisigInfo() {
+        if (!this._multisig)
+            return undefined;
+        return {
+            threshold: this._multisig.threshold,
+            totalCosigners: this._multisig.cosigners.length
+        };
+    }
     static async create(params) {
         try {
             const wallet = new Wallet(params);
@@ -201,6 +268,136 @@ class Wallet {
             return (0, utils_1.err)(e);
         }
     }
+    static async createWatchOnly(params) {
+        if (!params?.xpub)
+            return (0, utils_1.err)('No xpub provided.');
+        return await Wallet.create(params);
+    }
+    static async createMultisig(params) {
+        if (!params)
+            return (0, utils_1.err)('No multisig parameters provided.');
+        const { threshold, cosigners, ourXpub, ...walletParams } = params;
+        return await Wallet.create({
+            ...walletParams,
+            addressType: types_1.EAddressType.p2wsh,
+            multisig: { threshold, cosigners, ourXpub }
+        });
+    }
+    _initMultisig(multisig) {
+        const { threshold, cosigners, ourXpub } = multisig;
+        if (!Number.isInteger(threshold) || threshold < 1) {
+            throw new Error('Multisig threshold must be a positive integer.');
+        }
+        const keyId = (node) => Buffer.concat([node.publicKey, node.chainCode]).toString('hex');
+        const entries = [];
+        const addCosigner = (xpub) => {
+            const res = (0, utils_1.parseExtendedPublicKey)(xpub, this._network);
+            if (res.isErr())
+                throw res.error;
+            const node = res.value.node;
+            if (entries.some((e) => keyId(e.node) === keyId(node))) {
+                throw new Error(`Duplicate cosigner xpub provided: ${xpub}`);
+            }
+            entries.push({ node, isOurs: false });
+        };
+        for (const xpub of cosigners ?? [])
+            addCosigner(xpub);
+        if (this._root) {
+            const coinType = this._network === types_1.EAvailableNetworks.bitcoin ? '0' : '1';
+            const ourNode = this._root
+                .derivePath(`m/48'/${coinType}'/${this._account}'/2'`)
+                .neutered();
+            if (ourXpub) {
+                const parsed = (0, utils_1.parseExtendedPublicKey)(ourXpub, this._network);
+                if (parsed.isErr())
+                    throw parsed.error;
+                if (keyId(parsed.value.node) !== keyId(ourNode)) {
+                    throw new Error(`ourXpub does not match the account xpub derived from the mnemonic at m/48'/${coinType}'/${this._account}'/2'.`);
+                }
+            }
+            const existing = entries.find((e) => keyId(e.node) === keyId(ourNode));
+            if (existing) {
+                existing.isOurs = true;
+            }
+            else {
+                entries.push({ node: ourNode, isOurs: true });
+            }
+        }
+        else if (ourXpub) {
+            addCosigner(ourXpub);
+        }
+        const n = entries.length;
+        if (threshold > n) {
+            throw new Error(`Multisig threshold (${threshold}) exceeds the number of cosigners (${n}).`);
+        }
+        if (n > 15) {
+            throw new Error(`Multisig supports at most 15 cosigners, received ${n}.`);
+        }
+        entries.sort((a, b) => a.node.publicKey.compare(b.node.publicKey));
+        const id = (0, utils_1.generateWalletId)(Buffer.concat([
+            Buffer.from('sortedmulti'),
+            Buffer.from([threshold, n]),
+            ...entries.map((e) => Buffer.concat([e.node.publicKey, e.node.chainCode]))
+        ]));
+        return { config: { threshold, cosigners: entries }, id };
+    }
+    getMultisigPayment(path) {
+        try {
+            if (!this._multisig) {
+                return (0, utils_1.err)('This wallet is not a multisig wallet.');
+            }
+            const parsed = (0, utils_1.parseBip48Path)(path);
+            if (parsed.isErr())
+                return (0, utils_1.err)(parsed.error.message);
+            const { coinType, account, change, index } = parsed.value;
+            const expectedCoin = this._network === types_1.EAvailableNetworks.bitcoin ? '0' : '1';
+            if (coinType !== expectedCoin || account !== this._account) {
+                return (0, utils_1.err)(`Path ${path} does not match this wallet (expected m/48'/${expectedCoin}'/${this._account}'/2'/change/index).`);
+            }
+            const payment = (0, utils_1.buildSortedMultisigPayment)({
+                threshold: this._multisig.threshold,
+                cosignerNodes: this._multisig.cosigners.map((c) => c.node),
+                change,
+                index,
+                network: this.getBitcoinNetwork()
+            });
+            if (payment.isErr())
+                return (0, utils_1.err)(payment.error.message);
+            const perCosigner = this._multisig.cosigners
+                .map((c) => {
+                let masterFingerprint;
+                if (c.isOurs && this._root) {
+                    masterFingerprint = Buffer.from(this._root.fingerprint);
+                }
+                else {
+                    masterFingerprint = Buffer.alloc(4);
+                    masterFingerprint.writeUInt32BE(c.node.parentFingerprint ?? 0, 0);
+                }
+                return {
+                    masterFingerprint,
+                    path,
+                    pubkey: c.node.derive(change).derive(index).publicKey,
+                    isOurs: c.isOurs
+                };
+            })
+                .sort((a, b) => a.pubkey.compare(b.pubkey));
+            const ours = perCosigner.find((d) => d.isOurs);
+            return (0, utils_1.ok)({
+                address: payment.value.address,
+                output: payment.value.output,
+                witnessScript: payment.value.witnessScript,
+                publicKey: ours && this._root ? ours.pubkey.toString('hex') : '',
+                derivations: perCosigner.map((d) => ({
+                    masterFingerprint: d.masterFingerprint,
+                    path: d.path,
+                    pubkey: d.pubkey
+                }))
+            });
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
     async stop() {
         try {
             if (this.isRefreshing) {
@@ -219,6 +416,12 @@ class Wallet {
         this.coinSelectPreference = coinSelectPreference;
     }
     async switchNetwork(network, servers) {
+        if (this._multisig) {
+            return (0, utils_1.err)('Multisig wallets cannot switch networks. Create a new multisig wallet with cosigner xpubs for the target network.');
+        }
+        if (this.isWatchOnly) {
+            return (0, utils_1.err)('Watch-only wallets cannot switch networks. Create a new watch-only wallet with an xpub for the target network.');
+        }
         this.isSwitchingNetworks = true;
         await this.electrum.disconnect();
         this._network = network;
@@ -227,6 +430,8 @@ class Wallet {
             ...this,
             mnemonic: this._mnemonic,
             passphrase: this._passphrase,
+            account: Number(this._account),
+            birthdayHeight: this._birthdayHeightOption,
             network,
             electrumOptions: {
                 servers,
@@ -249,6 +454,12 @@ class Wallet {
         return (0, utils_1.ok)(this);
     }
     async updateAddressType(addressType) {
+        if (addressType === types_1.EAddressType.p2wsh && !this._multisig) {
+            throw new Error('p2wsh is a multisig address type. Use Wallet.createMultisig.');
+        }
+        if (this._multisig && addressType !== types_1.EAddressType.p2wsh) {
+            throw new Error('Multisig wallets only support the p2wsh address type.');
+        }
         this.addressType = addressType;
         if (!this.addressTypesToMonitor.includes(this.addressType)) {
             this.addressTypesToMonitor.push(this.addressType);
@@ -324,6 +535,7 @@ class Wallet {
             if (walletDataResponse.isErr())
                 return (0, utils_1.err)(walletDataResponse.error.message);
             this._data = walletDataResponse.value;
+            await this._applyBirthdayHeightOption();
             return (0, utils_1.ok)(true);
         }
         catch (e) {
@@ -346,7 +558,19 @@ class Wallet {
         return (0, utils_1.ok)("ID's match, it's safe to continue.");
     }
     getWalletDataKey(key) {
-        return (0, utils_1.getWalletDataStorageKey)(this.name, this._network, key);
+        return (0, utils_1.getWalletDataStorageKey)(this.name, this._network, key, Number(this._account));
+    }
+    async _applyBirthdayHeightOption() {
+        if (this._birthdayHeightOption === undefined)
+            return;
+        const stored = this._data.birthdayHeight ?? 0;
+        const next = stored > 0
+            ? Math.min(stored, this._birthdayHeightOption)
+            : this._birthdayHeightOption;
+        if (next !== stored) {
+            this._data.birthdayHeight = next;
+            await this.saveWalletData('birthdayHeight', next);
+        }
     }
     async getWalletData() {
         try {
@@ -413,6 +637,12 @@ class Wallet {
                     case 'feeEstimates':
                         walletData[key] = data;
                         break;
+                    case 'addressLabels':
+                        walletData[key] = data;
+                        break;
+                    case 'birthdayHeight':
+                        walletData[key] = data;
+                        break;
                     default:
                         console.log(`Unhandled key in getWalletData: ${key}`);
                         break;
@@ -428,13 +658,77 @@ class Wallet {
     getBitcoinNetwork(network) {
         if (!network)
             network = this._network;
-        return bitcoin.networks[network];
+        return (0, utils_1.getBitcoinJsNetwork)(network);
     }
     isValid(mnemonic) {
-        return mnemonic === this._mnemonic && (0, utils_1.validateMnemonic)(mnemonic);
+        return (!!this._mnemonic &&
+            mnemonic === this._mnemonic &&
+            (0, utils_1.validateMnemonic)(mnemonic));
+    }
+    _derivePathKeyPair(path) {
+        if (this._root)
+            return this._root.derivePath(path);
+        return this._deriveWatchOnlyNode(path);
+    }
+    _deriveWatchOnlyNode(path) {
+        if (!this._accountNode) {
+            throw new Error('Watch-only account node is unavailable.');
+        }
+        const segments = path.replace(/'/g, '').split('/');
+        if (segments.length !== 6) {
+            throw new Error(`Watch-only wallets require a full path (m/purpose'/coin'/account'/change/index): ${path}`);
+        }
+        const expectedPathRes = (0, utils_1.getKeyDerivationPathObject)({
+            path: shapes_1.addressTypes[this.addressType].path,
+            network: this._network
+        });
+        if (expectedPathRes.isErr())
+            throw expectedPathRes.error;
+        if (segments[1] !== expectedPathRes.value.purpose) {
+            throw new Error(`This watch-only wallet only derives ${this.addressType} paths (purpose ${expectedPathRes.value.purpose}'), received: ${path}`);
+        }
+        const change = Number(segments[4]);
+        const index = Number(segments[5]);
+        if (!Number.isInteger(change) ||
+            !Number.isInteger(index) ||
+            change < 0 ||
+            index < 0) {
+            throw new Error(`Invalid change/index segments in path: ${path}`);
+        }
+        return this._accountNode.derive(change).derive(index);
+    }
+    derivePublicNode(path) {
+        try {
+            if (this._root)
+                return (0, utils_1.ok)(this._root.derivePath(path).neutered());
+            return (0, utils_1.ok)(this._deriveWatchOnlyNode(path));
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    getMasterFingerprint() {
+        if (this._root)
+            return Buffer.from(this._root.fingerprint);
+        const fingerprint = Buffer.alloc(4);
+        fingerprint.writeUInt32BE(this._accountNode?.parentFingerprint ?? 0, 0);
+        return fingerprint;
     }
     async _getAddress(path, addressType) {
         try {
+            if (addressType === types_1.EAddressType.p2wsh) {
+                if (!this._multisig) {
+                    return (0, utils_1.err)('p2wsh addresses require a multisig wallet (Wallet.createMultisig).');
+                }
+                const payment = this.getMultisigPayment(path);
+                if (payment.isErr())
+                    return (0, utils_1.err)(payment.error.message);
+                return (0, utils_1.ok)({
+                    address: payment.value.address,
+                    publicKey: payment.value.publicKey,
+                    path
+                });
+            }
             if (this._customGetAddress) {
                 const data = {
                     path,
@@ -445,7 +739,7 @@ class Wallet {
                 if (res.isErr())
                     return (0, utils_1.err)(res.error.message);
             }
-            const keyPair = this._root.derivePath(path);
+            const keyPair = this._derivePathKeyPair(path);
             const network = this.getBitcoinNetwork(this._network);
             const addressInfo = (0, utils_1.getAddressFromKeyPair)({
                 keyPair,
@@ -473,6 +767,7 @@ class Wallet {
                 addressType,
                 changeAddress,
                 index,
+                accountType: this._account,
                 network: this._network
             });
             if (pathRes.isErr()) {
@@ -559,6 +854,8 @@ class Wallet {
         return (0, utils_1.getScriptHash)({ address, network });
     }
     getPrivateKey(path) {
+        if (!this._root)
+            throw new utils_1.WatchOnlySigningError();
         const keyPair = this._root.derivePath(path);
         return keyPair.toWIF();
     }
@@ -582,6 +879,7 @@ class Wallet {
                 if (keyDerivationPathResponse.isErr())
                     return (0, utils_1.err)(keyDerivationPathResponse.error.message);
                 keyDerivationPath = keyDerivationPathResponse.value;
+                keyDerivationPath.account = this._account;
             }
             const addresses = {};
             const changeAddresses = {};
@@ -681,6 +979,7 @@ class Wallet {
                 return (0, utils_1.err)(result.error.message);
             }
             const { pathObject: keyDerivationPath } = result.value;
+            keyDerivationPath.account = this._account;
             let addressIndex = currentWallet.addressIndex[addressType];
             let lastUsedAddressIndex = currentWallet.lastUsedAddressIndex[addressType];
             let changeAddressIndex = currentWallet.changeAddressIndex[addressType];
@@ -941,6 +1240,7 @@ class Wallet {
                 return (0, utils_1.err)(keyDerivationPathResponse.error.message);
             }
             keyDerivationPath = keyDerivationPathResponse.value;
+            keyDerivationPath.account = this._account;
         }
         const generatedAddresses = await this.generateAddresses({
             addressAmount,
@@ -1141,6 +1441,7 @@ class Wallet {
                     return (0, utils_1.err)(keyDerivationPathResponse.error.message);
                 }
                 keyDerivationPath = keyDerivationPathResponse.value;
+                keyDerivationPath.account = this._account;
             }
             const addresses = currentWallet.addresses[addressType];
             const currentAddressIndex = currentWallet.addressIndex[addressType].index;
@@ -1234,6 +1535,174 @@ class Wallet {
     listUtxos() {
         return this.data.utxos;
     }
+    isUtxoFrozen(txid, index) {
+        return this.data.blacklistedUtxos.some((frozen) => frozen.tx_hash === txid && frozen.tx_pos === index);
+    }
+    async freezeUtxo({ txid, index }) {
+        if (typeof txid !== 'string' || !/^[0-9a-fA-F]{64}$/.test(txid)) {
+            return (0, utils_1.err)('txid must be a 64-character hex string.');
+        }
+        if (!Number.isInteger(index) || index < 0) {
+            return (0, utils_1.err)('index must be a non-negative integer.');
+        }
+        const utxo = this.data.utxos.find((u) => u.tx_hash === txid && u.tx_pos === index);
+        if (!utxo) {
+            return (0, utils_1.err)(`UTXO ${txid}:${index} is not known to this wallet.`);
+        }
+        if (this.isUtxoFrozen(txid, index)) {
+            return (0, utils_1.ok)(`UTXO ${txid}:${index} is already frozen.`);
+        }
+        const { keyPair, ...frozen } = utxo;
+        void keyPair;
+        this._data.blacklistedUtxos.push(frozen);
+        await this.saveWalletData('blacklistedUtxos', this._data.blacklistedUtxos);
+        return (0, utils_1.ok)(`UTXO ${txid}:${index} frozen.`);
+    }
+    async unfreezeUtxo({ txid, index }) {
+        const before = this._data.blacklistedUtxos.length;
+        this._data.blacklistedUtxos = this._data.blacklistedUtxos.filter((frozen) => !(frozen.tx_hash === txid && frozen.tx_pos === index));
+        if (this._data.blacklistedUtxos.length === before) {
+            return (0, utils_1.err)(`UTXO ${txid}:${index} is not frozen.`);
+        }
+        await this.saveWalletData('blacklistedUtxos', this._data.blacklistedUtxos);
+        return (0, utils_1.ok)(`UTXO ${txid}:${index} unfrozen.`);
+    }
+    listFrozenUtxos() {
+        return this.data.blacklistedUtxos;
+    }
+    getBalanceBreakdown() {
+        const total = this.getBalance();
+        const frozen = this.data.utxos.reduce((acc, utxo) => {
+            return this.isUtxoFrozen(utxo.tx_hash, utxo.tx_pos)
+                ? acc + utxo.value
+                : acc;
+        }, 0);
+        return { total, spendable: total - frozen, frozen };
+    }
+    async setAddressLabel(address, label) {
+        if (!address || !this.validateAddress(address)) {
+            return (0, utils_1.err)(`Invalid ${this._network} address: ${address}`);
+        }
+        if (typeof label !== 'string') {
+            return (0, utils_1.err)('label must be a string.');
+        }
+        if (label.length > 255) {
+            return (0, utils_1.err)('label must be 255 characters or fewer.');
+        }
+        if (label === '') {
+            delete this._data.addressLabels[address];
+        }
+        else {
+            this._data.addressLabels[address] = label;
+        }
+        await this.saveWalletData('addressLabels', this._data.addressLabels);
+        return (0, utils_1.ok)(label === '' ? 'Label removed.' : 'Label saved.');
+    }
+    getAddressLabel(address) {
+        return this.data.addressLabels[address];
+    }
+    listAddressLabels() {
+        return { ...this.data.addressLabels };
+    }
+    exportDescriptors() {
+        try {
+            const fingerprint = this.getMasterFingerprint().toString('hex');
+            const descriptors = [];
+            const wrap = (addressType, keyExpr) => {
+                switch (addressType) {
+                    case types_1.EAddressType.p2pkh:
+                        return `pkh(${keyExpr})`;
+                    case types_1.EAddressType.p2sh:
+                        return `sh(wpkh(${keyExpr}))`;
+                    case types_1.EAddressType.p2wpkh:
+                        return `wpkh(${keyExpr})`;
+                    case types_1.EAddressType.p2tr:
+                        return `tr(${keyExpr})`;
+                    case types_1.EAddressType.p2wsh:
+                        return `wsh(${keyExpr})`;
+                }
+            };
+            if (this._multisig) {
+                const coinType = this._network === types_1.EAvailableNetworks.bitcoin ? '0' : '1';
+                const keyExpr = (chain) => {
+                    const keys = this._multisig.cosigners.map((cosigner) => {
+                        const xpub = this._toStandardBase58(cosigner.node);
+                        let origin;
+                        if (cosigner.isOurs && this._root) {
+                            origin = `[${fingerprint}/48h/${coinType}h/${this._account}h/2h]`;
+                        }
+                        else {
+                            const parentFp = Buffer.alloc(4);
+                            parentFp.writeUInt32BE(cosigner.node.parentFingerprint ?? 0, 0);
+                            origin = `[${parentFp.toString('hex')}]`;
+                        }
+                        return `${origin}${xpub}/${chain}/*`;
+                    });
+                    return `sortedmulti(${this._multisig.threshold},${keys.join(',')})`;
+                };
+                descriptors.push({
+                    addressType: types_1.EAddressType.p2wsh,
+                    external: (0, utils_1.appendDescriptorChecksum)(`wsh(${keyExpr(0)})`),
+                    internal: (0, utils_1.appendDescriptorChecksum)(`wsh(${keyExpr(1)})`)
+                });
+            }
+            else if (this.isWatchOnly) {
+                if (!this._accountNode) {
+                    return (0, utils_1.err)('Watch-only account node is unavailable.');
+                }
+                const xpub = this._toStandardBase58(this._accountNode);
+                descriptors.push({
+                    addressType: this.addressType,
+                    external: (0, utils_1.appendDescriptorChecksum)(wrap(this.addressType, `${xpub}/0/*`)),
+                    internal: (0, utils_1.appendDescriptorChecksum)(wrap(this.addressType, `${xpub}/1/*`))
+                });
+            }
+            else {
+                if (!this._root)
+                    return (0, utils_1.err)('Wallet root is unavailable.');
+                const coinType = this._network === types_1.EAvailableNetworks.bitcoin ? '0' : '1';
+                const singleSigTypes = Object.values(types_1.EAddressType).filter((type) => type !== types_1.EAddressType.p2wsh);
+                for (const addressType of singleSigTypes) {
+                    const pathRes = (0, utils_1.getKeyDerivationPathObject)({
+                        path: shapes_1.addressTypes[addressType].path,
+                        network: this._network
+                    });
+                    if (pathRes.isErr())
+                        return (0, utils_1.err)(pathRes.error.message);
+                    const purpose = pathRes.value.purpose;
+                    const accountPath = `m/${purpose}'/${coinType}'/${this._account}'`;
+                    const accountXpub = this._toStandardBase58(this._root.derivePath(accountPath).neutered());
+                    const origin = `[${fingerprint}/${purpose}h/${coinType}h/${this._account}h]`;
+                    descriptors.push({
+                        addressType,
+                        external: (0, utils_1.appendDescriptorChecksum)(wrap(addressType, `${origin}${accountXpub}/0/*`)),
+                        internal: (0, utils_1.appendDescriptorChecksum)(wrap(addressType, `${origin}${accountXpub}/1/*`))
+                    });
+                }
+            }
+            const birthdayHeight = this.birthdayHeight;
+            return (0, utils_1.ok)({
+                fingerprint,
+                network: this._network,
+                account: Number(this._account),
+                ...(birthdayHeight > 0 ? { birthdayHeight } : {}),
+                watchOnly: this.isWatchOnly,
+                descriptors
+            });
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    _toStandardBase58(node) {
+        const standard = this.getBitcoinNetwork(this._network);
+        if (node.network?.bip32?.public === standard.bip32.public) {
+            return node.toBase58();
+        }
+        const clone = Object.create(Object.getPrototypeOf(node), Object.getOwnPropertyDescriptors(node));
+        clone.network = standard;
+        return clone.toBase58();
+    }
     async saveWalletData(key, data) {
         if (!this._setData)
             return 'No setData method has been provided';
@@ -1850,24 +2319,59 @@ class Wallet {
         return (0, utils_1.ok)(generateAddressResponse.value.changeAddresses[0]);
     }
     async getFeeEstimates(network = this._network) {
+        if (network === types_1.EAvailableNetworks.bitcoinRegtest) {
+            return { ...shapes_1.defaultFeesShape, timestamp: Date.now() };
+        }
+        if (this.feeEstimationSource !== 'http') {
+            const electrumFees = await this.getFeeEstimatesFromElectrum();
+            if (electrumFees.isOk()) {
+                return electrumFees.value;
+            }
+            if (this.feeEstimationSource === 'electrum') {
+                return this.feeEstimates;
+            }
+        }
+        return this.getFeeEstimatesFromHttp(network);
+    }
+    async getFeeEstimatesFromElectrum() {
+        if (!this.electrum.connectedToElectrum) {
+            return (0, utils_1.err)('Not connected to an Electrum server.');
+        }
+        const targets = [2, 6, 24, 144];
+        const results = await Promise.all(targets.map((blocks) => this.electrum.getFeeEstimate(blocks)));
+        const [fast, normal, slow, minimum] = results;
+        if (fast.isErr() || normal.isErr() || slow.isErr() || minimum.isErr()) {
+            return (0, utils_1.err)('Electrum returned unusable fee estimates.');
+        }
+        return (0, utils_1.ok)({
+            fast: fast.value,
+            normal: normal.value,
+            slow: slow.value,
+            minimum: minimum.value,
+            timestamp: Date.now()
+        });
+    }
+    async getFeeEstimatesFromHttp(network = this._network) {
         try {
-            if (network === types_1.EAvailableNetworks.bitcoinRegtest) {
-                return { ...shapes_1.defaultFeesShape, timestamp: Date.now() };
+            let urlModifier = '';
+            if (network !== types_1.EAvailableNetworks.bitcoinMainnet) {
+                urlModifier =
+                    network === types_1.EAvailableNetworks.bitcoinSignet ? 'signet/' : 'testnet/';
             }
-            const urlModifier = network === 'bitcoin' ? '' : 'testnet/';
             const response = await fetch(`https://mempool.space/${urlModifier}api/v1/fees/recommended`);
             const res = await response.json();
-            if (!(res.fastestFee > 0 &&
-                res.halfHourFee > 0 &&
-                res.hourFee > 0 &&
-                res.minimumFee > 0)) {
+            const fast = (0, utils_1.clampFeeRate)(res.fastestFee);
+            const normal = (0, utils_1.clampFeeRate)(res.halfHourFee);
+            const slow = (0, utils_1.clampFeeRate)(res.hourFee);
+            const minimum = (0, utils_1.clampFeeRate)(res.minimumFee);
+            if (!(fast > 0 && normal > 0 && slow > 0 && minimum > 0)) {
                 throw new Error('Unexpected response from mempool.space');
             }
             return {
-                fast: res.fastestFee,
-                normal: res.halfHourFee,
-                slow: res.hourFee,
-                minimum: res.minimumFee,
+                fast,
+                normal,
+                slow,
+                minimum,
                 timestamp: Date.now()
             };
         }
@@ -1888,10 +2392,15 @@ class Wallet {
                 res?.onchain?.feeRates?.slow > 0)) {
                 throw new Error('Unexpected response from blocktank');
             }
-            const { fast, mid, slow } = res.onchain.feeRates;
+            const fast = (0, utils_1.clampFeeRate)(res.onchain.feeRates.fast);
+            const normal = (0, utils_1.clampFeeRate)(res.onchain.feeRates.mid);
+            const slow = (0, utils_1.clampFeeRate)(res.onchain.feeRates.slow);
+            if (!(fast > 0 && normal > 0 && slow > 0)) {
+                throw new Error('Unexpected response from blocktank');
+            }
             return {
                 fast,
-                normal: mid,
+                normal,
                 slow,
                 minimum: slow,
                 timestamp: Date.now()
@@ -1915,6 +2424,10 @@ class Wallet {
         });
     }
     async sendMany({ txs = [], satsPerByte = this.feeEstimates.normal, rbf, broadcast = true, shuffleOutputs = true }) {
+        if (this._multisig)
+            return (0, utils_1.err)(new utils_1.MultisigSpendError());
+        if (this.isWatchOnly)
+            return (0, utils_1.err)(new utils_1.WatchOnlySigningError());
         if (!this.data.utxos.length) {
             return (0, utils_1.err)('No UTXOs available.');
         }
@@ -1968,6 +2481,10 @@ class Wallet {
         return (0, utils_1.ok)(broadcastRes.value);
     }
     async sendMax({ address, satsPerByte, rbf = false, broadcast = true } = {}) {
+        if (this._multisig)
+            return (0, utils_1.err)(new utils_1.MultisigSpendError());
+        if (this.isWatchOnly)
+            return (0, utils_1.err)(new utils_1.WatchOnlySigningError());
         if (!this.data.utxos.length) {
             return (0, utils_1.err)('No UTXOs available.');
         }
@@ -2009,6 +2526,242 @@ class Wallet {
             shuffleOutputs
         });
     }
+    async buildPsbt({ txs, address, amount, message = '', satsPerByte = this.feeEstimates.normal, rbf = false, shuffleOutputs = true }) {
+        try {
+            let sendTxs = txs ?? [];
+            if (!sendTxs.length) {
+                if (!address || !amount) {
+                    return (0, utils_1.err)('No outputs provided. Specify txs or address and amount.');
+                }
+                sendTxs = [{ address, amount, message }];
+            }
+            if (!this.data.utxos.length) {
+                return (0, utils_1.err)('No UTXOs available.');
+            }
+            await this.resetSendTransaction();
+            const setupTransactionRes = await this.transaction.setupTransaction({
+                rbf,
+                satsPerByte
+            });
+            if (setupTransactionRes.isErr()) {
+                return (0, utils_1.err)(setupTransactionRes.error.message);
+            }
+            let index = 0;
+            for (const tx of sendTxs) {
+                const updateSendTransactionRes = this.transaction.updateSendTransaction({
+                    transaction: {
+                        label: tx.message,
+                        outputs: [{ address: tx.address, value: tx.amount, index }]
+                    }
+                });
+                if (updateSendTransactionRes.isErr()) {
+                    return (0, utils_1.err)(updateSendTransactionRes.error.message);
+                }
+                index++;
+            }
+            const updateFeeRes = this.transaction.updateFee({ satsPerByte });
+            if (updateFeeRes.isErr())
+                return (0, utils_1.err)(updateFeeRes.error.message);
+            const psbtRes = await this.transaction.createUnsignedPsbt({
+                shuffleOutputs
+            });
+            if (psbtRes.isErr())
+                return (0, utils_1.err)(psbtRes.error.message);
+            const psbt = psbtRes.value;
+            const txData = this.transaction.data;
+            const inputValue = this.transaction.getTransactionInputValue({
+                inputs: txData.inputs
+            });
+            const outputValue = psbt.txOutputs.reduce((acc, o) => acc + o.value, 0);
+            const fee = inputValue - outputValue;
+            const effectiveSatsPerByte = txData.satsPerByte || satsPerByte;
+            const vsizeEstimate = effectiveSatsPerByte > 0 ? Math.round(fee / effectiveSatsPerByte) : 0;
+            const network = this.getBitcoinNetwork();
+            const outputs = psbt.txOutputs.map((output, i) => {
+                let outputAddress = output.address;
+                if (!outputAddress) {
+                    try {
+                        outputAddress = bitcoin.address.fromOutputScript(output.script, network);
+                    }
+                    catch {
+                        outputAddress = undefined;
+                    }
+                }
+                return { address: outputAddress, value: output.value, index: i };
+            });
+            const inputs = txData.inputs.map((input) => ({
+                tx_hash: input.tx_hash,
+                tx_pos: input.tx_pos,
+                address: input.address,
+                value: input.value,
+                path: input.path
+            }));
+            return (0, utils_1.ok)({
+                psbtBase64: psbt.toBase64(),
+                fee,
+                vsizeEstimate,
+                satsPerByte: effectiveSatsPerByte,
+                inputs,
+                outputs
+            });
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    importSignedPsbt(psbtBase64) {
+        try {
+            if (!psbtBase64)
+                return (0, utils_1.err)('No PSBT provided.');
+            const network = this.getBitcoinNetwork();
+            const psbt = bitcoin.Psbt.fromBase64(psbtBase64, { network });
+            if (psbt.inputCount === 0)
+                return (0, utils_1.err)('PSBT has no inputs.');
+            for (let i = 0; i < psbt.inputCount; i++) {
+                const input = psbt.data.inputs[i];
+                const finalized = !!(input.finalScriptSig || input.finalScriptWitness);
+                if (finalized)
+                    continue;
+                const hasSignature = (input.partialSig?.length ?? 0) > 0 ||
+                    !!input.tapKeySig ||
+                    (input.tapScriptSig?.length ?? 0) > 0;
+                if (!hasSignature) {
+                    return (0, utils_1.err)(`Input ${i} is missing a signature.`);
+                }
+                const multisigCheck = this._enforceMultisigThreshold(psbt, i);
+                if (multisigCheck.isErr())
+                    return (0, utils_1.err)(multisigCheck.error.message);
+                let valid = false;
+                try {
+                    valid = psbt.validateSignaturesOfInput(i, utils_1.validatePsbtSignature);
+                }
+                catch (e) {
+                    return (0, utils_1.err)(`Unable to validate the signature for input ${i}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                if (!valid)
+                    return (0, utils_1.err)(`Input ${i} has an invalid signature.`);
+                psbt.finalizeInput(i);
+            }
+            const tx = psbt.extractTransaction();
+            return (0, utils_1.ok)({ txHex: tx.toHex(), txid: tx.getId() });
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    _enforceMultisigThreshold(psbt, i) {
+        const input = psbt.data.inputs[i];
+        const witnessScript = input.witnessScript;
+        if (!witnessScript)
+            return (0, utils_1.ok)('Not a multisig input.');
+        let m;
+        let pubkeys;
+        try {
+            const p2ms = bitcoin.payments.p2ms({ output: witnessScript });
+            m = p2ms.m;
+            pubkeys = p2ms.pubkeys;
+        }
+        catch {
+            return (0, utils_1.ok)('Not a multisig witnessScript.');
+        }
+        if (!m || !pubkeys?.length)
+            return (0, utils_1.ok)('Not a multisig witnessScript.');
+        const p2wsh = bitcoin.payments.p2wsh({
+            redeem: { output: witnessScript }
+        });
+        if (!input.witnessUtxo ||
+            !p2wsh.output ||
+            !input.witnessUtxo.script.equals(p2wsh.output)) {
+            return (0, utils_1.err)(`Input ${i}: witnessScript does not match the witnessUtxo script.`);
+        }
+        const partials = input.partialSig ?? [];
+        for (const ps of partials) {
+            if (!pubkeys.some((pk) => pk.equals(ps.pubkey))) {
+                return (0, utils_1.err)(`Input ${i} carries a signature from a key that is not in the multisig script.`);
+            }
+        }
+        const signedKeys = new Set(partials.map((ps) => ps.pubkey.toString('hex')));
+        const have = signedKeys.size;
+        if (have < m) {
+            return (0, utils_1.err)(`Input ${i} is below the multisig threshold: have ${have} signature(s), need ${m}.`);
+        }
+        if (have > m) {
+            const keep = [];
+            for (const pk of pubkeys) {
+                if (keep.length >= m)
+                    break;
+                const ps = partials.find((p) => p.pubkey.equals(pk));
+                if (ps)
+                    keep.push(ps);
+            }
+            input.partialSig = keep;
+        }
+        return (0, utils_1.ok)('Multisig threshold satisfied.');
+    }
+    signPsbtWithOurKey(psbtBase64) {
+        try {
+            if (!this._root)
+                return (0, utils_1.err)(new utils_1.WatchOnlySigningError());
+            if (!psbtBase64)
+                return (0, utils_1.err)('No PSBT provided.');
+            const network = this.getBitcoinNetwork();
+            const psbt = bitcoin.Psbt.fromBase64(psbtBase64, { network });
+            if (psbt.inputCount === 0)
+                return (0, utils_1.err)('PSBT has no inputs.');
+            let matched = 0;
+            for (let i = 0; i < psbt.inputCount; i++) {
+                const input = psbt.data.inputs[i];
+                if (input.finalScriptSig || input.finalScriptWitness)
+                    continue;
+                for (const derivation of input.bip32Derivation ?? []) {
+                    let keyPair;
+                    try {
+                        keyPair = this._root.derivePath(derivation.path);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!keyPair.publicKey.equals(derivation.pubkey))
+                        continue;
+                    matched++;
+                    const alreadySigned = (input.partialSig ?? []).some((ps) => ps.pubkey.equals(keyPair.publicKey));
+                    if (!alreadySigned)
+                        psbt.signInput(i, keyPair);
+                    break;
+                }
+            }
+            if (matched === 0) {
+                return (0, utils_1.err)('No PSBT input carries a bip32Derivation this wallet can sign for.');
+            }
+            return (0, utils_1.ok)(psbt.toBase64());
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    combinePsbts(psbts) {
+        try {
+            if (!psbts || psbts.length < 2) {
+                return (0, utils_1.err)('Provide at least two PSBTs to combine.');
+            }
+            const network = this.getBitcoinNetwork();
+            const parsed = psbts.map((psbtBase64) => bitcoin.Psbt.fromBase64(psbtBase64, { network }));
+            const [base, ...rest] = parsed;
+            base.combine(...rest);
+            return (0, utils_1.ok)(base.toBase64());
+        }
+        catch (e) {
+            return (0, utils_1.err)(e);
+        }
+    }
+    async broadcastTransaction(txHex) {
+        if (!txHex)
+            return (0, utils_1.err)('No transaction hex provided.');
+        return await this.electrum.broadcastTransaction({
+            rawTx: txHex,
+            subscribeToOutputAddress: false
+        });
+    }
     getAddressFromScriptHash(scriptHash) {
         const addresses = this.data.addresses;
         const changeAddresses = this.data.changeAddresses;
@@ -2436,7 +3189,7 @@ class Wallet {
         await this.saveWalletData('feeEstimates', feeEstimates);
         return (0, utils_1.ok)(feeEstimates);
     }
-    getAddressesFromPrivateKey(privateKey, _addressTypes = (0, shapes_1.getAddressTypes)()) {
+    getAddressesFromPrivateKey(privateKey, _addressTypes = (0, shapes_1.getAddressTypes)().filter((t) => t !== types_1.EAddressType.p2wsh)) {
         try {
             const network = this.getBitcoinNetwork();
             return (0, utils_1.getAddressesFromPrivateKey)({
@@ -2481,6 +3234,10 @@ class Wallet {
         return (0, utils_1.ok)({ balance, utxos, keyPair, addresses });
     }
     async sweepPrivateKey({ privateKey, toAddress, satsPerByte = this.feeEstimates.normal, broadcast = true, combineWithWalletUtxos = false }) {
+        if (this._multisig)
+            return (0, utils_1.err)(new utils_1.MultisigSpendError());
+        if (this.isWatchOnly)
+            return (0, utils_1.err)(new utils_1.WatchOnlySigningError());
         const privateKeyInfo = await this.getPrivateKeyInfo(privateKey);
         if (privateKeyInfo.isErr()) {
             return (0, utils_1.err)(privateKeyInfo.error.message);