Begin implementation of BCH_2025_05 and BCH_SPEC

.changeset/sour-ties-allow.md

@@ -0,0 +1,9 @@
+---
+'@bitauth/libauth': patch
+---
+
+Begin implementation of BCH_2025_05 and BCH_SPEC
+
+- Revised `AuthenticationVirtualMachine` to remove `clone` (obviated by wide availability of `structuredClone`) and add `initialize`, allowing VM proposals to add to the program state of an existing VM (in a type-safe way) without duplicating its unchanged logic.
+- Clarified documentation around contributing upgrade proposals to Libauth VMs
+- Allow usage of any `BCH_SPEC` opcodes in `assembleBytecodeBch`/`disassembleBytecodeBch`

.vscode/launch.json

@@ -25,6 +25,29 @@
       "args": ["${file}"],
       "outputCapture": "std",
       "skipFiles": ["<node_internals>/**", "**/node_modules/**"]
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug VMB Test",
+      "runtimeExecutable": "yarn",
+      "runtimeArgs": ["run", "test:unit:vmb_test"],
+      "args": ["bch_spec_standard", "06ty9", "-v"],
+      "outputCapture": "std",
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "preLaunchTask": "npm: build"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug VMB Test Generation",
+      "runtimeExecutable": "yarn",
+      "runtimeArgs": ["run", "gen:vmb_tests"],
+      "outputCapture": "std",
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "preLaunchTask": "npm: build"
     }
   ]
 }

package.json

@@ -44,11 +44,11 @@
     "fix": "yarn fix:eslint && yarn fix:prettier",
     "fix:prettier": "prettier . --write",
     "fix:eslint": "yarn test:eslint --fix",
-    "gen:vmb-tests": "yarn build && yarn gen:vmb-tests:bch && yarn gen:vmb-tests-prettier",
-    "gen:vmb-tests-prettier": "prettier 'src/lib/vmb-tests/generated/**/*.json' --write",
-    "gen:vmb-tests:bch": "node 'build/lib/vmb-tests/bch-vmb-tests.spec.helper.js' 'src/lib/vmb-tests/generated/bch' && yarn run gen:vmb-tests:bch:reasons",
-    "gen:vmb-tests:bch:reasons": "node 'build/lib/vmb-tests/bch-vmb-tests-invalid.spec.helper.js'",
-    "wallet": "node 'build/lib/vmb-tests/bch-vmb-tests.live.spec.helper.js'",
+    "gen:vmb_tests": "yarn build && yarn gen:vmb_tests:bch && yarn gen:vmb_tests-prettier",
+    "gen:vmb_tests-prettier": "prettier 'src/lib/vmb-tests/generated/**/*.json' --write",
+    "gen:vmb_tests:bch": "node --enable-source-maps 'build/lib/vmb-tests/bch-vmb-tests.spec.helper.js' 'src/lib/vmb-tests/generated/bch' && yarn run gen:vmb_tests:bch:reasons",
+    "gen:vmb_tests:bch:reasons": "node --enable-source-maps 'build/lib/vmb-tests/bch-vmb-tests-invalid.spec.helper.js'",
+    "wallet": "node --enable-source-maps 'build/lib/vmb-tests/bch-vmb-tests.live.spec.helper.js'",
     "gen:schema": "yarn gen:schema:wallet-template && yarn gen:schema:bcmr",
     "gen:schema:wallet-template": "ts-json-schema-generator --no-ref-encode --path 'src/lib/engine/types/template-types.ts' --type 'WalletTemplate' > src/lib/schema/wallet-template.schema.json && prettier 'src/lib/schema/wallet-template.schema.json' --write && ajv compile -s src/lib/schema/wallet-template.schema.json --allowUnionTypes -o src/lib/schema/ajv/validate-wallet-template.js && prettier 'src/lib/schema/ajv/validate-wallet-template.js' --write && node -e \"const fs = require('fs'), path = 'src/lib/schema/ajv/validate-wallet-template.js'; fs.writeFileSync(path, fs.readFileSync(path, 'utf8').replace(/'use strict'[\\s\\S]*module.exports.default =/, 'export default'), 'utf8')\"",
     "gen:schema:bcmr": "ts-json-schema-generator --no-ref-encode --path 'src/lib/engine/types/bcmr-types.ts' --type 'MetadataRegistry' > src/lib/schema/bcmr.schema.json && prettier 'src/lib/schema/bcmr.schema.json' --write && ajv compile -s src/lib/schema/bcmr.schema.json --allowUnionTypes -o src/lib/schema/ajv/validate-bcmr.js && prettier 'src/lib/schema/ajv/validate-bcmr.js' --write && node -e \"const fs = require('fs'), path = 'src/lib/schema/ajv/validate-bcmr.js'; fs.writeFileSync(path, fs.readFileSync(path, 'utf8').replace(/'use strict'[\\s\\S]*module.exports.default =/, 'export default'), 'utf8')\"",
@@ -69,8 +69,8 @@
     "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'",
-    "dev:vmb_tests": "yarn gen:vmb-tests && yarn build:tsc && ava src/lib/vmb-tests/bch-vmb-tests.spec.ts --serial --fail-fast",
+    "test:unit:vmb_test": "node --enable-source-maps 'build/lib/vmb-tests/bch-vmb-test.spec.helper.js'",
+    "dev:vmb_tests": "yarn gen:vmb_tests && yarn build:tsc && ava src/lib/vmb-tests/bch-vmb-tests.spec.ts --serial --fail-fast",
     "bench": "yarn build && yarn bench:browser-deps && yarn bench:test",
     "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",

src/lib/compiler/compiler-utils.ts

@@ -26,7 +26,7 @@ import type {
 import {
   generateBytecodeMap,
   Opcodes,
-  OpcodesBch,
+  OpcodesBchSpec,
   OpcodesBtc,
 } from '../vm/vm.js';
 
@@ -258,7 +258,7 @@ export const assembleBytecode = (
  * @param disassembledBytecode - the disassembled BCH bytecode to re-assemble
  */
 export const assembleBytecodeBch = (disassembledBytecode: string) =>
-  assembleBytecode(generateBytecodeMap(OpcodesBch), disassembledBytecode);
+  assembleBytecode(generateBytecodeMap(OpcodesBchSpec), disassembledBytecode);
 /**
  * @deprecated Alias of `assembleBytecodeBch` for backwards-compatibility.
  */

src/lib/compiler/standard/p2pkh.ts

@@ -43,8 +43,15 @@ export const walletTemplateP2pkhNonHd: WalletTemplate = {
       unlocks: 'lock',
     },
   },
-  supported: ['BCH_2020_05', 'BCH_2021_05', 'BCH_2022_05'],
-  version: 0,
+  supported: [
+    'BCH_2020_05',
+    'BCH_2021_05',
+    'BCH_2022_05',
+    'BCH_2023_05',
+    'BCH_2024_05',
+    'BCH_2025_05',
+    'BCH_SPEC',
+  ],
 };
 
 /**
@@ -90,6 +97,13 @@ export const walletTemplateP2pkh: WalletTemplate = {
       unlocks: 'lock',
     },
   },
-  supported: ['BCH_2020_05', 'BCH_2021_05', 'BCH_2022_05'],
-  version: 0,
+  supported: [
+    'BCH_2020_05',
+    'BCH_2021_05',
+    'BCH_2022_05',
+    'BCH_2023_05',
+    'BCH_2024_05',
+    'BCH_2025_05',
+    'BCH_SPEC',
+  ],
 };

src/lib/engine/types/template-types.ts

@@ -110,6 +110,13 @@ export type AuthenticationVirtualMachineIdentifier =
   | 'BCH_2021_05'
   | 'BCH_2022_05'
   | 'BCH_2023_05'
+  | 'BCH_2024_05'
+  | 'BCH_2025_05'
+  | 'BCH_2026_05'
+  | 'BCH_2027_05'
+  | 'BCH_2028_05'
+  | 'BCH_2029_05'
+  | 'BCH_2030_05'
   | 'BCH_SPEC'
   | 'BSV_2020_02'
   | 'BSV_SPEC'

src/lib/language/language-utils.ts

@@ -21,6 +21,7 @@ import {
   authenticationInstructionIsMalformed,
   decodeAuthenticationInstructions,
   encodeAuthenticationInstructionMalformed,
+  executionIsActive,
   OpcodesBch,
   vmNumberToBigInt,
 } from '../vm/vm.js';
@@ -702,10 +703,6 @@ export const extractEvaluationSamplesRecursive = <ProgramState>({
   };
 };
 
-const stateIsExecuting = (
-  state: AuthenticationProgramStateControlStack<boolean | number>,
-) => state.controlStack.every((item) => item !== false);
-
 /**
  * Extract an array of ranges that were unused by an evaluation. This is useful
  * in development tooling for fading out or hiding code that is unimportant to
@@ -735,7 +732,7 @@ const stateIsExecuting = (
  * executing), defaults to `1,1`
  */
 export const extractUnexecutedRanges = <
-  ProgramState extends AuthenticationProgramStateControlStack<boolean | number>,
+  ProgramState extends AuthenticationProgramStateControlStack,
 >(
   samples: EvaluationSample<ProgramState>[],
   evaluationBegins = '1,1',
@@ -752,10 +749,10 @@ export const extractUnexecutedRanges = <
       const precedingStateSkips =
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         precedingStateSkipsByEvaluation[currentEvaluationStartLineAndColumn]!;
-      const endsWithSkip = !stateIsExecuting(sample.state);
+      const endsWithSkip = !executionIsActive(sample.state);
       const sampleHasNoExecutedInstructions =
         endsWithSkip &&
-        sample.internalStates.every((group) => !stateIsExecuting(group.state));
+        sample.internalStates.every((group) => !executionIsActive(group.state));
       if (precedingStateSkips && sampleHasNoExecutedInstructions) {
         return {
           precedingStateSkipsByEvaluation: {

src/lib/mappings.spec.ts

@@ -59,9 +59,11 @@ import {
   OpcodeDescriptions,
   OpcodeDescriptionsBch,
   OpcodeDescriptionsBch2023,
+  OpcodeDescriptionsBchSpec,
   Opcodes,
   OpcodesBch,
   OpcodesBch2023,
+  OpcodesBchSpec,
   SigningSerializationType,
   SigningSerializationTypeBch,
 } from './lib.js';
@@ -80,7 +82,9 @@ type TypeTests =
   | AssertTypesEqual<TransactionBch, Transaction>
   | AssertTypesEqual<TransactionBch, TransactionCommon>
   | AssertTypesEqual<typeof ConsensusCommon, typeof ConsensusBch>
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
   | AssertTypesEqual<typeof OpcodeDescriptionsBch, typeof OpcodeDescriptions>
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
   | AssertTypesEqual<typeof OpcodesBch, typeof Opcodes>;
 /* eslint-enable @typescript-eslint/no-duplicate-type-constituents */
 
@@ -102,9 +106,9 @@ test('Libauth exposes all expected mappings', (t) => {
   t.deepEqual(decodeTransactionUnsafe, decodeTransactionUnsafeBch);
   t.deepEqual(encodeTransactionCommon, encodeTransactionBch);
   t.deepEqual(encodeTransaction, encodeTransactionBch);
-  t.deepEqual(OpcodeDescriptionsBch2023, OpcodeDescriptionsBch);
-  t.deepEqual(OpcodeDescriptionsBch, OpcodeDescriptions);
-  t.deepEqual(OpcodesBch2023, OpcodesBch);
-  t.deepEqual(Opcodes, OpcodesBch);
+  t.deepEqual(OpcodeDescriptionsBch, OpcodeDescriptionsBch2023);
+  t.deepEqual(OpcodeDescriptions, OpcodeDescriptionsBchSpec);
+  t.deepEqual(OpcodesBch, OpcodesBch2023);
+  t.deepEqual(Opcodes, OpcodesBchSpec);
   t.deepEqual(SigningSerializationType, SigningSerializationTypeBch);
 });

src/lib/schema/ajv/validate-wallet-template.js

@@ -11,6 +11,13 @@ const schema22 = {
         'BCH_2021_05',
         'BCH_2022_05',
         'BCH_2023_05',
+        'BCH_2024_05',
+        'BCH_2025_05',
+        'BCH_2026_05',
+        'BCH_2027_05',
+        'BCH_2028_05',
+        'BCH_2029_05',
+        'BCH_2030_05',
         'BCH_SPEC',
         'BSV_2020_02',
         'BSV_SPEC',
@@ -883,6 +890,13 @@ const schema42 = {
     'BCH_2021_05',
     'BCH_2022_05',
     'BCH_2023_05',
+    'BCH_2024_05',
+    'BCH_2025_05',
+    'BCH_2026_05',
+    'BCH_2027_05',
+    'BCH_2028_05',
+    'BCH_2029_05',
+    'BCH_2030_05',
     'BCH_SPEC',
     'BSV_2020_02',
     'BSV_SPEC',
@@ -6889,6 +6903,13 @@ function validate21(
                                   data27 === 'BCH_2021_05' ||
                                   data27 === 'BCH_2022_05' ||
                                   data27 === 'BCH_2023_05' ||
+                                  data27 === 'BCH_2024_05' ||
+                                  data27 === 'BCH_2025_05' ||
+                                  data27 === 'BCH_2026_05' ||
+                                  data27 === 'BCH_2027_05' ||
+                                  data27 === 'BCH_2028_05' ||
+                                  data27 === 'BCH_2029_05' ||
+                                  data27 === 'BCH_2030_05' ||
                                   data27 === 'BCH_SPEC' ||
                                   data27 === 'BSV_2020_02' ||
                                   data27 === 'BSV_SPEC' ||

src/lib/schema/wallet-template.schema.json

@@ -9,6 +9,13 @@
         "BCH_2021_05",
         "BCH_2022_05",
         "BCH_2023_05",
+        "BCH_2024_05",
+        "BCH_2025_05",
+        "BCH_2026_05",
+        "BCH_2027_05",
+        "BCH_2028_05",
+        "BCH_2029_05",
+        "BCH_2030_05",
         "BCH_SPEC",
         "BSV_2020_02",
         "BSV_SPEC",

src/lib/transaction/fixtures/template.2-of-2-recoverable.spec.helper.ts

@@ -102,5 +102,4 @@ export const twoOfTwoRecoverable: WalletTemplate = {
     },
   },
   supported: ['BCH_2021_05', 'BCH_2022_05'],
-  version: 0,
 };

src/lib/transaction/fixtures/template.2-of-3.spec.helper.ts

@@ -49,6 +49,11 @@ export const twoOfThree: WalletTemplate = {
         'OP_2\n<key1.public_key>\n<key2.public_key>\n<key3.public_key>\nOP_3\nOP_CHECKMULTISIG',
     },
   },
-  supported: ['BCH_2021_05', 'BCH_2022_05'],
-  version: 0,
+  supported: [
+    'BCH_2021_05',
+    'BCH_2022_05',
+    'BCH_2023_05',
+    'BCH_2024_05',
+    'BCH_2025_05',
+  ],
 };

src/lib/transaction/fixtures/template.cash-channels-v1.spec.helper.ts

@@ -248,5 +248,4 @@ export const cashChannels: WalletTemplate = {
     },
   },
   supported: ['BCH_2022_05'],
-  version: 0,
 };

src/lib/transaction/fixtures/template.sig-of-sig.spec.helper.ts

@@ -42,5 +42,4 @@ export const sigOfSig: WalletTemplate = {
     },
   },
   supported: ['BCH_2021_05', 'BCH_2022_05'],
-  version: 0,
 };

src/lib/transaction/fixtures/templates/2-of-2-recoverable.json

@@ -96,6 +96,5 @@
       "unlocks": "lock"
     }
   },
-  "supported": ["BCH_2021_05", "BCH_2022_05"],
-  "version": 0
+  "supported": ["BCH_2021_05", "BCH_2022_05"]
 }

src/lib/transaction/fixtures/templates/2-of-3.json

@@ -52,6 +52,11 @@
       "script": "OP_2\n<key1.public_key>\n<key2.public_key>\n<key3.public_key>\nOP_3\nOP_CHECKMULTISIG"
     }
   },
-  "supported": ["BCH_2021_05", "BCH_2022_05"],
-  "version": 0
+  "supported": [
+    "BCH_2021_05",
+    "BCH_2022_05",
+    "BCH_2023_05",
+    "BCH_2024_05",
+    "BCH_2025_05"
+  ]
 }

src/lib/transaction/fixtures/templates/cash-channels-v1.json

@@ -242,6 +242,5 @@
       }
     }
   },
-  "supported": ["BCH_2022_05"],
-  "version": 0
+  "supported": ["BCH_2022_05"]
 }

src/lib/transaction/fixtures/templates/p2pkh.json

@@ -28,6 +28,13 @@
       "unlocks": "lock"
     }
   },
-  "supported": ["BCH_2020_05", "BCH_2021_05", "BCH_2022_05"],
-  "version": 0
+  "supported": [
+    "BCH_2020_05",
+    "BCH_2021_05",
+    "BCH_2022_05",
+    "BCH_2023_05",
+    "BCH_2024_05",
+    "BCH_2025_05",
+    "BCH_SPEC"
+  ]
 }

src/lib/transaction/fixtures/templates/sig-of-sig.json

@@ -33,6 +33,5 @@
       "unlocks": "lock"
     }
   },
-  "supported": ["BCH_2021_05", "BCH_2022_05"],
-  "version": 0
+  "supported": ["BCH_2021_05", "BCH_2022_05"]
 }

src/lib/transaction/generate-transaction.spec.ts

@@ -42,7 +42,6 @@ const maybeP2pkhTemplate: unknown = {
     },
   },
   supported: ['BCH_2022_05'],
-  version: 0,
 };
 
 test('createCompilerBch: generateTransaction', (t) => {

src/lib/vm/instruction-sets/bch/2023/bch-2023-consensus.ts

@@ -1,6 +1,6 @@
 import {
   SigningSerializationTypeBch,
-  SigningSerializationTypesBch,
+  SigningSerializationTypesCommon,
 } from '../../common/common.js';
 
 /**
@@ -62,8 +62,8 @@ export enum ConsensusBch2023 {
 }
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
-export const SigningSerializationTypesBch2023 = [
-  ...SigningSerializationTypesBch,
+export const SigningSerializationTypesBch = [
+  ...SigningSerializationTypesCommon,
   SigningSerializationTypeBch.allOutputsAllUtxos,
   SigningSerializationTypeBch.correspondingOutputAllUtxos,
   SigningSerializationTypeBch.noOutputsAllUtxos,