# @bitcoinerlab/descriptors 中文文档

规范地址：https://npmcn.com/package/%40bitcoinerlab/descriptors/

版本：3\.2\.1
npm 元数据更新时间：2026-11-05T13:31:51.715Z
中文译文更新时间：2026-11-08T04:11:49.965Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitcoinerlab/descriptors
原文对照：https://npmcn.com/package/%40bitcoinerlab/descriptors/?lang=original
项目主页：https://github.com/bitcoinerlab/descriptors
源码仓库：https://github.com/bitcoinerlab/descriptors

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：92.8 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：5 个
- peer 依赖：@ledgerhq/ledger-bitcoin ^0\.3\.1
- 首次发布：2023-02-24T08:48:48.410Z
- 最新版本发布：2026-11-05T13:31:51.532Z
- 近 30 天下载量：91015（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 19 个）

## 中文简介

此库剖析并创建了 Bitcoin 最小描述符并生成部分签名的 Bitcoin 交易 (PSBTs) 。 它为单签名、BIP32和硬件钱包提供PSBT的定稿和签名人,为libra的比特币家庭捆绑

## 安装

```sh
npm install @bitcoinerlab/descriptors
```

也可以使用：`pnpm add @bitcoinerlab/descriptors`、`yarn add @bitcoinerlab/descriptors`、`bun add @bitcoinerlab/descriptors`

## README

# 比特币描述文件库

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

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

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

## TL; DR (快速启动)

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

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

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

```javascript
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());
```

点击可查看 scure 变体

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

```typescript
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);
```

## 特征

-   解析并创建 [比特币描述符](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) (包括基于 [最小标记语言](https://bitcoinerlab.com/modules/miniscript)) (中文(简体) ).
-   支持带树的标签: `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)_,单击下一节来扩展和阅读这些概念.

概念

### 说明

在比特币(Bitcoin)中,一项交易由一组投入组成,这些投入被花在了不同的一组产出上. 每个输入在前一次交易中花费一个输出. 比特币描述符(英語:Bitcoin description)是一串文字来描述交易中花费一出输出所需的规则和条件.

譬如说, `wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)` 是一种描述方式,它描述的是用指定的公用钥匙向证人支付报酬的公用钥匙。 如果您知道用于此描述符作为输出的交易的相应私钥,您可以使用它.

描述词可以表达更为复杂的条件,如多方合作,有时间限制的产出等等. 这些条件可以用Bitcoin Miniscript语言来表示,这是用有条理和更容易理解的方式来写出Bitcoin脚本的一种方式.

### 部分签名的比特币交易

PSBT(Partially signed Bitcoin Contact)是不同方之间共享比特币交易的一种格式.

PSBT在与描述器合作时有帮助,特别是在使用脚本时,因为它们允许多个方在签名过程中合作. 这在使用需要单独签名或授权的硬件钱包或其他设备时特别有用.

## 使用量

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

此外,我们详细记录了我们的API。 仔细看看班级、职能和类型,头朝上 [这里](https://bitcoinerlab.com/modules/descriptors/api)。 。 。 .

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

比特币的后端 :

```bash
npm install @bitcoinerlab/descriptors
```

斯库尔后端 :

```bash
npm install @bitcoinerlab/descriptors-scure
```

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

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

```bash
npm install @bitcoinerlab/miniscript-policies
```

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

现有 @ bitcoinerlab/ 描述器用户的兼容性注释

词根 `@bitcoinerlab/descriptors` 软件包仍然保留着几个3.x相容的shims,但它们被贬值并计划在下个主要发行时删除:

-   `DescriptorsFactory()` 财务报告和审定财务报表 `DescriptorsFactory(ecc)` 关于根包

对于新代码,倾向于预设的顶级直接输出. `DescriptorsFactory(...)` 打开 `@bitcoinerlab/descriptors` 仅保留3.x后相容性,并计划在下个主要版本,包括自定义中停止作为公共预设包 API `ecc` 初始化路径 .

关于最小端到端的示例,见 [`test/integration/scure.ts`](https://github.com/bitcoinerlab/descriptors/blob/main/test/integration/scure.ts)。 。 。 .

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

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

### 产出类

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

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

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

高级:自定义比特币js-兼容 ecc 执行

大多数用户不需要 `DescriptorsFactory(...)` 直接说 如果 您想要转换默认值 `@bitcoinerlab/secp256k1` 约束另一个 微秒256k1兼容执行.

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

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

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

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

高级支出路径控制(例如 `signersPubKeys`, (中文(简体) ), `taprootSpendPath`,以及 `tapLeaf`,参见 [支出路径选择: 从 WSH 最小标记到磁盘](https://npmcn.com/package/%40bitcoinerlab/descriptors/#readme-spending-path-selection-from-wsh-miniscript-to-taproot)。 。 。 .

关于构造器参数的详细资料可见于 [aPI 文档](https://bitcoinerlab.com/modules/descriptors/api/classes/Output.html#constructor) 内 [此堆栈交换答案](https://bitcoin.stackexchange.com/a/118036/89665)。 。 。 .

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

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

这个 `Output` 类 [提供各种有益的方法](https://bitcoinerlab.com/modules/descriptors/api/classes/Output.html),包括: `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()`,使用下列语法:

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

点击可查看 scure 变体

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

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

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

方法返回 `inputFinalizer()` 函数。 此定稿函数通过添加解锁脚本来完成 PSBT 输入( )`scriptWitness` 或者说 `scriptSig`)满足先前产出支出条件。 记住,两者 `scriptSig` 财务报告和审定财务报表 `scriptWitness` 包含签名。 因此,您应完成所有必要的签名行动,然后拨打 `inputFinalizer()`详细内容 [说明 `inputFinalizer` 方法](https://npmcn.com/package/%40bitcoinerlab/descriptors/#readme-signers-and-finalizers-finalize-psbt-input) 可在“签注”和“最后签注”部分找到.

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

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

欲了解有关使用《公约》的更多信息,请查阅: `Output` 分类,指 [综合指南](https://bitcoinerlab.com/guides) 提供解释和游乐场 帮助学习模块。 关于方法的具体细节,可直接参考: [aPI 地图](https://bitcoinerlab.com/modules/descriptors/api/classes/Output.html)。 。 。 .

#### 以 `expand()`

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

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

const info = expand({ descriptor });
```

关于返回地的全部详情,参见 [aPI 地图](https://bitcoinerlab.com/modules/descriptors/api/types/Expansion.html)。 。 。 .

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

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

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

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

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

```javascript
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)
});
```

点击可查看 scure 变体

```javascript
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` 以及相关时的预想).
    

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

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

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

```javascript
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`,看看这个 [堆栈交换答案](https://bitcoin.stackexchange.com/a/118036/89665)。 。 。 .

### 签字人和决赛

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

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

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

在签署业务时,使用 [`signers`](https://bitcoinerlab.com/modules/descriptors/api/modules/signers.html)数字 :

```javascript
// `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`
```

点击可查看 scure 变体

```javascript
// `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` 方法](https://bitcoinerlab.com/modules/descriptors/api/classes/Output.html#updatePsbtAsInput) 发挥关键的作用。 当援引时 `output.updatePsbtAsInput()` 设置 `psbt` 通过指定输出为输入,并在需要时调整交易锁定时间. 此外,它还返回a `inputFinalizer` 函数针对此特定 `psbt` 输入.

##### 程序

1.  对于您正在参考的上一笔交易的每个未用产出 `psbt` 作为要花费的投入,请拨打 `updatePsbtAsInput` 方法 :
    
    ```javascript
    const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
    ```
    
2.  一旦你完成了必要的签名操作 `psbt`,在每个输入上使用返回的定稿函数:
    
    ```javascript
    inputFinalizer({ psbt });
    ```
    

##### 重要说明

-   完成器函数从 `updatePsbtAsInput` 添加必要的解锁脚本( n)`scriptWitness` 或者说 `scriptSig`满足 `Output`消费条件 记住,两者 `scriptSig` 财务报告和审定财务报表 `scriptWitness` 包含签名。 确保在最后确定之前完成所有必要的签署行动.
    
-   `txHex` 非Segwit 输入需要。 对于 Segwit 输入, API 也 接受 `txId` 财务报告和审定财务报表 `value`,但使用满 `txHex` 强烈建议 用于安全, 因为它让图书馆验证更多以前的 交易和帮助防止费用攻击。 见 [Trezor的解释 硬件钱包为什么需要上一个交易](https://blog.trezor.io/details-of-firmware-updates-for-trezor-one-version-1-9-1-and-trezor-model-t-version-2-3-1-1eba8f60f2dd)。 。 。 . 对于支持的硬件钱包签名,总是通过全 `txHex`,包括: 为塞格维特输入.
    

### 密钥表达式和脚本表达式

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

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

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

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

```javascript
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
})
```

点击可查看 scure 变体

```javascript
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`](https://bitcoinerlab.com/modules/descriptors/api/functions/keyExpressionBIP32.html) bIP32 关键表达式。 其进口情况如下:

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

这些职能所需的参数是:

```javascript
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;
});
```

点击可查看 scure 变体

```javascript
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 键的字符串. 例如:

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

读取 [比特币 核心描述文件](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) 学习更多关于关键表达式.

### 硬件钱包集成

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

| 后端 | 编辑器 | 位框 |
| --- | --- | --- |
| 比特币js | `@bitcoinerlab/descriptors/ledger` | `@bitcoinerlab/descriptors/bitbox` |
| 仓库 | `@bitcoinerlab/descriptors-scure/ledger` | `@bitcoinerlab/descriptors-scure/bitbox` |

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

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

见 [硬件钱包](https://npmcn.com/package/%40bitcoinerlab/descriptors/HARDWARE_WALLETS.md) 设置、政策指南 注册、签名、反应原生支持、设备限制和真设备 测试.

## 额外资源

详情请参见以下资源:

-   **[指南](https://bitcoinerlab.com/guides)**:综合解释和游乐场帮助您学习如何使用模块.
    
-   **[API 密码](https://bitcoinerlab.com/modules/descriptors/api)**: 钻入分类,函数和类型的细节.
    
-   **[堆栈交换答案](https://bitcoin.stackexchange.com/a/118036/89665)**: 重点解释建造者,特别是 `signersPubKeys` 参数和使用 `updatePsbtAsInput`, (中文(简体) ), `getAddress` 财务报告和审定财务报表 `getScriptPubKey`。 。 。 .
    
-   **[融合测试](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration)**: 代表性软件和硬件-wallet流的端到端实例.
    
-   **本地文档**: 从源代码生成全面的 API 文件 :
    
    ```bash
    git clone https://github.com/bitcoinerlab/descriptors
    cd descriptors/
    npm install
    npm run docs
    ```
    
    生成的文件将载于 `docs/` 目录。 打开 `index.html` 查看文档的文件.
    

## 作者和贡献者

该项目最初是开发的,目前由 [何塞-路易斯·兰达巴索](https://github.com/landabaso)欢迎其他开发者的贡献和帮助.

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

### 从源头建楼

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

1.  清除仓库 :

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

2.  安装依赖性 :

```bash
npm install
```

3.  构建工程 :

```bash
npm run build
```

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

### 测试

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

运行单元测试 :

```bash
npm run test:unit
```

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

```bash
npm run test
```

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

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

### 许可证

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

## 常见问题

### @bitcoinerlab/descriptors 是什么？

此库剖析并创建了 Bitcoin 最小描述符并生成部分签名的 Bitcoin 交易 \(PSBTs\) 。 它为单签名、BIP32和硬件钱包提供PSBT的定稿和签名人,为libra的比特币家庭捆绑

### 如何安装 @bitcoinerlab/descriptors？

在项目目录运行 npm install @bitcoinerlab/descriptors，或使用 pnpm add / yarn add / bun add。

### @bitcoinerlab/descriptors 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitcoinerlab/descriptors 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bitcoinerlab/descriptors 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bitcoinerlab/descriptors 可以商用吗？

@bitcoinerlab/descriptors 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitcoinerlab/descriptors 的下载量有多少？

根据 npm 官方下载统计，@bitcoinerlab/descriptors 在 2026/10/08 – 2026/11/06 这 30 天内被下载 91,015 次，日均约 3,034 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitcoinerlab/descriptors 还在维护吗？

最新版本 3\.2\.1 发布于 2026/11/05（2 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 19 个；首次发布于 2023/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。