{"_id":"@elemental-zcash/zaddr_wasm_parser","_rev":"3-350bf24a5789521976d50517f5b5c1a2","name":"@elemental-zcash/zaddr_wasm_parser","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@elemental-zcash/zaddr_wasm_parser","version":"0.1.0","keywords":["zcash","address","sapling","unified"],"license":"MIT OR Apache-2.0","_id":"@elemental-zcash/zaddr_wasm_parser@0.1.0","maintainers":[{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"}],"homepage":"https://github.com/ruzcash/zaddr_wasm_parser#readme","bugs":{"url":"https://github.com/ruzcash/zaddr_wasm_parser/issues"},"dist":{"shasum":"6b6bd1a57c1fbf3b6d58e47c4fd5547f8c6d6df5","tarball":"https://registry.npmjs.org/@elemental-zcash/zaddr_wasm_parser/-/zaddr_wasm_parser-0.1.0.tgz","fileCount":6,"integrity":"sha512-uShN/C6L882nEVBC6nSFBrenvW6MKrFZm3tyvdPs1Y/z1WK1FDQxJuEgBidpTjE/HJ4sOTt4qGTJJFmTFTMJ5Q==","signatures":[{"sig":"MEYCIQDQy1S/XU4DStFKDCGrFMvq5m1RoE3Hmi5izV2/xt5wGwIhAKJALytRWDKKxXODNBCgmVlNbf77FDuSkBKGqyP/KAy9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119775},"main":"zaddr_wasm_parser.js","type":"module","types":"zaddr_wasm_parser.d.ts","gitHead":"05c1ded91331ab353ac6c6668523a02023d4bb97","_npmUser":{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"},"repository":{"url":"git+https://github.com/ruzcash/zaddr_wasm_parser.git","type":"git"},"_npmVersion":"10.2.3","description":"WASM wrapper around the official Rust zcash_address library for parsing and validating Zcash Unified Addresses.","directories":{},"sideEffects":["./zaddr_wasm_parser.js","./snippets/*"],"_nodeVersion":"18.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/zaddr_wasm_parser_0.1.0_1744823615420_0.1571204183744932","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@elemental-zcash/zaddr_wasm_parser","version":"0.1.1","keywords":["zcash","address","sapling","unified"],"license":"MIT OR Apache-2.0","_id":"@elemental-zcash/zaddr_wasm_parser@0.1.1","maintainers":[{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"}],"homepage":"https://github.com/elemental-zcash/zaddr_wasm_parser#readme","bugs":{"url":"https://github.com/elemental-zcash/zaddr_wasm_parser/issues"},"dist":{"shasum":"21f73955350f6afaf1e45acb499196bf74b23355","tarball":"https://registry.npmjs.org/@elemental-zcash/zaddr_wasm_parser/-/zaddr_wasm_parser-0.1.1.tgz","fileCount":8,"integrity":"sha512-4YB2Bzw83U4JAavMmH2ANQP+VhnpAYNpqjmZFvqAERmBdXhxN1vqeX9VR4B6RIrkidkHtVolLH0c4K209nLTNg==","signatures":[{"sig":"MEQCIDImdw8O3TeacDqZXxkgVpimKNEFMYkKGZpW1qK62xALAiAI7a7Am21N8EQym0lWAgR7wh4lv0gSjo/gSj7nntWz/Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131161},"main":"zaddr_wasm_parser.js","type":"module","types":"zaddr_wasm_parser.d.ts","gitHead":"05c1ded91331ab353ac6c6668523a02023d4bb97","_npmUser":{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"},"repository":{"url":"git+https://github.com/elemental-zcash/zaddr_wasm_parser.git","type":"git"},"_npmVersion":"10.2.3","description":"WASM wrapper around the official Rust zcash_address library for parsing and validating Zcash Unified Addresses.","directories":{},"sideEffects":["./zaddr_wasm_parser.js","./snippets/*"],"_nodeVersion":"18.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/zaddr_wasm_parser_0.1.1_1744828620742_0.8766416234369929","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@elemental-zcash/zaddr_wasm_parser","type":"module","description":"WASM wrapper around the official Rust zcash_address library for parsing and validating Zcash Unified Addresses.","version":"0.2.0","license":"MIT OR Apache-2.0","repository":{"type":"git","url":"git+https://github.com/ruzcash/zaddr_wasm_parser.git"},"main":"zaddr_wasm_parser.js","types":"zaddr_wasm_parser.d.ts","sideEffects":["./zaddr_wasm_parser.js","./snippets/*"],"keywords":["zcash","address","sapling","unified"],"_id":"@elemental-zcash/zaddr_wasm_parser@0.2.0","gitHead":"76d8efd0a89dd95c6d423de8361c2e4e21684a4b","bugs":{"url":"https://github.com/ruzcash/zaddr_wasm_parser/issues"},"homepage":"https://github.com/ruzcash/zaddr_wasm_parser#readme","_nodeVersion":"18.19.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-SBKx72zdX9kxkqImBZLhm3N5dG7zXQZFUFOpwL/n3PSUhwQgpckovxOeqWR4FqHBtEBjqWA/c9MUUzP3nsYxrQ==","shasum":"d2482cacb21abf83b68a87022d4e0096d074a5da","tarball":"https://registry.npmjs.org/@elemental-zcash/zaddr_wasm_parser/-/zaddr_wasm_parser-0.2.0.tgz","fileCount":6,"unpackedSize":1310103,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF5mEaxvOpojGgFqveleX9TK2bagXnZDrgwoSTCuKB9uAiEA6p++2tRX8gNtkUyKakkchUrcMsYygju/S3f21EC3e3w="}]},"_npmUser":{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"},"directories":{},"maintainers":[{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zaddr_wasm_parser_0.2.0_1745442795385_0.7628967363091768"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-16T17:13:35.318Z","modified":"2025-04-23T21:13:15.857Z","0.1.0":"2025-04-16T17:13:35.647Z","0.1.1":"2025-04-16T18:37:00.910Z","0.2.0":"2025-04-23T21:13:15.663Z"},"bugs":{"url":"https://github.com/ruzcash/zaddr_wasm_parser/issues"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/ruzcash/zaddr_wasm_parser#readme","keywords":["zcash","address","sapling","unified"],"repository":{"type":"git","url":"git+https://github.com/ruzcash/zaddr_wasm_parser.git"},"description":"WASM wrapper around the official Rust zcash_address library for parsing and validating Zcash Unified Addresses.","maintainers":[{"name":"macintoshhelper","email":"contact+npm@macintoshhelper.com"}],"readme":"# zaddr-wasm-parser\n\n`zaddr-wasm-parser` is a lightweight, stateless address parser for Zcash, compiled to WebAssembly (WASM) for safe integration into front-end applications.\n\nIt provides a minimal and reliable API to validate, classify, and analyze Zcash addresses, including Unified Addresses (UA), without requiring access to private keys, wallet state, or blockchain nodes.\n\nThis module is built using the Rust library [`zcash_address`](https://docs.rs/zcash_address/latest/zcash_address).  \nSource code is located in the `src/` directory.  \nWASM-integrated tests are located in the `tests/` directory.\n\n---\n\n## Installation and Build\n\nTo set up the project from a clean system:\n\n### 1. Clone the repository:\n\n```bash\ncd ~/zcash-wasm\ngit clone https://github.com/ruzcash/zaddr-wasm-parser.git\ncd zaddr-wasm-parser\n```\n\n### 2. Install dependencies:\n\nInstall the Rust WebAssembly toolchain:\n\n```bash\nbrew install wasm-pack\n```\n\n(Optional) Install `wasm-bindgen-cli` to run browser tests:\n\n```bash\ncargo install wasm-bindgen-cli\n```\n\n(Optional) Install a simple local server for browser preview:\n\n```bash\nnpm install -g live-server\n```\n\n### 3. Build the WASM module:\n\n#### For Node.js (TypeScript tests and demo)\n```bash\nwasm-pack build --target bundler --out-dir pkg\n```\n\n#### For browser (HTML demo and tests)\n```bash\nwasm-pack build --target web --out-dir pkg\n```\n\n> ⚠️ These two targets are **not compatible** with each other. If you switch between browser and Node.js testing, recompile the WASM module accordingly.\n\n---\n\n## TypeScript Wrapper\n\n### Compile and run demo\n\n```bash\ncd ts-wrapper\nnpm install\nnpm run build\nnpm run demo-dev   # Runs src/demo.ts with a mocked SDK\nnpm run demo       # Runs compiled dist/demo.js with real WASM\n```\n\n> `demo.ts` dynamically switches between `src/` and `dist/` depending on the `USE_SRC` environment variable.\n\n---\n\n## `npm` Usage\n\nThis package is published to `npm` under a forked repository: https://github.com/elemental-zcash/zaddr-wasm-parser with the package name `@elemental-zcash/zaddr_wasm_parser`.\n\n```tsx\nimport initWasm, {\n  normalize_zcash_address,\n  is_valid_zcash_address,\n  get_zcash_address_type,\n  get_address_receivers\n} from \"@elemental-zcash/zaddr_wasm_parser\";\n\nawait initWasm();\n\nconst addr = \"u1...\";\n\nconsole.log(\"Valid:\", isZcashAddressValid(addr));\nconsole.log(\"Type:\", getZcashAddressType(addr));\nconsole.log(\"Normalized:\", normalizeZcashAddress(addr));\nconsole.log(\"Receivers:\", getAddressReceivers(addr));\n```\n\nReturned receiver structure:\n\n```type AddressReceivers = {\n  p2pkh: string | null;\n  p2sh: string | null;\n  sapling: string | null;\n  orchard: string | null;\n  tex: string | null;\n};\n```\n\n\n## Usage Example\n\n```ts\nimport {\n  initWasm,\n  isZcashAddressValid,\n  getZcashAddressType,\n  normalizeZcashAddress,\n  getAddressReceivers,\n} from \"zaddr-wasm-parser\";\n\n\nawait initWasm();\n\nconst addr = \"u1...\";\nconsole.log(\"Valid:\", isZcashAddressValid(addr));\nconsole.log(\"Type:\", getZcashAddressType(addr));\nconsole.log(\"Normalized:\", normalizeZcashAddress(addr));\nconsole.log(\"Receivers:\", getAddressReceivers(addr));\n```\n\n---\n\n## API Reference\n\n### `initWasm(): Promise<void>`\nInitializes the WebAssembly module. Must be called before using other functions.\n\n### `isZcashAddressValid(address: string): boolean`\nReturns `true` if the given string is a valid Zcash address.\n\n### `getZcashAddressType(address: string): \"p2pkh\" | \"p2sh\" | \"sapling\" | \"unified\" | \"tex\"`\nReturns the address type:\n- `\"p2pkh\"` — Transparent Pay-to-PubKey-Hash address\n- `\"p2sh\"` — Transparent Pay-to-Script-Hash address\n- `\"sapling\"` — Sapling shielded address\n- `\"unified\"` — Unified address\n- `\"tex\"` — TExt address (experimental)\n\n### `normalizeZcashAddress(address: string): string`\nReturns a normalized version of the address string.\nThrows a `JsError` if the input is invalid.\n\n### `getAddressReceivers(address: string): AddressReceivers`\nDecomposes a Zcash address into its internal receivers.  \nThrows a `JsError` if the input is invalid.\n\n```ts\ntype AddressReceivers = {\n  p2pkh: string | null;\n  p2sh: string | null;\n  sapling: string | null;\n  orchard: string | null;\n  tex: string | null;\n};\n```\n\n---\n\n## Fuzz Testing (Vitest)\n\nA comprehensive fuzz test is included to ensure the Zcash address parser handles edge cases correctly and safely.\n\nThis uses [`vitest`](https://vitest.dev/) to validate the parser’s behavior across malformed, truncated, and fully valid addresses. It covers:\n\n- Address validation\n- Type detection\n- Normalization\n- Receiver extraction\n\nSupported address types include:\n- Transparent (`p2pkh`, `p2sh`)\n- Sapling\n- Unified Address (UA)\n- Orchard-only UA\n- TEX\n\nAll tests are located in:  \n`ts-wrapper/fuzz.test.ts`\n\nRun it from the `ts-wrapper` directory:\n\n```bash\ncd ts-wrapper\nnpm run fuzz\n```\n\n---\n\n## Rust Testing \n\nTo run integration tests using Chrome:\n\n```bash\nwasm-pack test --chrome\n```\n\nAll WASM-enabled Rust tests are located in the `tests/` directory.  \nThey cover transparent, shielded, Unified, and invalid Zcash address formats.\n\n> If you see errors related to `WebAssembly.instantiateStreaming`, make sure the module was built with `--target web`:\n\n```bash\nwasm-pack build --target web --out-dir pkg\n```\n\nExpected output:\n\n```\ntest result: ok. 16 passed; 0 failed\n```\n\n---\n\n### Node.js Integration Tests\n\nA plain JavaScript test file is included for manual validation via Node.js:\n\n```bash\nnpx tsx test-integration/test.js\n```\n\nThis script verifies multiple Zcash address types, including:\n\n- `t1` — Transparent P2PKH  \n- `zs` — Sapling  \n- `u1` — Unified Address  \n- `tex1` — TEX address (wrapped P2PKH with a different prefix)\n\nIt also covers malformed inputs (e.g. empty strings, emojis, and garbage).\n\nEach test case prints results from the following methods:\n\n- `is_valid_zcash_address`\n- `get_zcash_address_type`\n- `normalize_zcash_address`\n- `get_address_receivers`\n\nThis is a quick way to confirm that the WASM module functions correctly in Node.js environments.\n\n---\n\n\n## Browser Demo\n\nA functional browser-based demo page is included in the repository:  \n`zcash_address_parser_test.html`\n\nTo view the demo locally:\n\n```bash\nnpx live-server\n```\n\nThen open the following URL:\n\n```\nhttp://127.0.0.1:8080/zcash_address_parser_test.html\n```\n\nThis HTML page allows interactive testing of Zcash address parsing and classification using the compiled WASM module.\n\n> Ensure the WASM module was compiled using `--target web` before using the browser demo.\n\n---\n\n## Why Use This?\n\n`zaddr-wasm-parser` is designed for use cases where full-node access is not practical — especially:\n\n- Browser-based applications\n- Exchanges migrating from transparent to Unified Addresses\n- Zcash-compatible tooling that needs quick validation\n\nThis library never touches private keys or network state. It's ideal for front-end environments, static analysis, or integration in Web SDKs.\n\n---\n\n## Project Structure\n\n```\nzaddr-wasm-parser/\n├── src/                        # Rust source code (lib.rs)\n├── tests/                      # Rust-based tests for WASM\n├── ts-wrapper/                # TypeScript interface and bindings\n│   ├── src/\n│   │   ├── index.ts\n│   │   └── types.ts\n│   ├── dist/\n│   ├── demo.ts\n│   ├── fuzz.test.ts\n│   ├── package.json\n│   └── __mocks__/\n├── test-integration/          # Optional JS-only local test\n│   └── test.js\n├── zcash_address_parser_test.html  # Browser test page\n├── Cargo.toml\n├── README.md\n├── .gitignore\n├── LICENSE-MIT\n├── LICENSE-APACHE\n```\n\n---\n\n## License\n\nDual-licensed under MIT or Apache-2.0.\n\n---\n\n## Maintainer\n\n- [@elemental-zcash](https://github.com/elemental-zcash)\n- [@nuttycom](https://github.com/nuttycom)\n- [@ruzcash](https://github.com/ruzcash)  \n\n\n","readmeFilename":"README.md"}