扎德德-瓦斯-帕塞尔

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

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

此模块使用 Rust 库构建 zcash_address。 。 。 .
源代码位于 src/ 目录.
WASM-综合测试位于 tests/ 目录.

安装和构建

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

1. 清除储存库:

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

2. 安装依赖性:

安装 Rust Web Assembly 工具链 :

brew install wasm-pack

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

cargo install wasm-bindgen-cli

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

npm install -g live-server

3. 构建WASM模块:

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

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

浏览器( HTML 演示和测试)

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

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

类型脚本切换器

编译并运行演示

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 页面存档备份,存于互联网档案馆 带有软件包名称 @elemental-zcash/zaddr_wasm_parser。 。 。 .

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

返回接收器结构 :

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

用法示例

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 如果输入无效.

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

模糊测试( V)

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

这个用 vitest 以验证剖析器在不正确、截断和完全有效的地址之间的行为。 它涵盖:

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

支持的地址类型包括:

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

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

运行它从 ts-wrapper 目录 :

cd ts-wrapper
npm run fuzz

Rust 测试

要使用 Chrome 进行整合测试:

wasm-pack test --chrome

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

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

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

预期产出:

test result: ok. 16 passed; 0 failed

节点.js 集成测试

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

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

要查看本地演示:

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)
• @nuttycom (英语)
• @ ruzcash (英语)