@ledgerhq/zcash-utils 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @ledgerhq/zcash-utils
+
+Rust workspace for Zcash cryptographic operations. Provides key derivation,
+shielded transaction decryption, and compact block scanning across multiple
+runtime targets.
+
+## Build targets
+
+| Target                | Script                         | Output                                  |
+| --------------------- | ------------------------------ | --------------------------------------- |
+| Node.js / Electron    | `./scripts/build-napi.sh`      | `index.*.node`                          |
+| macOS CLI (universal) | `./scripts/build-cli-macos.sh` | `dist/ledger-zcash-cli-macos-universal` |
+| Linux CLI (static)    | `./scripts/build-cli-linux.sh` | `dist/ledger-zcash-cli-linux-x86_64`    |
+
+See [`docs/build-targets.md`](docs/build-targets.md) for prerequisites and details.
+
+## Crate structure
+
+```
+zcash-crypto     Pure cryptographic logic (key derivation, trial/full decryption)
+zcash-sync       Async sync engine (lightwalletd / Zaino)
+zcash-ffi-node   Node.js / Electron native addon (napi-rs)
+zcash-cli        CLI binary (ledger-zcash-cli)
+```
+
+See [`docs/architecture.md`](docs/architecture.md) for the dependency graph and
+design decisions.
+
+## CLI usage
+
+```bash
+# Key derivation
+ledger-zcash-cli derive --mnemonic "abandon abandon ... about" --format json
+
+# Query chain tip
+ledger-zcash-cli tip --grpc-url https://zaino-zec-testnet.nodes.stg.ledger-test.com/
+
+# Scan a block range
+ledger-zcash-cli sync \
+    --grpc-url https://zaino-zec-testnet.nodes.stg.ledger-test.com/ \
+    --viewing-key uviewtest1... \
+    --start-height 280000 \
+    --end-height 285000 \
+    --network testnet \
+    --format json
+```
+
+### `derive` options
+
+```
+--mnemonic <WORDS>      BIP-39 mnemonic (reads from stdin if omitted)
+--account <N>           ZIP-32 account index [default: 0]
+--xpub-path <PATH>      BIP-32 xpub path [default: m/44'/133'/{account}']
+--network mainnet|testnet [default: mainnet]
+--no-sapling            Exclude Sapling FVK from UFVK
+--format human|json     [default: human]
+```
+
+## Development
+
+```bash
+# Run all logic tests
+cargo test --package zcash-crypto
+
+# Run CLI integration tests
+cargo test --package zcash-cli
+
+# Coverage (requires cargo install cargo-llvm-cov)
+./scripts/coverage.sh
+
+# Type-check everything
+cargo check --workspace
+```
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — workspace design
+- [`docs/key-derivation.md`](docs/key-derivation.md) — BIP-39 → UFVK pipeline
+- [`docs/block-sync.md`](docs/block-sync.md) — gRPC trial + full decryption
+- [`docs/ffi-node.md`](docs/ffi-node.md) — Node.js/Electron integration
+- [`docs/build-targets.md`](docs/build-targets.md) — build scripts reference
+
+## Release
+
+Versioning is managed with [Changesets](https://github.com/changesets/action). Every merge to `main` triggers the CI workflow, which:
+
+1. Builds all artifacts in parallel on their respective platforms
+2. Either opens/updates a **"Version Packages"** PR if changesets are pending
+3. Or publishes immediately if the "Version Packages" PR has already been merged
+
+### Publishing a new version
+
+```bash
+# 1. Describe the change (patch / minor / major)
+pnpm changeset
+
+# 2. Commit the generated .changeset file and push
+git add .changeset/
+git commit -m "chore: add changeset"
+git push
+
+# 3. Merge the PR → CI automatically opens a "Version Packages" PR
+# 4. Merge the "Version Packages" PR → CI publishes
+```
+
+### Artifacts produced per release
+
+| Artifact                           | Distribution       | Platforms                   |
+| ---------------------------------- | ------------------ | --------------------------- |
+| `@ledgerhq/zcash-utils`            | Ledger JFrog (npm) | All (bundled `.node` files) |
+| `ledger-zcash-cli-macos-universal` | GitHub Release     | macOS arm64 + x64           |
+| `ledger-zcash-cli-linux-x86_64`    | GitHub Release     | Linux x64 (static musl)     |
+
+The `.node` binaries are built in a CI matrix for each OS/architecture target, collected in the publish job, and included in the npm package via the `files` field. The `index.js` NAPI-RS loader looks for a local `.node` file first, then falls back to a separate `@ledgerhq/zcash-utils-{platform}` package if needed.
+
+The npm package is published to the internal Ledger JFrog Artifactory registry. The CI authenticates via OIDC (`LedgerHQ/actions-security/actions/jfrog-login`) and configures `.npmrc` to route `@ledgerhq` scoped packages to the Artifactory URL.
+
+CLI binaries are attached to the tagged GitHub Release (`v{version}`) and are not part of the npm package.
+
+### Required secrets and variables
+
+| Secret / Variable              | Purpose                                               |
+| ------------------------------ | ----------------------------------------------------- |
+| `GITHUB_TOKEN`                 | Automatically provided by GitHub Actions              |
+| `vars.ARTIFACTORY_PUBLISH_URL` | JFrog Artifactory registry URL (without `https://`)  |
+
+## License
+
+MIT OR Apache-2.0

package/index.d.ts

@@ -0,0 +1,112 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Parameters for scanning a block range for shielded transactions.
+ *
+ * The UFVK must be obtained from the Ledger device — never derive it from
+ * a seed phrase directly in this layer.
+ */
+export interface SyncParams {
+  /** gRPC endpoint URL (e.g. `"https://zaino-zec-testnet.nodes.stg.ledger-test.com/"`). */
+  grpcUrl: string
+  /** Unified Full Viewing Key (UFVK) for the account to scan. */
+  viewingKey: string
+  /** First block height to scan (inclusive). */
+  startHeight: number
+  /** Last block height to scan (inclusive). */
+  endHeight: number
+  /** `"mainnet"` or `"testnet"` (default: `"testnet"`). */
+  network?: string
+  /**
+   * When `true`, Sapling outputs are stripped before trial decryption.
+   * Only Orchard actions are processed — eliminates all Sapling crypto work.
+   * Set to `true` for Ledger wallets (Orchard-only support).
+   */
+  orchardOnly?: boolean
+  /**
+   * Maximum retry attempts per range on transient errors (timeout, 503).
+   * The failing range is split in half on each retry. Defaults to 3.
+   */
+  maxRetries?: number
+  /** Emit per-phase timing diagnostics to stderr every 10 seconds. */
+  verbose?: boolean
+}
+/** A single shielded note found during decryption. */
+export interface ShieldedNote {
+  /** Amount in zatoshis (f64 for JS Number compatibility). */
+  amount: number
+  /** `"incoming"`, `"outgoing"`, or `"internal"`. */
+  transferType: string
+  /** Memo text decoded from the note. */
+  memo: string
+}
+/** A matched and fully-decrypted shielded transaction. */
+export interface ShieldedTransaction {
+  /** Transaction ID in big-endian (display) hex order. */
+  txid: string
+  /** Raw transaction bytes as a hex string. */
+  hex: string
+  /** Block height at which this transaction was confirmed. */
+  blockHeight: number
+  /** Block hash in big-endian (display) hex order. */
+  blockHash: string
+  /** Block timestamp (Unix seconds). */
+  blockTime: number
+  /** Transaction fee in zatoshis (shielded bundles only). */
+  fee: number
+  /** Decrypted Sapling notes belonging to this account. */
+  saplingNotes: Array<ShieldedNote>
+  /** Decrypted Orchard notes belonging to this account. */
+  orchardNotes: Array<ShieldedNote>
+}
+/** Scan statistics returned once the stream is exhausted. */
+export interface SyncStats {
+  blocksScanned: number
+  elapsedMs: number
+}
+/**
+ * Start scanning a range of compact blocks and return a transaction stream.
+ *
+ * The scan runs in the background immediately. Call `stream.next()` to
+ * consume transactions as they are found. Call `stream.stats()` after the
+ * stream is exhausted to retrieve scan statistics.
+ *
+ * Trial decryption runs entirely in Rust (no JS event loop blocking).
+ * `GetTransaction` is called only for matched transactions.
+ */
+export declare function startSync(params: SyncParams): Promise<TransactionStream>
+/** Returns the current chain tip height from the gRPC endpoint. */
+export declare function getChainTip(grpcUrl: string): Promise<number>
+/**
+ * Async iterator over matched shielded transactions.
+ *
+ * Usage (TypeScript):
+ * ```ts
+ * const stream = await startSync(params);
+ * let tx: ShieldedTransaction | null;
+ * while ((tx = await stream.next()) !== null) {
+ *   console.log(tx);
+ * }
+ * const stats = await stream.stats();
+ * ```
+ */
+export declare class TransactionStream {
+  /**
+   * Returns the next matched transaction, or `null` when the scan is complete.
+   *
+   * Safety: napi-rs requires `unsafe` for `&mut self` in async methods.
+   * This method is safe to call — it only mutates the internal channel receiver.
+   */
+  next(): Promise<ShieldedTransaction | null>
+  /**
+   * Returns scan statistics once the stream is exhausted (i.e. after `next()`
+   * returns `null`). Calling this before the stream is done will wait until
+   * the background sync task finishes.
+   *
+   * Safety: napi-rs requires `unsafe` for `&mut self` in async methods.
+   */
+  stats(): Promise<SyncStats>
+}

package/index.js

@@ -0,0 +1,317 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.android-arm64.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'index.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.darwin-universal.node')
+      } else {
+        nativeBinding = require('@ledgerhq/zcash-utils-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'index.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-x64.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'index.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@ledgerhq/zcash-utils-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@ledgerhq/zcash-utils-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@ledgerhq/zcash-utils-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { TransactionStream, startSync, getChainTip } = nativeBinding
+
+module.exports.TransactionStream = TransactionStream
+module.exports.startSync = startSync
+module.exports.getChainTip = getChainTip

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ledgerhq/zcash-utils",
+  "version": "0.1.0",
+  "description": "Native Zcash key derivation and shielded sync — Node.js (NAPI)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LedgerHQ/ledger-zcash-utils.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@napi-rs/cli": "^2.18.0",
+    "@types/node": "^25.5.2",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  },
+  "license": "MIT",
+  "scripts": {
+    "// ── NAPI (Node.js / Electron) ──────────────────────────────────────": "",
+    "build": "./scripts/build-napi.sh",
+    "build:debug": "DEBUG=1 ./scripts/build-napi.sh",
+    "// ── CLI artifacts ───────────────────────────────────────────────────": "",
+    "build:cli:macos": "./scripts/build-cli-macos.sh",
+    "build:cli:linux": "./scripts/build-cli-linux.sh",
+    "// ── Rust checks & tests ────────────────────────────────────────────": "",
+    "check": "cargo check --workspace",
+    "test": "cargo test --package zcash-crypto",
+    "test:cli": "cargo test --package zcash-cli",
+    "test:all": "cargo test --workspace",
+    "// ── Coverage ───────────────────────────────────────────────────────": "",
+    "coverage": "./scripts/coverage.sh",
+    "coverage:open": "OPEN_REPORT=1 ./scripts/coverage.sh",
+    "// ── Rustdoc ────────────────────────────────────────────────────────": "",
+    "doc": "cargo doc --workspace --no-deps",
+    "doc:open": "cargo doc --workspace --no-deps --open",
+    "// ── CLI (ledger-zcash-cli) — usage: pnpm cli -- derive --mnemonic '...'": "",
+    "cli": "cargo run -q -p zcash-cli",
+    "cli:derive": "cargo run -q -p zcash-cli -- derive --help",
+    "cli:tip": "cargo run -q -p zcash-cli -- tip --help",
+    "cli:sync": "cargo run -q -p zcash-cli -- sync --help",
+    "// ── Node.js validation & benchmarks ───────────────────────────────": "",
+    "sync-tx": "tsx examples/sync-tx.node.ts --start-height 1130000 --end-height 1180000",
+    "bench": "tsx examples/bench.ts --start-height 280000 --end-height 285000"
+  }
+}