# @caravan/bitcoin 中文文档

规范地址：https://npmcn.com/package/%40caravan/bitcoin/

版本：0\.4\.7
npm 元数据更新时间：2026-10-31T18:20:18.420Z
中文译文更新时间：2026-11-09T05:34:23.575Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：840 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：11 个
- 首次发布：2024-02-13T03:43:15.437Z
- 最新版本发布：2026-10-31T18:20:18.117Z
- 近 30 天下载量：6552（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 6 个）

## 中文简介

无链首都比特币公用事业图书馆.

## 安装

```sh
npm install @caravan/bitcoin
```

也可以使用：`pnpm add @caravan/bitcoin`、`yarn add @caravan/bitcoin`、`bun add @caravan/bitcoin`

## README

# 无链资本比特币公用事业

[![Build Status](https://travis-ci.com/unchained-capital/@caravan/bitcoin.svg?branch=master)](https://travis-ci.com/unchained-capital/@caravan/bitcoin)

这个图书馆以优秀的 [比特币js-lib](https://github.com/bitcoinjs/bitcoinjs-lib),添加 用于验证、 HD 钱包、 块的有价值但缺失的功能 探险家,特别是多西格.

完整的 API 文档可见于 [@ caravan/ 比特币](https://unchained-capital.github.io/@caravan/bitcoin)。 。 。 .

这间图书馆是建造和维护的 [无链 资本](https://www.unchained-capital.com/)。 。 。 .

## 安装

`@caravan/bitcoin` 作为国家防范机制一揽子计划分发。 把它加进你的 应用程序的依赖性 :

```
$ npm install --save @caravan/bitcoin
```

## 使用量

库提供基于数据的功能性API 使用的结构 `bitcoinjs-lib`。 。 。 .

特别是,许多职能接受a `Multisig` 对象是 此库为返回的对象类型提供的类型名称 函数,例如 `bitcoin.payments.p2ms`, (中文(简体) ), `bitcoin.payments.p2sh`, (中文(简体) ), 从( c) `bitcoinjs-lib`。 。 。 .

下面的例子初步说明了如何使用这个库.

### 与多西格地址交互.

#### 生成多西格

`Multisig` 对象可以用两个函数生成:

-   `generateMultisigFromPublicKeys` -- 在直接通过公钥时有用
-   `generateMultisigFromHex` -- 在解析已存在的赎回/证人脚本时有用

每个函数都接受决定 多西格地址类型(如P2SH或P2WSH).

> **重要:公用钥匙排序**
> 
> `generateMultisigFromPublicKeys` 使用公用钥匙的顺序. 如果你需要的话 `sortedmulti` 相容性( 包括大多数硬件钱包都需要) Ledger 和 Trezor, 以及钱包描述符中的标准, 您必须排序公众 语法键 **在此之前** 将它们转到此功能:
> 
> ```javascript
> const sortedPublicKeys = [...publicKeys].sort();
> const multisig = generateMultisigFromPublicKeys(network, addressType, m, ...sortedPublicKeys);
> ```
> 
> 无法排序将生成一个有效的多西格地址, 但将会是 **不同** 从硬件钱包和其他软件生成的地址 `sortedmulti`。 。 。 .

```javascript
import {
    generateMultisigFromPublicKeys,
    generateMultisigFromHex,
    P2SH,                      // or: P2SH_P2WSH, P2WSH,
    TESTNET,                   // or: MAINNET,
    multisigAddress,
} from "@caravan/bitcoin";

// Public keys are represented as compressed hex.
const publicKeys = [
  "02a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d4",
  "03938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba",
];

// Sort public keys for sortedmulti compatibility (recommended)
const sortedPublicKeys = [...publicKeys].sort();

// A testnet P2SH 2-of-2 multisig.
const m1 = generateMultisigFromPublicKeys(TESTNET, P2SH, 2, ...sortedPublicKeys);
console.log(multisigAddress(m1))
// 2N5KgAnFFpmk5TRMiCicRZDQS8FFNCKqKf1

const redeemScript = "522102a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d42103938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba52ae";
// Same as m1 but using redeem script
const m2 = generateMultisigFromHex(TESTNET, P2SH, redeemScript);
console.log(multisigAddress(m2))
// 2N5KgAnFFpmk5TRMiCicRZDQS8FFNCKqKf1
```

#### 查询多西格

`Multisig` 对象可以相互传递,并与其它对象一起询问 函数.

```javascript
multisigAddress(multisig); // Returns public address
multisigAddressType(multisig); // P2SH
multisigRequiredSigners(multisig); // 2
multisigTotalSigners(multisig); // 3
multisigScript(multisig); // Returns redeem OR witness script, as appropriate
multisigRedeemScript(multisig); // Returns redeem script in hex (null for P2WSH)
multisigWitnessScript(multisig); // Returns witness script in hex (null for P2SH)
multisigPublicKeys(multisig); // Returns publicKeys
```

#### 多西格交易

`Multisig` 对象可用于起草签名或未签名 交易和验证交易签名.

```javascript
import {
  generateMultisigFromPublicKeys,
  TESTNET,
  P2SH,
  unsignedMultisigTransaction,
  validateMultisigSignature,
} from "@caravan/bitcoin";
// Spending 3 UTXOs from the same multisig address.

// First build the multisig for the address.
const publicKeys = [
  "02a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d4",
  "03938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba",
];
const multisig = generateMultisigFromPublicKeys(
  TESTNET,
  P2SH,
  2,
  ...publicKeys
);

// All 3 UTXOs are at the same address so get decorated with the same multisig object.
const inputs = [
  {
    txid: "65e7ef764030dabfb46e3ae1c357b0666d0dda722c9809fb73245d6d68665284",
    index: 1,
    multisig,
  },
  {
    txid: "ae9e1aa8312e102e806fa11d8e65965a624f88459e6bb5bcf48156a0c53e022a",
    index: 1,
    multisig,
  },
  {
    txid: "f243c1fbb85dd49da91477b89c76636202721be9c7df5ee6eee0c6a10861ae44",
    index: 0,
    multisig,
  },
];

const outputs = [
  {
    address: "2NE1LH35XT4YrdnEebk5oKMmRpGiYcUvpNR",
    amountSats: 291590,
  },
];

const unsignedTransaction = unsignedMultisigTransaction(
  TESTNET,
  inputs,
  outputs
);

// Pass the above unsigned transaction to some keystore device/software to obtain a signature.
//
// One signature value per input.
const transactionSignature1 = [
  "304402205397795a8b6e0b8d1c5a0b2b5b8fb8e49afb6dd150d1a186604fa9e71e23aaa20220514b7b7ed9ec43d983d7be5ea4ece5a55b29efa2193d90bf1fd087356fcbd54b",
  "304402200ffcb2331655f1f24bf2f7e16984d81310e55d47c405b45e327abde524c8d31e022036460b70a665d1756ea91e131a1ed1022544dfdd2232f64117230d22f9deeb08",
  "30440220167a35bccf4bb13073e8c66a1b094906d5c7879d6cdac730e435aef196d2f3eb02205a39e05763e511dc15deff56fa29eead850623076fda8a5e173dd0942197aaf4",
];

// Signatures can be validated.
transactionSignature1.forEach((inputSignature, inputIndex) => {
  const result = validateMultisigSignature(
    unsignedTransaction,
    inputIndex,
    inputs[inputIndex],
    inputSignature
  );
  if (!result) {
    console.error(`Invalid signature for input ${inputIndex + 1}`);
  }
});

// Get the second required signature.
const transactionSignature2 = ["304a...", "304b...", "304c..."];

// Combine signatures into a fully signed transaction.
const signedTransaction = signedMultisigTransaction(
  TESTNET,
  inputs,
  outputs,
  transactionSignature1,
  transactionSignature2
);

// Broadcast this transaction somehow...
console.log(signedTransaction.tHex());
```

### 验证

此库包含若干用于校验的实用函数, 而非 国家 `bitcoinjs-lib` 或其他图书馆。 审定 函数旨在返回空字符串 `''` 关于有效输入 并提供一个有用的错误信息.

-   `validateAddress` - 了解Bech32地址并知道 不同网络地址的差异
    
-   `valdiateBIP32Path` - 理解绝对和相对的BIP32 路径,验证最大 BIP32 指数值,并可以选择 检查完全硬化或未硬化的路径
    
-   `validateExtendedPublicKey` -- 了解网络依赖性 编码扩展公钥的差异
    
-   `validatePublicKey` -- 允许任何十六进制值
    
-   `validateFeeRate` - 实施合理的最高收费标准 萨多什语/字节
    
-   `validateFee` - 在BTC中实施合理的最高收费
    
-   `validateOutputAmount` - 检查尘埃,但数量较少 超过总输入量
    
-   `validateMultisigSignature` - 检查签名是否正确 跨多相地址类型的工作
    

## 开发者

### 问题解决与问题

#### `bitcoinjs-lib-v5`

这是为了确保传统车队/比特币的功能 使用遗留的比特币js-lib,在建于大篷车/协调员.

学多点 [这里](https://github.com/vitejs/vite/issues/4245), (中文(简体) ), [这里](https://github.com/zackerydev/noist?tab=readme-ov-file),以及 [这里](https://github.com/prisma/prisma/issues/9649)。 。 。 .

### 捐款

Unchained Capital 欢迎错误报告,新功能,以及这个库更好的文档.

如果您正在修复错误或添加特性, 请先检查 [GitHub 问题页面](https://github.com/caravan-bitcoin/caravan/issues) 以了解是否对此进行过任何讨论.

为了作出贡献,在 GitHub 上创建一个拉动请求(PR),以对抗 [@ caravan/ 比特币主叉](https://github.com/caravan-bitcoin/caravan/)。 。 。 .

在提交公关前,确保更新并运行测试套房!

## 常见问题

### @caravan/bitcoin 是什么？

无链首都比特币公用事业图书馆\.

### 如何安装 @caravan/bitcoin？

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

### @caravan/bitcoin 支持 TypeScript 吗？

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

### @caravan/bitcoin 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @caravan/bitcoin 需要什么版本的 Node\.js？

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

### @caravan/bitcoin 可以商用吗？

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

### @caravan/bitcoin 的下载量有多少？

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

### @caravan/bitcoin 还在维护吗？

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