# @elemental-zcash/zaddr\_wasm\_parser 中文文档

规范地址：https://npmcn.com/package/%40elemental-zcash/zaddr_wasm_parser/

版本：0\.2\.0
npm 元数据更新时间：2025-04-23T21:13:15.857Z
中文译文更新时间：2026-11-14T06:41:11.896Z
软件包许可：MIT OR Apache-2\.0

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

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

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

- 包体积（解压后）：1.3 MB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-04-16T17:13:35.318Z
- 最新版本发布：2025-04-23T21:13:15.663Z
- 近 30 天下载量：2230（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

WASM 包装器围绕官方的 Rust zcash 地址库,用于解析和验证 Zcash 统一地址 .

## 安装

```sh
npm install @elemental-zcash/zaddr_wasm_parser
```

也可以使用：`pnpm add @elemental-zcash/zaddr_wasm_parser`、`yarn add @elemental-zcash/zaddr_wasm_parser`、`bun add @elemental-zcash/zaddr_wasm_parser`

## README

# 扎德德-瓦斯-帕塞尔

`zaddr-wasm-parser` 是一个轻量级,无国籍的Zcash地址解析器,编译为WebAssem(WASM),用于安全地融入前端应用程序.

它提供了一个最小和可靠的API,用于验证,分类,分析Zcash地址,包括United 地址(UA),而不需要访问私人密钥,钱包状态,或块链节点.

此模块使用 Rust 库构建 [`zcash_address`](https://docs.rs/zcash_address/latest/zcash_address)。 。 。 .  
源代码位于 `src/` 目录.  
WASM-综合测试位于 `tests/` 目录.

* * *

## 安装和构建

为了从一个干净的系统建立该项目:

### 1\. 清除储存库:

```bash
cd ~/zcash-wasm
git clone https://github.com/ruzcash/zaddr-wasm-parser.git
cd zaddr-wasm-parser
```

### 2\. 安装依赖性:

安装 Rust Web Assembly 工具链 :

```bash
brew install wasm-pack
```

(可选)安装 `wasm-bindgen-cli` 以运行浏览器测试 :

```bash
cargo install wasm-bindgen-cli
```

(可选) 安装一个简单的本地服务器供浏览器预览 :

```bash
npm install -g live-server
```

### 3\. 构建WASM模块:

#### 对于Node.js(TypeScript测试和演示)

```bash
wasm-pack build --target bundler --out-dir pkg
```

#### 浏览器( HTML 演示和测试)

```bash
wasm-pack build --target web --out-dir pkg
```

> 这两个目标是: **不兼容** 与相为相. 如果在浏览器和Node.js测试之间切换,则会相应重编WASM模块.

* * *

## 类型脚本切换器

### 编译并运行演示

```bash
cd ts-wrapper
npm install
npm run build
npm run demo-dev   # Runs src/demo.ts with a mocked SDK
npm run demo       # Runs compiled dist/demo.js with real WASM
```

> `demo.ts` 动态交换 `src/` 财务报告和审定财务报表 `dist/` 取决于 `USE_SRC` 环境变量.

* * *

## `npm` 使用量

此软件包发布到 `npm` 设于一个防御工事仓库之下: [https://github.com/elemental-zcash/zaddr-wasm-parser 页面存档备份,存于互联网档案馆](https://github.com/elemental-zcash/zaddr-wasm-parser) 带有软件包名称 `@elemental-zcash/zaddr_wasm_parser`。 。 。 .

```tsx
import initWasm, {
  normalize_zcash_address,
  is_valid_zcash_address,
  get_zcash_address_type,
  get_address_receivers
} from "@elemental-zcash/zaddr_wasm_parser";

await initWasm();

const addr = "u1...";

console.log("Valid:", isZcashAddressValid(addr));
console.log("Type:", getZcashAddressType(addr));
console.log("Normalized:", normalizeZcashAddress(addr));
console.log("Receivers:", getAddressReceivers(addr));
```

返回接收器结构 :

```type
  p2pkh: string | null;
  p2sh: string | null;
  sapling: string | null;
  orchard: string | null;
  tex: string | null;
};
```

## 用法示例

```ts
import {
  initWasm,
  isZcashAddressValid,
  getZcashAddressType,
  normalizeZcashAddress,
  getAddressReceivers,
} from "zaddr-wasm-parser";


await initWasm();

const addr = "u1...";
console.log("Valid:", isZcashAddressValid(addr));
console.log("Type:", getZcashAddressType(addr));
console.log("Normalized:", normalizeZcashAddress(addr));
console.log("Receivers:", getAddressReceivers(addr));
```

* * *

## API 参考

### `initWasm(): Promise<void>`

初始化 Web Assembly 模块。 在使用其他函数之前必须先调用 .

### `isZcashAddressValid(address: string): boolean`

回返 `true` 如果给定的字符串是一个有效的Zcash地址.

### `getZcashAddressType(address: string): "p2pkh" | "p2sh" | "sapling" | "unified" | "tex"`

返回地址类型 :

-   `"p2pkh"` ——透明付费地址
-   `"p2sh"` - 透明的按脚本付费地址
-   `"sapling"` - 树苗屏蔽地址
-   `"unified"` ——统一地址
-   `"tex"` — TExt 地址( 实验性)

### `normalizeZcashAddress(address: string): string`

返回地址串的正则版本. 丢出一个 `JsError` 如果输入无效.

### `getAddressReceivers(address: string): AddressReceivers`

将Zcash地址分解为内部接收器.  
丢出一个 `JsError` 如果输入无效.

```ts
type AddressReceivers = {
  p2pkh: string | null;
  p2sh: string | null;
  sapling: string | null;
  orchard: string | null;
  tex: string | null;
};
```

* * *

## 模糊测试( V)

包括一个全面的模糊测试,以确保Zcash地址解析器正确和安全地处理边缘案件.

这个用 [`vitest`](https://vitest.dev/) 以验证剖析器在不正确、截断和完全有效的地址之间的行为。 它涵盖:

-   地址验证
-   类型检测
-   正常化
-   接收器提取

支持的地址类型包括:

-   透明`p2pkh`, (中文(简体) ), `p2sh`(中文(简体) )
-   树苗
-   统一地址( UA)
-   仅限果园
-   文本

所有测试都位于:  
`ts-wrapper/fuzz.test.ts`

运行它从 `ts-wrapper` 目录 :

```bash
cd ts-wrapper
npm run fuzz
```

* * *

## Rust 测试

要使用 Chrome 进行整合测试:

```bash
wasm-pack test --chrome
```

所有基于WASM的Rust测试都位于 `tests/` 目录.  
它们包括透明、屏蔽、统一和无效的Zcash地址格式.

> 如果您看到与 `WebAssembly.instantiateStreaming`中,确保模块与 `--target web`数字 :

```bash
wasm-pack build --target web --out-dir pkg
```

预期产出:

```
test result: ok. 16 passed; 0 failed
```

* * *

### 节点.js 集成测试

包含一个普通JavaScript测试文件,通过Node.js进行人工验证:

```bash
npx tsx test-integration/test.js
```

此脚本验证多个 Zcash 地址类型, 包括 :

-   `t1` - 透明的P2PKH
-   `zs` - 树苗
-   `u1` ——统一地址
-   `tex1` ——TEX地址(用不同的前缀包装了P2PKH)

它也涵盖不正确的输入(如空字符串,emojis和垃圾等).

每一个测试案例的打印结果如下:

-   `is_valid_zcash_address`
-   `get_zcash_address_type`
-   `normalize_zcash_address`
-   `get_address_receivers`

这是一个快速确认WASM模块在Node.js环境中正确运行的方法.

* * *

## 浏览器 Demo

基于功能浏览器的演示页面包含在寄存器中:  
`zcash_address_parser_test.html`

要查看本地演示:

```bash
npx live-server
```

然后打开以下 URL :

```
http://127.0.0.1:8080/zcash_address_parser_test.html
```

此 HTML 页面允许使用编译的 WASM 模块对 ZCash 地址解析和分类进行交互测试.

> 确保使用 WASM 模块编译 `--target web` 在使用浏览器演示之前.

* * *

## 为什么用这个?

`zaddr-wasm-parser` 用于完全节点接入不切实际的情况,特别是:

-   基于浏览器的应用程序
-   从透明地址转移到统一地址的交易所
-   需要快速验证的Zcash兼容工具

这个库从不触及私人密钥或网络状态. 它对于前端环境,静态分析,或者Web SDKs中的集成来说是理想的.

* * *

## 项目结构

```
zaddr-wasm-parser/
├── src/                        # Rust source code (lib.rs)
├── tests/                      # Rust-based tests for WASM
├── ts-wrapper/                # TypeScript interface and bindings
│   ├── src/
│   │   ├── index.ts
│   │   └── types.ts
│   ├── dist/
│   ├── demo.ts
│   ├── fuzz.test.ts
│   ├── package.json
│   └── __mocks__/
├── test-integration/          # Optional JS-only local test
│   └── test.js
├── zcash_address_parser_test.html  # Browser test page
├── Cargo.toml
├── README.md
├── .gitignore
├── LICENSE-MIT
├── LICENSE-APACHE
```

* * *

## 许可证

根据麻省理工学院或Apache-2.0颁发双重许可证.

* * *

## 维护者

-   [@elemental-zcash (原始内容存档于2012-10-12)](https://github.com/elemental-zcash)
-   [@nuttycom (英语)](https://github.com/nuttycom)
-   [@ ruzcash (英语)](https://github.com/ruzcash)

## 常见问题

### @elemental-zcash/zaddr\_wasm\_parser 是什么？

WASM 包装器围绕官方的 Rust zcash 地址库,用于解析和验证 Zcash 统一地址 \.

### 如何安装 @elemental-zcash/zaddr\_wasm\_parser？

在项目目录运行 npm install @elemental-zcash/zaddr\_wasm\_parser，或使用 pnpm add / yarn add / bun add。

### @elemental-zcash/zaddr\_wasm\_parser 支持 TypeScript 吗？

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

### @elemental-zcash/zaddr\_wasm\_parser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @elemental-zcash/zaddr\_wasm\_parser 可以商用吗？

@elemental-zcash/zaddr\_wasm\_parser 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @elemental-zcash/zaddr\_wasm\_parser 的下载量有多少？

根据 npm 官方下载统计，@elemental-zcash/zaddr\_wasm\_parser 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,230 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elemental-zcash/zaddr\_wasm\_parser 还在维护吗？

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