比特币描述文件库

这个库旨在解析并创建比特币描述符,包括Miniscript和Taproot脚本树并生成部分已签名的比特币交易(PSBTs). 它还为单键,BIP32和硬件-wallet流提供PSBT的签注和定稿.

这个库使用一个基础的比特币库来创建,签名并解码交易. 用户可以选择 :

• @bitcoinerlab/descriptors 联 合 国 比特币js-lib 财务报告和审定财务报表 比特币js 图书馆家族:经过战斗测试并广泛使用.
• @bitcoinerlab/descriptors-scure 页:1 @ scure/btc- signer 编辑 贵族编号 :缝制 图书馆:审计、快速和最少.
• @bitcoinerlab/descriptors-core 作为预设软件包下使用的低级软件包。 大多数用户应该将其作为内部处理,但高级用户需要明确控制后端设置时可以直接使用.

TL; DR (快速启动)

使用 @bitcoinerlab/descriptors-scure见下面的scure变体.

npm install @bitcoinerlab/descriptors @bitcoinerlab/miniscript-policies

这个快例汇编了一个被时间锁起的Miniscript 策略,创建了一个描述器地址来资助,然后构建,签名,最后敲定一个用于资助UTXO的PSBT,并打印最终交易十六进制.

import { ECPair, Output, Psbt, signers } from '@bitcoinerlab/descriptors'; // bitcoinjs-ready package

const ecpair = ECPair.makeRandom(); // Creates a signer for a single-key wallet

// Timelocked policy: signature + relative timelock (older)
const { miniscript } = compilePolicy('and(pk(@bob),older(10))');

const descriptor = `wsh(${miniscript.replace('@bob', toHex(ecpair.publicKey))})`;

// 1) Build the output description
const fundedOutput = new Output({ descriptor });
const address = fundedOutput.getAddress(); // Fund this address

// 2) Prepare PSBT input/output
const psbt = new Psbt();

const txHex = 'FUNDING_TX_HEX'; // hex of the tx that funded the address above
const vout = 0; // Output index (vout) of that UTXO within FUNDING_TX_HEX
const finalizeInput = fundedOutput.updatePsbtAsInput({ psbt, txHex, vout });

const recipient = new Output({
  descriptor: 'addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)'
}); // Final address where we'll send the funds after timelock
recipient.updatePsbtAsOutput({ psbt, value: 10000n }); // input covers this+fees

// 3) Sign and finalize
signers.signECPair({ psbt, ecpair });
finalizeInput({ psbt });

console.log('Push this: ' + psbt.extractTransaction().toHex());

npm install @bitcoinerlab/descriptors-scure @bitcoinerlab/miniscript-policies

import { Output, btc, secp256k1, signers } from '@bitcoinerlab/descriptors-scure';

const privKey = btc.utils.randomPrivateKeyBytes();
const pubkey = secp256k1.getPublicKey(privKey, true);

// Timelocked policy: signature + relative timelock (older)
const { miniscript } = compilePolicy('and(pk(@bob),older(10))');

const descriptor = `wsh(${miniscript.replace('@bob', toHex(pubkey))})`;

// 1) Build the output description
const fundedOutput = new Output({ descriptor });
const address = fundedOutput.getAddress(); // Fund this address

// 2) Prepare transaction input/output
const psbt = new btc.Transaction();

const txHex = 'FUNDING_TX_HEX'; // hex of the tx that funded the address above
const vout = 0; // Output index (vout) of that UTXO within FUNDING_TX_HEX
const finalizeInput = fundedOutput.updatePsbtAsInput({ psbt, txHex, vout });

const recipient = new Output({
  descriptor: 'addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)'
});
recipient.updatePsbtAsOutput({ psbt, value: 10000n }); // input covers this+fees

// 3) Sign and finalize
signers.signPrivKey({ psbt, privKey });
finalizeInput({ psbt });

console.log('Push this: ' + psbt.hex);

特征

• 解析并创建 比特币描述符 (包括基于 最小标记语言) (中文(简体) ).
• 支持带树的标签: tr(KEY,TREE) (标注).
• 生成部分签名的比特币交易(PSBT).
• 为单签名,BIP32和硬件-wallet流提供PSBT的定稿和签名.
• 为比特币和斯库尔提供可选的Ledger和BitBox集成.

版本兼容性

开始于 3.x, (中文(简体) ), @bitcoinerlab/descriptors 与现代比特币堆栈对齐(bitcoinjs-lib 7.x) (中文(简体) ).

实际上,这意味着:

• 字节数组表示为 Uint8Array· ;
• satoshi 值为 bigint。 。 。 .

如果你需要更古老的比特币版本,请继续使用 @bitcoinerlab/descriptors 2.x。 。 。 . 如果你想要磁带树tr(KEY,TREE)),使用时 3.x+。 。 。 .

开始于 3.1.x,scure 用户可以安装 @bitcoinerlab/descriptors-scure。 。 。 .

版本 3.2.0 需要节点.js >=20.19.0。 。 。 .

概念

这个库主要有两种能力与比特币描述符有关. 首先,它可以产生 addresses 财务报告和审定财务报表 scriptPubKeys 从描述。 这些 addresses 财务报告和审定财务报表 scriptPubKeys 可用于接受其他方面的资金。 第二,图书馆能够签署交易,并使用这些说明所描述的未用产出。 为了做到这一点,必须首先将描述符设定为PSBT.

如果你不熟悉的话 比特币描述符 财务报告和审定财务报表 部分签名的比特币交易( PSBTs),单击下一节来扩展和阅读这些概念.

使用量

在潜入之前,值得一提的是,我们有几种综合指南,涵盖图书馆的不同方面. 这些指南在交互式游乐场中提供解释和代码示例,允许您在修改代码时看到输出的变化. 这种亲身体验,加上清晰的解释,帮助你更好地理解如何有效地使用图书馆. 检查这里可用的指南。 。 。 .

此外,我们详细记录了我们的API。 仔细看看班级、职能和类型,头朝上 这里。 。 。 .

对于大多数用户,安装与您喜欢的比特币库相匹配的软件包.

比特币的后端 :

npm install @bitcoinerlab/descriptors

斯库尔后端 :

npm install @bitcoinerlab/descriptors-scure

选择应用程序的后端 。 将两个预设软件包一起装入 不支持, 因为现有的输出和 PSBT 必须继续使用后端 这创造了他们。 如果两者都需要,请在不同的过程中将它们隔离,或 工人们.

如果您计划在应用程序中将策略字符串编译为Miniscript,请同时安装:

npm install @bitcoinerlab/miniscript-policies

下面的例子默认保留比特币的堆栈可见. 何时 后端特定代码不同,可折叠的 scure 变体显示为右 见下文.

关于最小端到端的示例,见 test/integration/scure.ts。 。 。 .

该图书馆可分为四个主要部分:

• 这个 Output 分类是管理描述符的核心组成部分。 它有利于创造获得资金的产出,并能够签署和最终确定用于支出UTXOs(未用交易产出)的PSBT(部分已签署的比特币交易).
• PSBT的签名人和定稿人,用于管理PSBT的签署和定稿.
• keyExpressions 财务报告和审定财务报表 scriptExpressions,它提供了从结构化数据创建密钥和标准描述符表达式(字符串)的函数.
• 硬件钱包集成,在下方的自有部分覆盖.

产出类

用于正常使用,导入 Output 直接取自您选择的预设软件包 .

import { Output } from '@bitcoinerlab/descriptors'; // bitcoinjs-ready package

import { Output } from '@bitcoinerlab/descriptors-scure'; // scure-ready package

import * as ecc from '@bitcoinerlab/secp256k1'; // or another tiny-secp256k1-compatible implementation
import {
  DescriptorsFactory,
  createBitcoinjsLib
} from '@bitcoinerlab/descriptors';

const { Output } = DescriptorsFactory(createBitcoinjsLib(ecc));

设置后,您可以得到一个输出的示例,由描述器描述,如 wpkh,内容如下:

const wpkhOutput = new Output({
  descriptor:
    'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
});

高级支出路径控制(例如 signersPubKeys, (中文(简体) ), taprootSpendPath,以及 tapLeaf,参见 支出路径选择: 从 WSH 最小标记到磁盘。 。 。 .

关于构造器参数的详细资料可见于 aPI 文档 内 此堆栈交换答案。 。 。 .

一些常用的构造器参数有:

• index: 对于结束于 *。 。 。 .
• change:用于多路径密钥表达式,例如 /** 或者说 /<0;1>/*。例如,在 /<0;1>/*,使用时 change: 0 或者说 change: 1。 。 。 .

这个 Output 类 提供各种有益的方法,包括: getAddress(),返回与描述符相关的地址, getScriptPubKey(),返回 scriptPubKey 为描述者, expand()将描述器分解成元素部分, updatePsbtAsInput() 财务报告和审定财务报表 updatePsbtAsOutput()。 。 。 .

图书馆支持多种描述类型,包括:

• 公交-Key-Hash(P2PKH): pkh(KEY)
• 付-付-公-克-哈什(P2WPKH): wpkh(KEY)
• 对脚本- Hash( P2SH) : sh(SCRIPT)
• 给-Witness-脚本-Hash(P2WSH): wsh(SCRIPT)
• Pay- to- Taproot (P2TR) 有只按键或脚本树 : tr(KEY) 财务报告和审定财务报表 tr(KEY,TREE)
• 基于地址的描述符: addr(ADDRESS)

这些描述符可用于各种关键表达式,包括原始公钥,BIP32衍生道等.

例如,有脚本叶的Tapproot描述符可以看起来像:

tr(INTERNAL_KEY,{pk(KEY_A),{pk(KEY_B),and_v(v:pk(KEY_C),older(144))}})

这意味着输出在树内有一个内键花路径和额外的脚本路径选项.

这个 updatePsbtAsInput() 方法是库中一个必不可少的部分,负责向描述符描述的UTXO对应的PSBT添加一个输入. 此外,当描述符表示绝对时间耗用条件时,如"这个UTXO只能在N区块后使用", updatePsbtAsInput() 向 PSBT 添加时钟信息 .

打电话 updatePsbtAsInput(),使用下列语法:

import { Psbt } from '@bitcoinerlab/descriptors';
const psbt = new Psbt();
const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout, rbf });

import { btc } from '@bitcoinerlab/descriptors-scure';

const psbt = new btc.Transaction();
const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout, rbf });

这里, psbt 指一个 比特币js-lib Psbt 类 实例或实例 @scure/btc-signer Transaction,取决于您选择的后端。 参数 txHex 表示将包含此输出的上一个交易序列化的十六进制字符串 。 同时, vout 是表示该交易中输出位置的整数。 终于, rbf 是可选参数( 默认为 true)用于表示交易是否使用"替换-By-Fee"(RBF). 当RBF被启用时,交易可以在与其它收费较高的人混居时被替换. 注意, 如果至少有一个输入信号, 整个交易都会启用 RBF 。 还请注意,由于 nSequence 使用范围.

方法返回 inputFinalizer() 函数。 此定稿函数通过添加解锁脚本来完成 PSBT 输入( )scriptWitness 或者说 scriptSig)满足先前产出支出条件。 记住,两者 scriptSig 财务报告和审定财务报表 scriptWitness 包含签名。 因此,您应完成所有必要的签名行动,然后拨打 inputFinalizer()详细内容 说明 inputFinalizer 方法 可在“签注”和“最后签注”部分找到.

同样, updatePsbtAsOutput 允许您在 PSBT 中添加输出。 例如,要配置一个 psbt 发送 10,000 坐到 SegWit 地址 bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x数字 :

const recipientOutput = new Output({
  descriptor: `addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)`
});
recipientOutput.updatePsbtAsOutput({ psbt, value: 10000n });

欲了解有关使用《公约》的更多信息,请查阅: Output 分类,指 综合指南 提供解释和游乐场 帮助学习模块。 关于方法的具体细节,可直接参考: aPI 地图。 。 。 .

以 expand()

大多数应用程序不需要 expand() 用于正常的收/支流动。 它主要用于调试和回溯(例如检查扩展表达式,密钥映射,脚本,和解析后元数据).

import { expand } from '@bitcoinerlab/descriptors'; // or '@bitcoinerlab/descriptors-scure' for scure

const info = expand({ descriptor });

关于返回地的全部详情,参见 aPI 地图。 。 。 .

支出路径选择: 从 WSH 最小标记到磁盘

当描述器有不止一种有效的使用方式时,库需要知道您打算使用的路径.

对于 wsh(miniscript) 财务报告和审定财务报表 sh(wsh(miniscript)),通常使用 signersPubKeys:您通过预期要签名的公钥,而库会选择最理想的可选择分支.

signersPubKeys 以公钥数组形式传递(Uint8Array[]) (中文(简体) ). 如果省略,库假定所有描述键可以签名.

示例有两个BIP32衍生的密钥和一个首选的签名符:

import { randomBytes } from 'crypto';
import { BIP32, Output, keyExpressionBIP32 } from '@bitcoinerlab/descriptors';

const masterNode = BIP32.fromSeed(randomBytes(32));

const originPath = "/84'/0'/0'";

const keyPathA = '/0/0';
const keyPathB = '/0/1';

const keyExprA = keyExpressionBIP32({ masterNode, originPath, keyPath: keyPathA });
const keyExprB = keyExpressionBIP32({ masterNode, originPath, keyPath: keyPathB });

const signerPubKeyA = masterNode.derivePath(`m${originPath}${keyPathA}`).publicKey;

// Two possible branches:
// - branch 1: signature by keyA + older(10)
// - branch 2: signature by keyB (no timelock)
const output = new Output({
  descriptor: `wsh(andor(pk(${keyExprA}),older(10),pk(${keyExprB})))`,
  signersPubKeys: [signerPubKeyA] // choose the keyA (timelock branch)
});

import { randomBytes } from '@noble/hashes/utils.js';
import { HDKey, Output, keyExpressionBIP32 } from '@bitcoinerlab/descriptors-scure';

const masterNode = HDKey.fromMasterSeed(randomBytes(32));

const originPath = "/84'/0'/0'";

const keyPathA = '/0/0';
const keyPathB = '/0/1';

const keyExprA = keyExpressionBIP32({ masterNode, originPath, keyPath: keyPathA });
const keyExprB = keyExpressionBIP32({ masterNode, originPath, keyPath: keyPathB });

const signerPubKeyA = masterNode.derive(`m${originPath}${keyPathA}`).publicKey;

const output = new Output({
  descriptor: `wsh(andor(pk(${keyExprA}),older(10),pk(${keyExprB})))`,
  signersPubKeys: [signerPubKeyA]
});

龙卷风也用同样的主意 对于 tr(KEY,TREE), (中文(简体) ), signersPubKeys 帮助确定哪片叶子是可调适的,哪条可调适的路径更理想. 此外,Taproot还提供了两个可选的控制:

• taprootSpendPath (单位:千美元)'key' | 'script'强迫按键路径或脚本路径支出.

• tapLeaf 在使用脚本路径时强制使用特定的脚本叶.

  若为 taprootSpendPath 省略 tr(KEY,TREE),库使用脚本路径,并自动从可用的支出数据(包括 signersPubKeys 以及相关时的预想).

如果您专门计划从内部键中支出,请设定:

new Output({
  descriptor: 'tr(INTERNAL_KEY,{pk(KEY_A),pk(KEY_B)})',
  taprootSpendPath: 'key'
});

如果您想要强制特定脚本叶 :

new Output({
  descriptor: 'tr(INTERNAL_KEY,{pk(KEY_A),pk(KEY_B)})',
  taprootSpendPath: 'script',
  tapLeaf: 'pk(KEY_A)'
});

这些支出路径参数(A/CONF.96/11)signersPubKeys, (中文(简体) ), taprootSpendPath, (中文(简体) ), tapLeaf) 只有在使用/最后确定具有多条候选路径的UTXO时才需要。 并非仅仅为了找到地址或 scriptPubKeys。 。 。 .

为有重点地走过建筑商的选择(包括: signersPubKeys)和实用 updatePsbtAsInput, (中文(简体) ), getAddress 财务报告和审定财务报表 getScriptPubKey,看看这个 堆栈交换答案。 。 。 .

签字人和决赛

这个库包含一个PSBT定稿器以及单键和BIP32流量的签名助手. 设备后置签名使用相同的PSBT模式,但设备设置是分开的.

为纳入这些功能,使用以下导入语句:

import { signers } from '@bitcoinerlab/descriptors'; // or '@bitcoinerlab/descriptors-scure' for scure

在签署业务时,使用 signers数字 :

// `psbt` here is a bitcoinjs-lib `Psbt` (for example: `const psbt = new Psbt()`)

// For BIP32 - https://github.com/bitcoinjs/bip32
signers.signBIP32({ psbt, masterNode }); // Here, `masterNode` is a bitcoinjs `BIP32Interface` (see examples above)

// For ECPair - https://github.com/bitcoinjs/ecpair
signers.signECPair({ psbt, ecpair }); // Here, `ecpair` is a bitcoinjs `ECPairInterface`

// `psbt` here is an `@scure/btc-signer` `Transaction`
// (for example: `const psbt = new btc.Transaction()`)

// For BIP32 with @scure/bip32
signers.signBIP32({ psbt, masterNode }); // Here, `masterNode` is an `HDKey` (see examples above)

// For raw private keys
signers.signPrivKey({ psbt, privKey }); // Here, `privKey` is a 32-byte `Uint8Array`
signers.signInputPrivKey({ psbt, index: 0, privKey }); // Same `privKey` type as above

硬件-wallet签名器在设备会话创建后遵循相同的模式.

最后确定 psbt

在最后确定 psbt,则 updatePsbtAsInput 方法 发挥关键的作用。 当援引时 output.updatePsbtAsInput() 设置 psbt 通过指定输出为输入,并在需要时调整交易锁定时间. 此外,它还返回a inputFinalizer 函数针对此特定 psbt 输入.

程序

1. 对于您正在参考的上一笔交易的每个未用产出 psbt 作为要花费的投入,请拨打 updatePsbtAsInput 方法 :

   const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
   

2. 一旦你完成了必要的签名操作 psbt,在每个输入上使用返回的定稿函数:

   inputFinalizer({ psbt });
   

重要说明

• 完成器函数从 updatePsbtAsInput 添加必要的解锁脚本( n)scriptWitness 或者说 scriptSig满足 Output消费条件 记住,两者 scriptSig 财务报告和审定财务报表 scriptWitness 包含签名。 确保在最后确定之前完成所有必要的签署行动.

• txHex 非Segwit 输入需要。 对于 Segwit 输入, API 也 接受 txId 财务报告和审定财务报表 value,但使用满 txHex 强烈建议 用于安全, 因为它让图书馆验证更多以前的 交易和帮助防止费用攻击。 见 Trezor的解释 硬件钱包为什么需要上一个交易。 。 。 . 对于支持的硬件钱包签名,总是通过全 txHex,包括: 为塞格维特输入.

密钥表达式和脚本表达式

这个库还提供一系列功能助手,旨在简化生成 descriptor 字符串。 这些字符串可以作为输入参数 Output 阶级建筑师. 这些帮手被困在 scriptExpressions 模块。 您可以导入如下:

import { scriptExpressions } from '@bitcoinerlab/descriptors'; // or '@bitcoinerlab/descriptors-scure' for scure

根内 scriptExpressions 模块,有为常用的 BIP32 脚本生成描述符的功能,例如 pkhBIP32(), (中文(简体) ), shWpkhBIP32() 财务报告和审定财务报表 wpkhBIP32()。参见 aPI 地图 详细清单和进一步资料.

在使用基于BIP32的描述符时,需要以下参数来表示: scriptExpressions 函数:

pkhBIP32(params: {
  masterNode: BIP32Interface; //bitcoinjs-lib BIP32 - https://github.com/bitcoinjs/bip32
  network?: Network; //A bitcoinjs-lib network
  account: number;
  change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
  index?: number | undefined | '*';
  keyPath?: string; //You can use change & index or a keyPath such as "/0/0"
  isPublic?: boolean; //Whether to use xpub or xprv
})

pkhBIP32(params: {
  masterNode: HDKey; // @scure/bip32 - https://github.com/paulmillr/scure-bip32
  network?: Network;
  account: number;
  change?: number | undefined;
  index?: number | undefined | '*';
  keyPath?: string;
  isPublic?: boolean;
})

这个 keyExpressions 类别包括生成对公钥关键表达式的字符串表示的函数.

该图书馆包括: keyExpressionBIP32 bIP32 关键表达式。 其进口情况如下:

import { keyExpressionBIP32 } from '@bitcoinerlab/descriptors'; // or '@bitcoinerlab/descriptors-scure' for scure

这些职能所需的参数是:

function keyExpressionBIP32({
  masterNode: BIP32Interface; //bitcoinjs-lib BIP32 - https://github.com/bitcoinjs/bip32
  originPath: string;
  change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
  index?: number | undefined | '*';
  keyPath?: string | undefined;
  isPublic?: boolean;
});

function keyExpressionBIP32({
  masterNode: HDKey; // @scure/bip32 - https://github.com/paulmillr/scure-bip32
  originPath: string;
  change?: number | undefined;
  index?: number | undefined | '*';
  keyPath?: string | undefined;
  isPublic?: boolean;
});

此函数生成充分定义 BIP32 键的字符串. 例如:

[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*

读取 比特币 核心描述文件 学习更多关于关键表达式.

硬件钱包集成

Ledger 和 BitBox 支持通过单独的切入点提供 :

应用程序只导入它们使用的设备支持, 所以未使用的硬件钱包 代码和供应商包不装入主包.

connect(...) 返回 a Session 拥有设备连接。 传过去 会话到硬件-Wallet操作,完成后关闭。 坚持下去 JSON安全系统 Store,而不是实时会话,所以缓存密钥和政策信息 可以在重新连接后重新使用.

见 硬件钱包 设置、政策指南 注册、签名、反应原生支持、设备限制和真设备 测试.

额外资源

详情请参见以下资源:

• 指南:综合解释和游乐场帮助您学习如何使用模块.

• API 密码: 钻入分类,函数和类型的细节.

• 堆栈交换答案: 重点解释建造者,特别是 signersPubKeys 参数和使用 updatePsbtAsInput, (中文(简体) ), getAddress 财务报告和审定财务报表 getScriptPubKey。 。 。 .

• 融合测试: 代表性软件和硬件-wallet流的端到端实例.

• 本地文档: 从源代码生成全面的 API 文件 :

  git clone https://github.com/bitcoinerlab/descriptors
  cd descriptors/
  npm install
  npm run docs
  

  生成的文件将载于 docs/ 目录。 打开 index.html 查看文档的文件.

作者和贡献者

该项目最初是开发的,目前由 何塞-路易斯·兰达巴索欢迎其他开发者的贡献和帮助.

以下是一些帮助您开始捐款的资源:

从源头建楼

要下载源代码并构建项目,请遵循这些步骤:

1. 清除仓库 :

git clone https://github.com/bitcoinerlab/descriptors.git

2. 安装依赖性 :

npm install

3. 构建工程 :

npm run build

这将构建工程并生成必要的文件 dist 目录.

测试

在实施任何代码之前,确保它通过所有测试.

运行单元测试 :

npm run test:unit

运行全试验管(林特+建设+单位+集成):

npm run test

融合测试需要多克. 确保 docker 命令在您的 PATH 中安装并可用。 当集成测试运行时,它们会自动启动或再利用本地容器,并配有此寄存器所需的再测试服务.

硬件-Wallet测试需要真正的设备,不是正常测试的一部分 输油管。 运行 npm run test:ledger 或者说 npm run test:bitbox 手动设备 检查。 两个命令先运行并构建,然后测试比特币和 斯克后卫.

许可证

这个项目根据麻省理工学院的许可证获得许可.