Expand BIP39 support, docs, and tests

Author: bitjson

.cspell.json

@@ -76,6 +76,7 @@
     "endianness",
     "EQUALVERIFY",
     "esnext",
+    "exfiltration",
     "FORKID",
     "FROMALTSTACK",
     "gitter",
@@ -90,6 +91,7 @@
     "Ints",
     "INVALIDOPCODE",
     "ipfs",
+    "Jaro",
     "LESSTHAN",
     "LESSTHANOREQUAL",
     "libauth",

.github/CONTRIBUTING.md

@@ -27,7 +27,7 @@ This library should provide the primitives needed to hack on bitcoin and bitcoin
 - **accept immutable, return mutable** - We should always return mutable types to allow consumers the option of mutating results without running afoul of type-checking. For the same reason, when we accept a value, we should generally avoid mutating it.
 - **use `eslint-disable-next-line` or `eslint-disable-line`** - It's ok to disable eslint; in some cases, rules should be disabled every time they're hit (e.g. `no-bitwise`). By using single-line disables, we clearly mark intentional deviations from our conventions.
 - **avoid Hungarian notation & name prefixing** – Including the type of a variable in its name is a code smell: a name should clearly describe only one concept, and types are the business of the type system. Likewise, using prefixes to distinguish between an interface and an instance typically indicates the concepts should be simplified. E.g. `IChecker` and `Checker` – this is likely made unnecessarily complex to accommodate an object-oriented style. Consider replacing with a single function (or if instantiation is required, an object containing only stateless functions).
-- **don't throw things** – instead, return a result that can be either a success or error type. This strategy encourages a more functional approach to problems, and pragmatically, [TypeScript does not yet offer a `throws` clause or otherwise](https://github.com/microsoft/TypeScript/issues/13219), so only this strategy allows errors to be well-typed. A good pattern is `() => string | ResultType`, where ResultType is the desired output, and error messages are returned as a string. Consumers can easily use `typeof result === 'string'` to narrow the resulting type. When errors are more complex or `ResultType` is also a string, use an object with a `success` property, e.g. `() => { success: true, bytecode: Uint8Array } | { success: false, errors: ErrorType[] }`.
+- **don't throw things** – instead, return a result that can be either a success or error type. This strategy encourages a more functional approach to problems, and pragmatically, [TypeScript does not yet offer a `throws` clause or otherwise](https://github.com/microsoft/TypeScript/issues/13219), so only this strategy allows errors to be well-typed. A good pattern is `() => string | ResultType`, where ResultType is the desired output, and error messages are returned as a string. Consumers can easily use `typeof result === 'string'` to narrow the resulting type. When errors are more complex or `ResultType` is also a string, use an object with a `success` property, e.g. `() => string | { success: true, phrase: string }` or `() => { success: true, bytecode: Uint8Array } | { success: false, errors: ErrorType[] }`.
   - Exception: errors that can never happen during correct usage of a function may be either 1) detected by type checking or 2) thrown. For example, if a function always expects 32-byte Uint8Array inputs (like `encodeCashAddress`), an incorrectly sized Uint8Array implies incorrect usage of the function by the implementing application. Such implementation errors should ideally be detected at development time and never occur at runtime.
 - **test the import** – when importing modules within the library, aim to import from a sibling or a sibling of the closest mutual parent module (this helps to avoid import cycles), rather than importing from a higher-level export (like `lib.ts`). When importing modules within test files, always import directly from the top-level `lib.ts` file – this ensures that intended public functionality is available and working as expected. (Note: this is also enforced by our eslint configuration.)
 - **try the formatting utilities** – especially when writing tests for large, complex objects, the `stringify` and `stringifyTestVector` utilities can save you a lot of time.

.github/workflows/ci.yaml

@@ -5,9 +5,12 @@ jobs:
   build-and-test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        node: [18, latest]
-    name: Test Node ${{ matrix.node }}
+        node: [18, 20, latest]
+        runner_index: [0, 1, 2, 3]
+        runners_per_version: [4]
+    name: Test Node ${{ matrix.node }} (${{ matrix.runner_index }}/${{ matrix.runners_per_version }})
     steps:
       - uses: actions/checkout@v4
         with:
@@ -17,24 +20,11 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
       - run: yarn install --immutable --immutable-cache
-      - run: yarn test
-
-  build-and-test-with-coverage:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node: [20]
-    name: Test Node ${{ matrix.node }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: 'recursive'
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node }}
-      - run: yarn install --immutable --immutable-cache
-      - run: yarn test
+      - run: yarn build
+      - run: yarn test:unit
+        env:
+          CI_NODE_INDEX: ${{ matrix.runner_index }}
+          CI_NODE_TOTAL: ${{ matrix.runners_per_version }}
       - run: yarn cov:lcov
       - name: Upload test coverage
         uses: codecov/codecov-action@v4
@@ -43,8 +33,9 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true
 
-  check-yarn-cache:
+  check-policies:
     runs-on: ubuntu-latest
+    name: Check Policies
     steps:
       - name: Check out repository code
         uses: actions/checkout@v4
@@ -55,3 +46,5 @@ jobs:
         with:
           node-version: '20'
       - run: yarn install --immutable --immutable-cache --check-cache
+      - run: yarn build
+      - run: yarn test:policies

.pnp.cjs

@@ -55,6 +55,7 @@ These functions include:
 - `encodeBase58AddressFormat`
 - `encodeBech32`
 - `encodeBip39Mnemonic`
+- `encodeBip39MnemonicNonStandard`
 - `encodeCashAddress`
 - `encodeCashAddressFormat`
 - `encodeCashAddressNonStandard`
@@ -95,6 +96,7 @@ The `decode*` utility functions include:
 - `decodeBase58AddressFormat`
 - `decodeBech32`
 - `decodeBip39Mnemonic`
+- `decodeBip39MnemonicNonStandard`
 - `decodeBitcoinSignature`
 - `decodeCashAddress`
 - `decodeCashAddressFormat`

.yarn

@@ -51,7 +51,8 @@
     "gen:schema-TODO": "//TODO: use ajv compile --code-esm option after merge: https://github.com/ajv-validator/ajv-cli/pull/200",
     "gen:templates": "yarn build && node 'build/lib/transaction/fixtures/generate-templates.spec.helper.js' 'p2pkh' > src/lib/transaction/fixtures/templates/p2pkh.json && node 'build/lib/transaction/fixtures/generate-templates.spec.helper.js' '2-of-3' > src/lib/transaction/fixtures/templates/2-of-3.json && node 'build/lib/transaction/fixtures/generate-templates.spec.helper.js' '2-of-2-recoverable' > src/lib/transaction/fixtures/templates/2-of-2-recoverable.json && node 'build/lib/transaction/fixtures/generate-templates.spec.helper.js' 'sig-of-sig' > src/lib/transaction/fixtures/templates/sig-of-sig.json && node 'build/lib/transaction/fixtures/generate-templates.spec.helper.js' 'cash-channels-v1' > src/lib/transaction/fixtures/templates/cash-channels-v1.json && prettier 'src/lib/transaction/fixtures/templates/*.json' --write",
     "gen:graph": "mkdir -p temp && madge --image temp/deps-$(date +\"%FT%H%M\").svg build/index.js",
-    "test": "yarn build && yarn test:deps && yarn test:schemas && yarn test:lint && yarn test:cycles && yarn test:unit",
+    "test": "yarn build && yarn test:policies && yarn test:unit",
+    "test:policies": "yarn test:deps && yarn test:schemas && yarn test:lint && yarn test:cycles",
     "test:deps": "node -e \"import('./package.json', { assert: { type: 'json' } }).then(p => typeof p.dependencies === 'undefined' ? console.log('No dependencies found.') : (console.error('Dependencies are not allowed.') && process.exit(1)));\"",
     "test:schemas:unchanged": "yarn gen:schema && node -e \"child_process.exec('git status src/lib/schema --porcelain | head -c1 | wc -c', (err, stdout) => stdout.trim() === '0' ? process.exit(0) : process.exit(1) )\"",
     "test:schemas": "yarn test:schemas:unchanged && echo \"Schemas are up to date.\" || echo \"Error: one or more schemas are outdated. Please review and commit the changes in src/lib/schema.\"",
@@ -61,6 +62,7 @@
     "test:spelling": "cspell \"{README.md,.github/*.md,src/**/*.ts}\"",
     "test:cycles": "madge --circular build/index.js",
     "test:unit": "c8 ava",
+    "test:fast": "echo '\n\nUsage:\n yarn test:fast src/lib/key/bip39.spec.ts                    # run a single test file \n yarn test:fast --match=\"!*crypto*\" --match=\"!*vmb_tests*\"   # include/exclude tests with names matching pattern(s) \n\n' && ava -v",
     "test:unit:script_tests": "c8 ava --match='*[script_tests]*' --serial",
     "test:unit:vmb_tests": "c8 ava src/lib/vmb-tests/bch-vmb-tests.spec.ts --serial",
     "test:unit:vmb_test": "node 'build/lib/vmb-tests/bch-vmb-test.spec.helper.js'",
@@ -69,7 +71,7 @@
     "bench:test": "ava --config .ava.bench.config.js --serial --timeout=2m 2>&1 | tee bench.log",
     "bench:browser-deps": "cpy '.yarn/artifacts/*.js' build/bench",
     "watch": "yarn build -w",
-    "watch:test": "echo 'Usage: yarn watch:test --match=\"*pattern*\"' && ava -v --watch",
+    "watch:test": "echo '\n\nUsage:\n yarn watch:test src/lib/key/bip39.spec.ts                    # watch a single test file \n yarn watch:test --match=\"!*crypto*\" --match=\"!*vmb_tests*\"   # include/exclude tests with names matching pattern(s) \n\n' && ava -v --watch",
     "cov": "yarn build && yarn test:unit && yarn cov:html && yarn cov:lcov && open-cli coverage/index.html",
     "cov:html": "c8 report --reporter=html",
     "cov:lcov": "c8 report --reporter=lcov",
@@ -107,6 +109,7 @@
     "ajv-cli": "^5.0.0",
     "asmcrypto.js": "^2.3.2",
     "ava": "^6.0.1",
+    "bip39": "^3.1.0",
     "bitcore-lib-cash": "^10.0.23",
     "c8": "^9.0.0",
     "chuhai": "^1.2.0",
@@ -147,17 +150,18 @@
     "SECURITY.md"
   ],
   "ava": {
-    "timeout": "20s",
+    "timeout": "60s",
     "typescript": {
       "compile": false,
       "rewritePaths": {
         "src/": "build/"
       }
     },
     "nodeArguments": [
-      "--experimental-json-modules"
-    ],
-    "workerThreads": false
+      "--experimental-json-modules",
+      "--experimental-global-webcrypto",
+      "# ^ needed for node v18"
+    ]
   },
   "config": {
     "commitizen": {
@@ -198,7 +202,8 @@
       "**/*.bench.js",
       "**/*.spec.js",
       "**/*.spec.helper.js",
-      ".pnp.*"
+      ".pnp.*",
+      "**/ajv/validate-*.js"
     ]
   },
   "sideEffects": false,

docs/encodings-and-formats.md

@@ -685,6 +685,18 @@ export enum CashAddressCorrectionError {
   tooManyErrors = 'This address has more than 2 errors and cannot be corrected.',
 }
 
+export type CashAddressCorrection = {
+  /**
+   * The corrected address in CashAddressFormat (including the prefix).
+   */
+  address: string;
+  /**
+   * An array of up to two numbers (in ascending order) indicating the index of
+   * each corrected character within the corrected address.
+   */
+  corrections: [] | [number, number] | [number];
+};
+
 /**
  * Attempt to correct up to 2 errors in a CashAddress. The CashAddress must be
  * properly formed (include a prefix and only contain Bech32 characters).
@@ -730,7 +742,7 @@ export const attemptCashAddressFormatErrorCorrection = (address: string) => {
     return {
       address: cashAddressPolynomialToCashAddress(polynomial),
       corrections: [],
-    };
+    } as CashAddressCorrection;
   }
 
   const syndromes: { [index: string]: number } = {};
@@ -752,7 +764,7 @@ export const attemptCashAddressFormatErrorCorrection = (address: string) => {
         return {
           address: cashAddressPolynomialToCashAddress(polynomial),
           corrections: [term],
-        };
+        } as CashAddressCorrection;
       }
       // eslint-disable-next-line no-bitwise
       const s0 = (BigInt(correct) ^ BigInt(originalChecksum)).toString();
@@ -778,7 +790,7 @@ export const attemptCashAddressFormatErrorCorrection = (address: string) => {
       return {
         address: cashAddressPolynomialToCashAddress(polynomial),
         corrections: [correctionIndex1, correctionIndex2].sort((a, b) => a - b),
-      };
+      } as CashAddressCorrection;
     }
   }
 

package.json

@@ -27,11 +27,9 @@ export const instantiateRustWasm = async (
          * Since `__wbindgen_malloc` isn't exposed to consumers, this error
          * can only be encountered if the code below is broken.
          */
+        /* c8 ignore next 10 */
         // eslint-disable-next-line camelcase, @typescript-eslint/naming-convention
-        __wbindgen_throw: /* istanbul ignore next */ (
-          ptr: number,
-          len: number,
-        ) => {
+        __wbindgen_throw: (ptr: number, len: number) => {
           // eslint-disable-next-line functional/no-throw-statements
           throw new Error(
             // eslint-disable-next-line @typescript-eslint/no-use-before-define

src/lib/address/cash-address.ts

@@ -232,7 +232,8 @@ const isLittleEndian = (buffer: ArrayBuffer): boolean => {
   heap32[0] = 1668509029;
   heap16[1] = 25459;
   return heapU8[2] !== 115 || heapU8[3] !== 99
-    ? /* istanbul ignore next */ notLittleEndian
+    ? /* c8 ignore next */
+      notLittleEndian
     : littleEndian;
 };
 
@@ -266,7 +267,7 @@ export const instantiateSecp256k1WasmBytes = async (
     maximum: TOTAL_MEMORY / WASM_PAGE_SIZE,
   });
 
-  /* istanbul ignore if  */
+  /* c8 ignore next 9 */
   if (!isLittleEndian(wasmMemory.buffer)) {
     /*
      * note: this block is excluded from test coverage. It's A) hard to test
@@ -308,34 +309,32 @@ export const instantiateSecp256k1WasmBytes = async (
   const env = {
     DYNAMICTOP_PTR,
     STACKTOP,
-    ___setErrNo: /* istanbul ignore next */ (value: number) => {
+    /* c8 ignore start */
+    ___setErrNo: (value: number) => {
       if (getErrNoLocation !== undefined) {
         heap32[getErrNoLocation() >> 2] = value;
       }
       return value;
     },
-    _abort: /* istanbul ignore next */ (err = 'Secp256k1 Error') => {
+    _abort: (err = 'Secp256k1 Error') => {
       throw new Error(err);
     },
     // eslint-disable-next-line camelcase
-    _emscripten_memcpy_big: /* istanbul ignore next */ (
-      dest: number,
-      src: number,
-      num: number,
-    ) => {
+    _emscripten_memcpy_big: (dest: number, src: number, num: number) => {
       heapU8.set(heapU8.subarray(src, src + num), dest);
       return dest;
     },
-    abort: /* istanbul ignore next */ (err = 'Secp256k1 Error') => {
+    abort: (err = 'Secp256k1 Error') => {
       throw new Error(err);
     },
-    abortOnCannotGrowMemory: /* istanbul ignore next */ () => {
+    abortOnCannotGrowMemory: () => {
       throw new Error('Secp256k1 Error: abortOnCannotGrowMemory was called.');
     },
-    enlargeMemory: /* istanbul ignore next */ () => {
+    enlargeMemory: () => {
       throw new Error('Secp256k1 Error: enlargeMemory was called.');
     },
     getTotalMemory: () => TOTAL_MEMORY,
+    /* c8 ignore stop */
   };
 
   const info = {