feat: hdwallet-ledger zcash support

ZCASH_LEDGER_IMPLEMENTATION.md

@@ -0,0 +1,101 @@
+# Zcash Ledger Implementation Guide
+
+This document outlines the changes required to support Zcash (ZEC) on Ledger devices within `hdwallet`.
+
+## Overview
+Zcash support on Ledger requires specific handling due to its unique transaction format (ZIP-244, v4/v5 versions) and consensus branch IDs. The standard Bitcoin app on Ledger does not natively support these features without specific flags and updated libraries.
+
+---
+
+## Technical Specifications
+
+### BIP44 Derivation Path
+- **SLIP44 Code**: 133
+- **Standard Path**: `m/44'/133'/0'/0/x`
+- **Account Type**: P2PKH (Legacy) only - no SegWit support
+
+### Transaction Format
+- **Versions**: v4 (Sapling), v5 (NU5+)
+- **Version Encoding**: Little-endian with Overwinter flag
+  - v4: `0x80000004`
+  - v5: `0x80000005`
+- **Version Group IDs**:
+  - v4 (Sapling): `0x892F2085`
+  - v5 (NU5+): `0x26A7270A`
+
+### Consensus Branch IDs
+- **NU5**: `0xC2D6D0B4` (block 1,687,104)
+- **NU6**: `0xC8E71055` (block 2,726,400 - Nov 2024)
+- **NU6.1**: `0x4DEC4DF0` (block 3,146,400 - Nov 2025)
+
+### Address Format
+- **Transparent addresses** (t-addresses): Start with "t1" (mainnet)
+- **No shielded support**: z-addresses not supported in this implementation
+
+---
+
+## Issues & Solutions Discovered
+
+### Issue 1: `getVarint called with unexpected parameters`
+**Error**: `splitTransaction` failed with varint parsing error
+**Root Cause**: Missing `additionals` parameter when calling `splitTransaction`
+**Solution**: Pass `["zcash", "sapling"]` as 4th parameter
+**Reference**: [Ledger splitTransaction tests](https://github.com/LedgerHQ/ledger-live/blob/develop/libs/ledgerjs/packages/hw-app-btc/tests/splitTransaction.test.ts)
+
+### Issue 2: Ledger App Quits / USB Transfer Cancelled
+**Error**: `AbortError: Failed to execute 'transferIn' on 'USBDevice'`
+**Root Cause**: Wrong `isSegwit` parameter value (was `false`, should be `true`)
+**Solution**: Set 2nd parameter to `true` for Zcash in `splitTransaction`
+**Reference**: Ledger test file shows `splitTransaction(hex, true, true, ["zcash", "sapling"])`
+
+### Issue 3: Consensus Branch ID Mismatch (NU6 vs NU6.1)
+**Error**: `transaction uses an incorrect consensus branch id`
+**Root Cause**: Zcash network upgraded to NU6.1 (0x4DEC4DF0), but older Ledger libraries defaulted to NU6.
+**Solution**:
+- Use `@ledgerhq/hw-app-btc` version `10.13.0` (strictly pinned across all packages)
+- Explicitly set `consensusBranchId` in the adapter if necessary.
+
+### Issue 4: Invalid Trusted Input Hash (Zcash v5)
+**Error**: "Missing inputs" error or invalid signature verification on broadcast.
+**Root Cause**: `@ledgerhq/hw-app-btc` uses Double-SHA256 (SHA256d) to calculate the transaction hash for trusted inputs. However, Zcash v5 transactions use ZIP-244 transaction digests (Tree Hash) for the TXID. The library fails to handle this correctly for Zcash inputs, resulting in a mismatch between the trusted input's TXID and the actual input being signed.
+**Solution**: **Monkey Patch** implemented in `packages/hdwallet-ledger/src/bitcoin.ts`.
+- **Mechanism**: We patch `getTrustedInputBIP143` to intercept Zcash transactions.
+- **Fix**: The patch injects the correct ZIP-244 TXID (provided by the adapter via `_customZcashTxId`) and Amount, bypassing the library's faulty re-hashing logic.
+- **Safety**: The patch is strictly guarded to only affect Zcash transactions with the custom properties attached. Trusted input security is maintained as the Ledger device still verifies the signature.
+- **Implementation**: Uses `require` to modify the CommonJS exports of the library, as ES6 imports are immutable.
+
+---
+
+## Known Limitations
+
+### 1. Transparent Addresses Only
+- Only supports t-addresses (transparent UTXO transactions)
+- Does **not** support z-addresses (shielded transactions)
+
+### 2. Expiry Height Management
+- **Current**: Hardcoded to 0 (no expiry) using `Buffer.alloc(4)` in the implementation.
+- **Requirement**: Zcash transactions require `expiryHeight`. If 0, it means no expiry (valid per ZIP-203).
+- **Note**: The current implementation does not derive expiry from input block height.
+
+---
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `packages/hdwallet-ledger/src/bitcoin.ts` | **Major Update**: Added Monkey Patch for `getTrustedInputBIP143`. Logic for Zcash inputs (using `ZcashPsbt`, `splitTransaction` params). Constants for Version/Branch IDs. |
+| `packages/hdwallet-ledger/src/utils.ts` | Configured `isSegwitSupported: true` and `areTransactionTimestamped: true` for Zcash (SLIP-133). |
+| `packages/hdwallet-ledger/src/currencies.ts` | Added Zcash currency with xpub version. |
+
+---
+
+## Testing Checklist
+
+- [x] Address derivation works (t-address format)
+- [x] Transaction signing initiates
+- [x] Ledger app stays open during signing
+- [x] splitTransaction parses input transactions correctly
+- [x] **Consensus Branch ID** matches NU6.1 (0x4DEC4DF0)
+- [x] **Trusted Input Hashing** matches ZIP-244 (via Monkey Patch)
+- [x] Broadcast succeeds (Simulated/Verified)
+- [ ] Swap works end-to-end

examples/sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-sandbox",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "private": true,
   "browserslist": "> 0.5%, last 2 versions, not dead",
@@ -12,24 +12,24 @@
   "dependencies": {
     "@esm2cjs/p-queue": "^7.3.0",
     "@metamask/eth-sig-util": "^7.0.0",
-    "@shapeshiftoss/hdwallet-coinbase": "1.62.25",
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey-tcp": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey-webusb": "1.62.25",
-    "@shapeshiftoss/hdwallet-keplr": "1.62.25",
-    "@shapeshiftoss/hdwallet-ledger": "1.62.25",
-    "@shapeshiftoss/hdwallet-ledger-webhid": "1.62.25",
-    "@shapeshiftoss/hdwallet-ledger-webusb": "1.62.25",
-    "@shapeshiftoss/hdwallet-metamask-multichain": "1.62.25",
-    "@shapeshiftoss/hdwallet-native": "1.62.25",
-    "@shapeshiftoss/hdwallet-phantom": "1.62.25",
-    "@shapeshiftoss/hdwallet-portis": "1.62.25",
-    "@shapeshiftoss/hdwallet-trezor": "1.62.25",
-    "@shapeshiftoss/hdwallet-trezor-connect": "1.62.25",
-    "@shapeshiftoss/hdwallet-vultisig": "1.62.25",
-    "@shapeshiftoss/hdwallet-walletconnect": "1.62.25",
-    "@shapeshiftoss/hdwallet-walletconnectv2": "1.62.25",
+    "@shapeshiftoss/hdwallet-coinbase": "1.62.26",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey-tcp": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey-webusb": "1.62.26",
+    "@shapeshiftoss/hdwallet-keplr": "1.62.26",
+    "@shapeshiftoss/hdwallet-ledger": "1.62.26",
+    "@shapeshiftoss/hdwallet-ledger-webhid": "1.62.26",
+    "@shapeshiftoss/hdwallet-ledger-webusb": "1.62.26",
+    "@shapeshiftoss/hdwallet-metamask-multichain": "1.62.26",
+    "@shapeshiftoss/hdwallet-native": "1.62.26",
+    "@shapeshiftoss/hdwallet-phantom": "1.62.26",
+    "@shapeshiftoss/hdwallet-portis": "1.62.26",
+    "@shapeshiftoss/hdwallet-trezor": "1.62.26",
+    "@shapeshiftoss/hdwallet-trezor-connect": "1.62.26",
+    "@shapeshiftoss/hdwallet-vultisig": "1.62.26",
+    "@shapeshiftoss/hdwallet-walletconnect": "1.62.26",
+    "@shapeshiftoss/hdwallet-walletconnectv2": "1.62.26",
     "bip32": "^2.0.4",
     "eip-712": "^1.0.0",
     "jquery": "^3.7.1",

integration/jest.config.js

@@ -12,6 +12,7 @@ module.exports = {
     "^@shapeshiftoss/hdwallet-(.*)": "<rootDir>/../../packages/hdwallet-$1/src",
     "^valibot$": require.resolve("valibot"),
     "^axios$": require.resolve("axios"),
+    "^@brandonblack/musig/base_crypto$": "<rootDir>/../../node_modules/@brandonblack/musig/lib/base_crypto.js",
   },
   globals: {
     "ts-jest": {

integration/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/integration",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "main": "index.js",
   "license": "MIT",
   "private": true,
@@ -11,16 +11,17 @@
   },
   "dependencies": {
     "@bitcoinerlab/secp256k1": "^1.1.1",
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey-nodewebusb": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey-tcp": "1.62.25",
-    "@shapeshiftoss/hdwallet-ledger": "1.62.25",
-    "@shapeshiftoss/hdwallet-metamask-multichain": "1.62.25",
-    "@shapeshiftoss/hdwallet-native": "1.62.25",
-    "@shapeshiftoss/hdwallet-portis": "1.62.25",
-    "@shapeshiftoss/hdwallet-trezor": "1.62.25",
-    "@shapeshiftoss/hdwallet-vultisig": "1.62.25",
+    "@bitgo/utxo-lib": "^11.18.0",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey-nodewebusb": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey-tcp": "1.62.26",
+    "@shapeshiftoss/hdwallet-ledger": "1.62.26",
+    "@shapeshiftoss/hdwallet-metamask-multichain": "1.62.26",
+    "@shapeshiftoss/hdwallet-native": "1.62.26",
+    "@shapeshiftoss/hdwallet-portis": "1.62.26",
+    "@shapeshiftoss/hdwallet-trezor": "1.62.26",
+    "@shapeshiftoss/hdwallet-vultisig": "1.62.26",
     "fast-json-stable-stringify": "^2.1.0",
     "msw": "^0.27.1",
     "whatwg-fetch": "^3.6.2"

lerna.json

@@ -1,6 +1,6 @@
 {
   "lerna": "5.2.0",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "command": {

packages/hdwallet-coinbase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-coinbase",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "@coinbase/wallet-sdk": "^3.6.6",
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
     "eth-rpc-errors": "^4.0.3",
     "lodash": "^4.17.21"
   },

packages/hdwallet-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-core",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

packages/hdwallet-gridplus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-gridplus",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -20,7 +20,7 @@
     "@ethereumjs/rlp": "5.0.2",
     "@ethereumjs/tx": "5.4.0",
     "@metamask/eth-sig-util": "^7.0.0",
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
     "bech32": "^1.1.4",
     "bs58": "^5.0.0",
     "bs58check": "^4.0.0",

packages/hdwallet-keepkey-chromeusb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-chromeusb",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,7 +14,7 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25"
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26"
   }
 }

packages/hdwallet-keepkey-electron/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-electron",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,7 +14,7 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26",
     "uuid": "^8.3.2"
   },
   "peerDependencies": {

packages/hdwallet-keepkey-nodehid/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-nodehid",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,7 +14,7 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25"
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26"
   },
   "peerDependencies": {
     "node-hid": "^2.1.1"

packages/hdwallet-keepkey-nodewebusb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-nodewebusb",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,8 +14,8 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25"
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26"
   },
   "peerDependencies": {
     "usb": "^2.3.1"

packages/hdwallet-keepkey-tcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-tcp",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,8 +14,8 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26",
     "axios": "^0.21.1"
   }
 }

packages/hdwallet-keepkey-webusb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey-webusb",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,8 +14,8 @@
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
-    "@shapeshiftoss/hdwallet-keepkey": "1.62.25"
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
+    "@shapeshiftoss/hdwallet-keepkey": "1.62.26"
   },
   "devDependencies": {
     "@types/w3c-web-usb": "^1.0.4"

packages/hdwallet-keepkey/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/hdwallet-keepkey",
-  "version": "1.62.25",
+  "version": "1.62.26",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -21,10 +21,12 @@
     "@keepkey/device-protocol": "7.13.4",
     "@metamask/eth-sig-util": "^7.0.0",
     "@shapeshiftoss/bitcoinjs-lib": "7.0.0-shapeshift.2",
-    "@shapeshiftoss/hdwallet-core": "1.62.25",
+    "@shapeshiftoss/hdwallet-core": "1.62.26",
     "@shapeshiftoss/proto-tx-builder": "0.10.0",
     "bignumber.js": "^9.0.1",
     "bnb-javascript-sdk-nobroadcast": "2.16.15",
+    "bs58": "^5.0.0",
+    "bs58check": "^4.0.0",
     "crypto-js": "^4.0.0",
     "eip55": "^2.1.0",
     "google-protobuf": "^3.15.8",

packages/hdwallet-keepkey/src/eos.ts

@@ -1,7 +1,7 @@
 import * as Messages from "@keepkey/device-protocol/lib/messages_pb";
 import * as EosMessages from "@keepkey/device-protocol/lib/messages-eos_pb";
 import * as core from "@shapeshiftoss/hdwallet-core";
-import * as bs58 from "bs58";
+import bs58 from "bs58";
 import createHash from "create-hash";
 import Long from "long";