@bitcoinerlab/descriptors 0.2.0

package/README.draft.md

@@ -0,0 +1,84 @@
+A JavaScript library for parsing and signing Bitcoin descriptors, including those based on the Miniscript language.
+
+Key features:
+It allows signing using Hierarchical Deterministic keeps (those that use word mnemonics) and also Hardware Wallets (the Ledger wallet so far; more are comming).
+It integrates miniscript, making it super easy to program advanced transactions. For example, timelock-based vaults, multisigs vaults or inheritance are now a breeze.
+Dessigned to be used with psbt (Partially Signed Bitcion transactions) so that it can be used in mkuti-party scenarios.
+Can be used with Typescript and Javascript.
+Integrates with the bitcoinjs-lib family of modules.
+
+Usage:
+
+Installation:
+npm install @bitcoinerlab/descriptors
+
+Usage:
+
+This section describes how to use this library, starting from a very easy transaction and ends up using a smart contract that only allows spending a transaction after a certain time, providing a certain secret (a preimage) and can only be unlocked by co-signing with a Ledger wallet and a Software Wallet.
+
+We will show examples that have been run on the testnet network. We share the mnemonic we used so that you can replicate the transactions: . You won't be able to spend the transactions again but you will be able to replicate everything.
+
+```
+MNEMONIC: "drum turtle globe inherit autumn flavor slice illness sniff distance carbon elder"
+```
+
+TIP: you can use https://iancoleman.io/bip39/ to verify some of the steps below.
+
+Simple case using standard transactions:
+
+Let's start with an easy case. Let's send some sats from a Bitcoin Legacy address to a Segwit one.
+
+We are ready to use the library. Here we skip all initialization. You will be able to see the complete code on a shared repository with the tests.
+
+Examples are written using Javascript. If you want to use Typescript (recommended), please take a look to the test/integration folder for some advanced use use cases.
+Please, note that the code below is just for explanation purposes. When writting code for production you must assert all intermediate steps.
+
+```javascript
+//NETWORK is set to testnet
+const masterNode = BIP32.fromSeed(mnemonicToSeedSync(MNEMONIC), NETWORK);
+const descriptorLegacy = pkhBIP32({ masterNode, network: NETWORK, account: 0, change: 0, index: 1 });
+
+console.log(descriptorLegacy.getAddress()); //moovc1JqGrz4v6FA2U8ks8ZqjSwjv3yRKQ
+```
+
+So we sent some sats (`1679037`) to that address above. Those sats were sent in `TX_ID = "ee02b5a12c2f22e892bed376781fc9ed435f0d192a1b67ca47a7190804d8e868"`. [See it here](https://blockstream.info/testnet/tx/ee02b5a12c2f22e892bed376781fc9ed435f0d192a1b67ca47a7190804d8e868).
+
+Now let's spend them. We will send all the funds, except for a fee to our first internal address (change 1) in account 0 of the P2WPKH (Segwit) wallet:
+
+<!--https://coinfaucet.eu/en/btc-testnet/-->
+
+```javascript
+const TX_ID = "ee02b5a12c2f22e892bed376781fc9ed435f0d192a1b67ca47a7190804d8e868";
+const FEE = 100;
+
+//Define the Segwit descriptor where we will receive the sats:
+const descriptorSegwit = wpkhBIP32({ masterNode, network: NETWORK, account: 0, change: 1, index: 0 });
+
+//Get some info from the network about the Legacy utxo we will spend from:
+const txHex = await (await fetch(`https://blockstream.info/testnet/api/tx/${TX_ID}/hex`)).text();
+const txOuts = (await (await fetch(`https://blockstream.info/testnet/api/tx/${TX_ID}`)).json()).vout;
+const vout = txOuts.findIndex(txOut => txOut.scriptpubkey === descriptorLegacy.getScriptPubKey());
+const initialValue = txOut[vout].value; //1679037, as mentioned above
+
+//Create a transaction (Partially Signed Bitcoin Transaction) now:
+const psbt = new Psbt({network: NETWORK});
+//Update the transaction with the Legacy descriptor input:
+const legacyInputNumber = descriptorLegacy.updatePsbt({ psbt, vout, txHex });
+//Now add the Segwit address as the new output. Let's give some FEE to the miners
+psbt.addOutput({ address: descriptorSegwit.getAddress(), value: initialValue - FEE});
+
+//Sign the transaction, finalize it and submit it to the miners:
+signBIP32({ psbt, masterNode });
+descriptorLegacy.finalizePsbtInput({psbt, index: legacyInputNumber});
+const spendTx = psbt.extractTransaction();
+console.log(spendTx.getId()); //
+await fetch('https://blockstream.info/testnet/api/tx', {
+  method: 'POST',
+  body: spendTx.toHex()
+});
+```
+We have sent the 1679037 - 100 to ourselves in just a few lines.
+Easy! See the tx here: ....
+This has only started. Let's do really cool stuff now.
+
+

package/README.md

@@ -0,0 +1,74 @@
+## Bitcoin Descriptors Library *Pre Release*
+
+This library is designed to parse and create Bitcoin Descriptors, including Miniscript, and generate Partially Signed Bitcoin Transactions (PSBTs). It also provides PSBT finalizers and signers for single-signature, BIP32, and Hardware Wallets.
+
+**NOTE: This is a pre-release version only.** The Usage documentation is still being finalized. However, you can take a look at the [integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration) for some examples of how to use this library.
+
+### Features
+
+- Parses and creates Bitcoin Descriptors (including those based on the Miniscript language).
+- Generates Partially Signed Bitcoin Transactions (PSBTs).
+- Provides PSBT finalizers and signers for single-signature, BIP32, and Hardware Wallets (currently supports Ledger devices; more devices are planned).
+
+### Usage
+
+Usage instructions will be added to this README as soon as they are finalized. In the meantime, please refer to the [integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration) for some examples of how to use this library.
+
+## Authors and Contributors
+
+The project was initially developed and is currently maintained by [Jose-Luis Landabaso](https://github.com/landabaso). Contributions and help from other developers are welcome.
+
+Here are some resources to help you get started with contributing:
+
+### Building from source
+
+To download the source code and build the project, follow these steps:
+
+1. Clone the repository:
+
+```
+git clone https://github.com/bitcoinerlab/descriptors.git
+```
+
+2. Install the dependencies:
+
+```
+npm install
+```
+
+3. Build the project:
+
+```
+npm run build
+```
+
+This will build the project and generate the necessary files in the `dist` directory.
+
+### Testing
+
+
+Before committing any code, make sure it passes all tests. First, make sure that you have a Bitcoin regtest node running and that you have set up the Express-based bitcoind manager from this repository: https://github.com/bitcoinjs/regtest-server. The manager should be running on 127.0.0.1:8080.
+
+The easiest way to set up these services is to use a Docker image that comes preconfigured with them. You can use the following commands to download and run the Docker image:
+
+```bash
+docker pull junderw/bitcoinjs-regtest-server
+docker run -d -p 127.0.0.1:8080:8080 junderw/bitcoinjs-regtest-server
+```
+
+This will start a container running a Bitcoin regtest node and the bitcoind manager on your machine. Once you have your node and manager set up, you can run the tests using the following command:
+
+```
+npm run test
+```
+
+And, in case you have a Ledger device:
+
+```
+npm run test:integration:ledger
+```
+
+### License
+
+This project is licensed under the MIT License.
+

package/dist/checksum.d.ts

@@ -0,0 +1,2 @@
+export declare const CHECKSUM_CHARSET: string;
+export declare const DescriptorChecksum: (span: string) => string;

package/dist/checksum.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DescriptorChecksum = exports.CHECKSUM_CHARSET = void 0;
+// Converted to Javascript by Jose-Luis Landabaso, 2023 - https://bitcoinerlab.com
+// Source: https://github.com/bitcoin/bitcoin/blob/master/src/script/descriptor.cpp
+// Distributed under the MIT software license
+const PolyMod = (c, val) => {
+    const c0 = c >> 35n;
+    c = ((c & 0x7ffffffffn) << 5n) ^ val;
+    if (c0 & 1n)
+        c ^= 0xf5dee51989n;
+    if (c0 & 2n)
+        c ^= 0xa9fdca3312n;
+    if (c0 & 4n)
+        c ^= 0x1bab10e32dn;
+    if (c0 & 8n)
+        c ^= 0x3706b1677an;
+    if (c0 & 16n)
+        c ^= 0x644d626ffdn;
+    return c;
+};
+exports.CHECKSUM_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const DescriptorChecksum = (span) => {
+    const INPUT_CHARSET = '0123456789()[],\'/*abcdefgh@:$%{}IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~ijklmnopqrstuvwxyzABCDEFGH`#"\\ ';
+    let c = 1n;
+    let cls = 0n;
+    let clscount = 0n;
+    for (const ch of span) {
+        const pos = BigInt(INPUT_CHARSET.indexOf(ch));
+        if (pos === -1n)
+            return '';
+        c = PolyMod(c, pos & 31n);
+        cls = cls * 3n + (pos >> 5n);
+        if (++clscount === 3n) {
+            c = PolyMod(c, cls);
+            cls = 0n;
+            clscount = 0n;
+        }
+    }
+    if (clscount > 0n)
+        c = PolyMod(c, cls);
+    for (let j = 0; j < 8; ++j)
+        c = PolyMod(c, 0n);
+    c ^= 1n;
+    let ret = '';
+    for (let j = 0; j < 8; ++j) {
+        const index = (c >> (5n * (7n - BigInt(j)))) & 31n;
+        if (index < 0 || index > Number.MAX_SAFE_INTEGER)
+            throw new Error(`Error: could not compute checksum, invalid index ${index}`);
+        ret += exports.CHECKSUM_CHARSET[Number(index)];
+    }
+    return ret;
+};
+exports.DescriptorChecksum = DescriptorChecksum;

package/dist/descriptors.d.ts

@@ -0,0 +1,15 @@
+import { BIP32API } from 'bip32';
+import { ECPairAPI } from 'ecpair';
+import type { TinySecp256k1Interface, ParseKeyExpression, DescriptorInterfaceConstructor } from './types';
+/**
+ * Builds the functions needed to operate with descriptors using an external elliptic curve (ecc) library.
+ * @param {Object} ecc - an object containing elliptic curve operations, such as [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1) or [@bitcoinerlab/secp256k1](https://github.com/bitcoinerlab/secp256k1).
+ * @returns {Object} an object containing functions, `parse` and `checksum`.
+ * @namespace
+ */
+export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
+    Descriptor: DescriptorInterfaceConstructor;
+    ECPair: ECPairAPI;
+    parseKeyExpression: ParseKeyExpression;
+    BIP32: BIP32API;
+};