\n\n# @stricahq/bip32ed25519\n\n[](https://www.npmjs.com/package/@stricahq/bip32ed25519)\n[](https://www.npmjs.com/package/@stricahq/bip32ed25519)\n[](https://nodejs.org)\n[](./LICENSE)\n\nCardano key derivation and signing for JavaScript.\n\n- Root keys from a BIP-39 mnemonic's entropy, made the [CIP-3](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0003/Icarus.md) (Icarus) way, with an optional passphrase\n- Hardened and soft [BIP32-Ed25519](https://input-output-hk.github.io/adrestia/static/Ed25519_BIP.pdf) derivation, one index at a time or by a path like [CIP-1852](https://github.com/cardano-foundation/CIPs/tree/master/CIP-1852)'s `m/1852'/1815'/0'/0/0`\n- Address keys from an account's public key alone, for watch-only wallets\n- Ed25519 signing, and verification that agrees with the Cardano ledger\n- Runs in Node.js and in browsers, no polyfills needed\n\nThe curve math and hashing come from the audited [@noble/curves](https://github.com/paulmillr/noble-curves) and [@noble/hashes](https://github.com/paulmillr/noble-hashes). Those are the only dependencies.\n\n## v2 is a breaking change\n\nv2 is not a drop-in upgrade. It is ESM-only and needs Node 22.12 or later, and keys, signatures and hashes are `Uint8Array` instead of `Buffer`.\n\nMoving to v2 is the recommended path: it is faster than v1, carries two dependencies instead of six and no Node.js builtins, and it will get new features and fixes from here on.\n\n### Migrating from v1\n\n| v1 | v2 |\n|---|---|\n| `Buffer` in and out | `Uint8Array` out; `Buffer` still accepted as input |\n| `bytes.toString(\"hex\")` | `Buffer.from(bytes).toString(\"hex\")` (on a `Uint8Array`, `toString(\"hex\")` returns comma-separated numbers) |\n| `publicKey.pubKey` | `publicKey.toBytes()` |\n| deep imports from `@stricahq/bip32ed25519/dist/…` | the package root only |\n| Node.js polyfills for browser bundles | no Node.js builtins |\n| CommonJS package | ESM only, `require(esm)` on Node >= 22.12 |\n\n## Installation\n\n### yarn/npm\n\n```sh\nyarn add @stricahq/bip32ed25519\n```\n\nThe package is ESM-only and needs Node 22.12 or later. You can still `require()` it from CommonJS:\n\n```js\nconst { Bip32PrivateKey } = require(\"@stricahq/bip32ed25519\");\n```\n\nIf you compile TypeScript to CommonJS, that needs TypeScript 5.8 or later with `\"module\": \"nodenext\"`.\n\n### Browser\n\n```html\n\n\n```\n\nThe bundle puts everything on a `bip32ed25519` global. If you use a bundler instead, you won't need polyfills or aliases, because the package doesn't use any Node.js builtins.\n\n## Deriving keys\n\nStart with `fromEntropy`. It takes the entropy of a BIP-39 mnemonic, meaning the bytes the words encode rather than the words themselves, so run the mnemonic through a BIP-39 library first.\n\n```js\nimport { Bip32PrivateKey } from \"@stricahq/bip32ed25519\";\n\nconst rootKey = await Bip32PrivateKey.fromEntropy(entropy);\n\n// CIP-1852: m / purpose' / coin type' / account' / role / index\nconst accountKey = rootKey.derivePath(\"m/1852'/1815'/0'\");\nconst paymentKey = accountKey.derivePath(\"0/0\").toPrivateKey();\nconst stakeKey = accountKey.derivePath(\"2/0\").toPrivateKey();\n\nconst publicKey = paymentKey.toPublicKey();\npublicKey.toBytes(); // Uint8Array(32)\npublicKey.hash(); // Uint8Array(28), Blake2b-224: the payment credential in an address\n```\n\nIn a path, `'`, `h` and `H` all mark a hardened index. You can also derive one step at a time. Both of these lines give the same account key as above:\n\n```js\nimport { HARDENED_OFFSET } from \"@stricahq/bip32ed25519\";\n\nrootKey.deriveHardened(1852).deriveHardened(1815).deriveHardened(0);\nrootKey.derive(HARDENED_OFFSET + 1852).derive(HARDENED_OFFSET + 1815).derive(HARDENED_OFFSET);\n```\n\nIf the wallet has a passphrase (the optional second factor from CIP-3), pass it as a string or as bytes:\n\n```js\nconst rootKey = await Bip32PrivateKey.fromEntropy(entropy, \"passphrase\");\n```\n\nEntropy of any length works. For a 24-word Trezor wallet, pass 33 bytes: the 32 bytes of entropy followed by the mnemonic's checksum byte. Trezor's firmware keeps the checksum in, a known quirk that [CIP-3](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0003/Icarus.md#trezor) documents.\n\n`fromEntropy` is async because it runs PBKDF2 with 4096 iterations through WebCrypto, which takes about 2 ms. Where `crypto.subtle` isn't available, such as on a page served over plain http, it falls back to a JavaScript implementation that takes about 30 ms.\n\n### Watch-only wallets\n\nYou don't need private keys to generate addresses. An account's extended public key can derive all of its soft (non-hardened) children:\n\n```js\nconst accountXpub = accountKey.toBip32PublicKey();\nconst addressKey = accountXpub.derivePath(\"0/5\").toPublicKey(); // the public key of accountKey.derivePath(\"0/5\")\n```\n\nHardened children can't be derived from a public key, so asking for one throws. To store an xpub, `toBytes()` gives you its 64 bytes and `Bip32PublicKey.fromBytes()` loads them back.\n\n## Signing\n\n`sign` takes any bytes. To witness a Cardano transaction, you sign the 32-byte hash of its body.\n\n```js\nconst signature = paymentKey.sign(txHash); // Uint8Array(64)\npublicKey.verify(signature, txHash); // true\n```\n\n### cardano-cli keys\n\nA signing key from cardano-cli, like a `payment.skey` file, isn't an extended key. It's a plain 32-byte Ed25519 secret key: the hex in its `cborHex` after the leading `5820`, which is just the CBOR header for 32 bytes. Load it with `fromSecretKey` and it signs exactly like standard RFC 8032 Ed25519:\n\n```js\nimport { PrivateKey } from \"@stricahq/bip32ed25519\";\n\nconst key = PrivateKey.fromSecretKey(secretKey);\n```\n\nThe `PrivateKey` constructor takes the 64-byte extended form (kL ‖ kR), the one `toPrivateKey()` gives you. Pass it 32 bytes and it throws, pointing you to `fromSecretKey`.\n\n### Which signatures `verify` accepts\n\nEd25519 verifiers disagree on some edge cases, so `verify` matches the one Cardano uses. It accepts exactly what libsodium's `crypto_sign_verify_detached` accepts, and that's what the ledger checks signatures with. If `verify` accepts a signature, so will the chain, and the other way around. A signature is valid when:\n\n- S is less than the group order L\n- neither R nor the public key is one of the small-order encodings libsodium rejects\n- the public key is canonically encoded and is a point on the curve\n- [S]B − [h]A encodes to exactly R's bytes, where h = SHA-512(R ‖ A ‖ M) mod L. This is the cofactorless equation, and it also rules out a non-canonical R.\n\nFor a signature that isn't 64 bytes, `verify` just returns `false`. It never throws because of what a signature contains. None of these rules matter for honestly made signatures, which every Ed25519 verifier accepts. They only settle crafted edge cases.\n\n## Bytes and hex\n\nEverything the package returns is a plain `Uint8Array`. Wherever it takes bytes, any `Uint8Array` works, including a Node.js `Buffer` or one from another realm, like a jsdom test environment.\n\nThere are no hex helpers. On Node, use `Buffer.from(bytes).toString(\"hex\")`. Newer runtimes have `bytes.toHex()`. Or use whatever hex helper your project already has.\n\n## Errors\n\nBad input throws instead of quietly giving you a wrong key. Every function checks its arguments and throws a `TypeError` naming the one that's wrong. Here's what each one accepts:\n\n| Where | Accepts |\n|---|---|\n| any byte argument | a `Uint8Array`, so a string throws, like a mnemonic passed as entropy |\n| `fromEntropy` | non-empty entropy, and a passphrase as a string or bytes |\n| `Bip32PrivateKey` | 96 bytes (kL ‖ kR ‖ chain code), where kL has its 3 lowest bits and its highest bit clear and its second-highest bit set |\n| `Bip32PublicKey` | 64 bytes (public key ‖ chain code), where the public key is a point on the curve |\n| `PrivateKey` | 64 bytes (kL ‖ kR), with the same rule for kL |\n| `PrivateKey.fromSecretKey` | 32 bytes |\n| `PublicKey` | 32 bytes |\n| `derive` | an integer from 0 to 2^32 − 1, where 2^31 and up are hardened |\n| `deriveHardened` | an integer from 0 to 2^31 − 1 |\n| `derivePath` | an optional `m`, then decimal indices separated by `/`. An index marked with `'`, `h` or `H` is hardened and must be below 2^31; the others must be below 2^32 |\n| `Bip32PublicKey.derive`, `derivePath` | soft indices only. A hardened one throws a plain `Error` |\n\n## Key material\n\nEach class keeps its own private copy of the bytes you pass in, and `toBytes()` hands back a fresh copy every time, so changing an array afterwards never changes a key. The package logs nothing, and no error message ever includes key bytes. It doesn't try to wipe keys from memory, though, since JavaScript has no way to guarantee that.\n\n## Benchmarks\n\nMeasured on an Apple M1 Pro with Node 24.13.0.\n\n| Operation | ops/s |\n|---|---|\n| `deriveHardened` | 50,576 |\n| `derive`, soft, children of one key | 51,590 |\n| `derivePath(\"m/1852'/1815'/0'/0/i\")` from the root key | 1,955 |\n| `Bip32PublicKey.derive` | 6,521 |\n| `toPublicKey` of a new `PrivateKey` | 4,959 |\n| `sign`, 32 bytes | 4,652 |\n| `sign`, 1 KB | 4,175 |\n| `verify`, 32 bytes | 1,061 |\n\n`fromEntropy` takes 1.9 ms. A key remembers its public key after computing it, so deriving many soft children of one key (which is what a wallet does for its addresses) only computes it once. Computing a public key and signing each take one constant-time scalar multiplication. That's done by noble, which also blinds the secret scalar.\n\nThe browser bundle is 50 KB minified, 19 KB gzipped.\n\n## Tests\n\n```sh\nyarn test\n```\n\nThe suite checks:\n\n- keys and signatures on 2,000 paths, against the [ed25519-bip32](https://docs.rs/ed25519-bip32/) crate that CIP-3 names as its reference implementation\n- the CIP-3 and RFC 8032 test vectors\n- `verify` against libsodium's verdicts, on the [ed25519-speccheck](https://github.com/novifinancial/ed25519-speccheck) vectors and a fuzz\n\nRun `yarn build` first and it also tests the build: it loads the package through Node's own ESM loader and through `require()`, and runs the browser bundle with no Node.js globals.\n\n## API docs\n\nThe full API reference is at [docs.strica.io/lib/bip32ed25519](https://docs.strica.io/lib/bip32ed25519).\n\n## Used by\n\n[Typhon Wallet](https://typhonwallet.io)\n\n# License\n\nCopyright 2021 Strica\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","readmeFilename":"README.md"}
![](\"https://docs.strica.io/images/logo.png\"){kind=logo}
\n \n