@opcat-labs/scrypt-ts-opcat 2.0.2 → 2.1.0

package/dist/types/smart-contract/builtin-libs/genesis.d.ts

@@ -0,0 +1,252 @@
+import { SmartContract } from '../smartContract.js';
+import { FixedArray, TxOut } from '../types/index.js';
+import { ContractCall } from '../../psbt/types.js';
+/**
+ * Maximum number of inputs allowed during genesis deployment.
+ *
+ * ## Purpose
+ * Limits the number of inputs validated to prevent script size bloat while
+ * maintaining sufficient security coverage.
+ *
+ * ## Why 6?
+ * - **Typical deployments**: 1-3 inputs (Genesis UTXO + fee UTXOs)
+ * - **Edge case coverage**: Handles multi-input deployment scenarios
+ * - **Script size**: Each input check adds ~50 bytes; 6 is optimal balance
+ * - **Security**: Validates all inputs in normal cases
+ * - **sCrypt constraint**: Bitcoin Script loops must be unrolled at compile time
+ *
+ * ## Security Implications
+ * Transactions with more than 6 inputs will be **rejected by the contract**.
+ * This prevents attackers from hiding duplicate scriptHashes in unchecked input
+ * indices beyond the validation limit.
+ *
+ * @constant
+ * @see {@link Genesis.checkDeploy} - Uses this constant for input validation
+ * @category Genesis
+ */
+export declare const MAX_GENESIS_CHECK_INPUT = 6;
+/**
+ * Maximum number of outputs to check during genesis deployment.
+ *
+ * ## Purpose
+ * Limits the number of outputs validated during deployment to match input
+ * validation coverage and support typical deployment patterns.
+ *
+ * ## Usage Scenarios
+ * - **1 output**: Deploy single contract
+ * - **2-3 outputs**: Deploy contract + change outputs
+ * - **4-6 outputs**: Multi-contract deployment or complex output structures
+ *
+ * ## Validation Scope
+ * Only `output[0]` must be unique. Other outputs (1-5) can have duplicate
+ * scriptHashes as long as they differ from `output[0]`.
+ *
+ * @constant
+ * @see {@link Genesis.checkDeploy} - Uses this constant for output validation
+ * @see {@link MAX_GENESIS_CHECK_INPUT} - Corresponding input limit
+ * @category Genesis
+ */
+export declare const MAX_GENESIS_CHECK_OUTPUT = 6;
+/**
+ * Genesis contract for validating initial deployment outputs.
+ *
+ * ## Purpose
+ * The Genesis contract ensures that deployed contracts have unique scriptHashes,
+ * preventing duplicate deployments and establishing a verifiable deployment origin.
+ * It acts as a "genesis UTXO" that validates the first deployment of a contract.
+ *
+ * ## Deployment Validation Rules
+ * 1. **Genesis position**: Genesis must be unlocked at input index 0
+ * 2. **Output uniqueness**: Contract at `output[0]` must have unique scriptHash among all outputs
+ * 3. **Input differentiation**: Contract at `output[0]` must differ from all input scriptHashes
+ * 4. **Input limit**: Transaction must have ≤ {@link MAX_GENESIS_CHECK_INPUT} inputs
+ * 5. **Output limit**: Transaction must specify ≤ {@link MAX_GENESIS_CHECK_OUTPUT} outputs
+ *
+ * ## Why output[0]?
+ * Only `output[0]` requires uniqueness validation. This design allows:
+ * - Deploying the **primary contract** at output[0] with guaranteed uniqueness
+ * - Including **auxiliary contracts** or **change outputs** at indices 1-5
+ * - **Multi-output deployments** where only the main contract needs uniqueness
+ *
+ * ## Empty Placeholders
+ * When fewer than {@link MAX_GENESIS_CHECK_OUTPUT} outputs exist, use empty
+ * placeholders (scriptHash = empty ByteString) for unused slots. These are
+ * ignored during validation.
+ *
+ * @example
+ * **Basic single contract deployment:**
+ * ```typescript
+ * import { Genesis, genesisCheckDeploy } from '@opcat-labs/scrypt-ts-opcat';
+ * import { ExtPsbt } from '@opcat-labs/scrypt-ts-opcat';
+ *
+ * // 1. Create and bind Genesis contract
+ * const genesis = new Genesis();
+ * genesis.bindToUtxo(genesisUtxo);
+ *
+ * // 2. Create the contract to deploy
+ * const minter = new CAT20Minter(...);
+ *
+ * // 3. Build deployment transaction
+ * const psbt = new ExtPsbt({ network })
+ *   .addContractInput(genesis, genesisCheckDeploy()) // Genesis validates deployment
+ *   .addContractOutput(minter, 1000n)                 // Deploy at output[0]
+ *   .change(changeAddress, feeRate)
+ *   .seal();
+ *
+ * // 4. Finalize and broadcast
+ * await psbt.finalizeAllInputs();
+ * const txid = await psbt.broadcast();
+ * console.log(`Contract deployed at ${txid}:0`);
+ * ```
+ *
+ * @category Contract
+ * @category Genesis
+ * @see {@link genesisCheckDeploy} - Helper function for easier deployment
+ * @see {@link MAX_GENESIS_CHECK_INPUT} - Maximum inputs validated
+ * @see {@link MAX_GENESIS_CHECK_OUTPUT} - Maximum outputs validated
+ * @onchain
+ */
+export declare class Genesis extends SmartContract {
+    constructor();
+    /**
+     * Validates the deployment transaction outputs.
+     *
+     * ## Validation Process
+     * This method performs a **two-phase validation**:
+     *
+     * **Phase 1: Output Serialization & Uniqueness** (lines 168-183)
+     * - Iterates through all outputs up to MAX_GENESIS_CHECK_OUTPUT
+     * - Serializes valid outputs (index < outputCount) for context matching
+     * - Validates `output[0]` scriptHash is unique among all outputs
+     * - Ensures no duplicate contracts are deployed in a single transaction
+     *
+     * **Phase 2: Input Differentiation** (lines 185-195)
+     * - Checks `output[0]` differs from all input scriptHashes
+     * - Prevents redeployment attacks using existing contract UTXOs
+     * - Validates only inputs within MAX_GENESIS_CHECK_INPUT limit
+     *
+     * ## Why Two Separate Loops?
+     * 1. **Output loop**: Dual-purpose (serialize + validate uniqueness)
+     * 2. **Input loop**: Independent validation after outputs are processed
+     * 3. **sCrypt constraint**: Loops must be unrolled at compile time
+     *
+     * @param outputs - Fixed array of 6 outputs; fill unused slots with empty placeholders
+     * @param outputCount - Number of actual outputs (1-6); outputs beyond this are ignored
+     *
+     * @throws {Error} 'Genesis must be unlocked at input index 0' - Genesis not at input 0
+     * @throws {Error} 'Too many inputs to validate' - More than MAX_GENESIS_CHECK_INPUT inputs
+     * @throws {Error} 'Invalid outputCount' - outputCount out of range [1, 6]
+     * @throws {Error} 'Output scriptHash must be non-empty' - Empty scriptHash in valid output
+     * @throws {Error} 'output[0] must be unique among all outputs' - Duplicate scriptHash in outputs
+     * @throws {Error} 'output[0] must differ from all input scriptHashes' - Matches an input
+     * @throws {Error} 'Outputs mismatch with the transaction context' - Serialization mismatch
+     *
+     * @example
+     * ```typescript
+     * // Advanced: Direct method call (most users should use genesisCheckDeploy helper)
+     * const genesis = new Genesis();
+     * genesis.bindToUtxo(genesisUtxo);
+     *
+     * // Create output array with empty placeholders
+     * const outputs: TxOut[] = [
+     *   { scriptHash: sha256(contractScript), satoshis: 1000n, dataHash: sha256('') },
+     *   ...fill({ scriptHash: toByteString(''), satoshis: 0n, dataHash: sha256('') }, 5)
+     * ];
+     *
+     * await genesis.methods.checkDeploy(
+     *   outputs as FixedArray<TxOut, 6>,
+     *   1n // Only 1 real output, rest are placeholders
+     * );
+     * ```
+     *
+     * @see {@link genesisCheckDeploy} - Helper function for easier usage
+     * @see {@link MAX_GENESIS_CHECK_INPUT} - Maximum inputs validated
+     * @see {@link MAX_GENESIS_CHECK_OUTPUT} - Maximum outputs validated
+     * @onchain
+     */
+    checkDeploy(outputs: FixedArray<TxOut, typeof MAX_GENESIS_CHECK_OUTPUT>, outputCount: bigint): void;
+}
+/**
+ * Creates a contract call function for Genesis.checkDeploy that automatically
+ * builds the TxOut array from transaction outputs.
+ *
+ * ## What it does
+ * This helper function simplifies Genesis deployment by:
+ * 1. **Extracting outputs** from the PSBT transaction
+ * 2. **Computing hashes** (scriptHash and dataHash) for each output
+ * 3. **Creating placeholders** for unused output slots (up to 6 total)
+ * 4. **Invoking checkDeploy** with properly formatted parameters
+ *
+ * ## When to use
+ * - **Recommended**: Use this helper when building deployment transactions with ExtPsbt
+ * - **Advanced**: Call {@link Genesis.checkDeploy} directly for manual control
+ *
+ * ## Output Handling
+ * - Processes up to {@link MAX_GENESIS_CHECK_OUTPUT} (6) outputs
+ * - Automatically limits `outputCount` via `Math.min(txOutputs.length, 6)`
+ * - Fills unused slots with empty placeholders (scriptHash = empty ByteString)
+ *
+ * @returns A ContractCall function compatible with ExtPsbt.addContractInput
+ *
+ * @example
+ * **Basic single contract deployment:**
+ * ```typescript
+ * import { Genesis, genesisCheckDeploy } from '@opcat-labs/scrypt-ts-opcat';
+ * import { ExtPsbt } from '@opcat-labs/scrypt-ts-opcat';
+ *
+ * // 1. Setup Genesis contract
+ * const genesis = new Genesis();
+ * genesis.bindToUtxo(genesisUtxo);
+ *
+ * // 2. Create contract to deploy
+ * const minter = new CAT20Minter(...);
+ *
+ * // 3. Build deployment transaction
+ * const psbt = new ExtPsbt({ network })
+ *   .addContractInput(genesis, genesisCheckDeploy())  // Genesis validates
+ *   .addContractOutput(minter, 1000n)                  // Deploy at output[0]
+ *   .change(changeAddress, feeRate)                    // Change output
+ *   .seal();
+ *
+ * // 4. Finalize and broadcast
+ * await psbt.finalizeAllInputs();
+ * const txid = await psbt.broadcast();
+ * console.log(`Contract deployed at ${txid}:0`);
+ * ```
+ *
+ * @example
+ * **Multi-output deployment:**
+ * ```typescript
+ * // Deploy primary contract + auxiliary contracts
+ * const psbt = new ExtPsbt({ network })
+ *   .addContractInput(genesis, genesisCheckDeploy())
+ *   .addContractOutput(primaryContract, 2000n)    // output[0] - must be unique
+ *   .addContractOutput(helperContract, 1000n)     // output[1] - can match output[2+]
+ *   .addContractOutput(anotherHelper, 1000n)      // output[2] - can match output[1]
+ *   .change(changeAddress, feeRate)
+ *   .seal();
+ * ```
+ *
+ * @example
+ * **Error handling:**
+ * ```typescript
+ * try {
+ *   const psbt = new ExtPsbt({ network })
+ *     .addContractInput(genesis, genesisCheckDeploy())
+ *     .addContractOutput(contract1, 1000n)  // output[0]
+ *     .addContractOutput(contract1, 1000n)  // ❌ Same as output[0] - will fail!
+ *     .seal();
+ *   await psbt.finalizeAllInputs();
+ *   await psbt.broadcast();
+ * } catch (error) {
+ *   // Error: output[0] must be unique among all outputs
+ *   console.error('Deployment failed:', error.message);
+ * }
+ * ```
+ *
+ * @category Genesis
+ * @see {@link Genesis.checkDeploy} - The underlying contract method
+ * @see {@link MAX_GENESIS_CHECK_OUTPUT} - Maximum outputs validated
+ */
+export declare function genesisCheckDeploy(): ContractCall<Genesis>;
+//# sourceMappingURL=genesis.d.ts.map

package/dist/types/smart-contract/builtin-libs/genesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"genesis.d.ts","sourceRoot":"","sources":["../../../../src/smart-contract/builtin-libs/genesis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBACa,OAAQ,SAAQ,aAAa;;IAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuDG;IAEI,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,wBAAwB,CAAC,EAAE,WAAW,EAAE,MAAM;CAyEpG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAAC,OAAO,CAAC,CAwC1D"}

package/dist/types/smart-contract/builtin-libs/index.d.ts

@@ -5,4 +5,5 @@ export { StdUtils } from './stdUtils.js';
 export { Backtrace, type ChainTxVerifyResponse } from './backtrace.js';
 export { StateLib } from './stateLib.js';
 export { TxHashPreimageUtils } from './txHashPreimageUtils.js';
+export { Genesis, MAX_GENESIS_CHECK_OUTPUT, genesisCheckDeploy } from './genesis.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/smart-contract/builtin-libs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/smart-contract/builtin-libs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/smart-contract/builtin-libs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/types/smart-contract/smartContract.d.ts

@@ -43,12 +43,32 @@ export declare class SmartContract<StateT extends OpcatState = undefined> extend
      * @ignore
      */
     getStateType(): string | undefined;
+    /**
+     * Get the data of the contract.
+     * @returns the data of the contract
+     */
+    get data(): ByteString;
+    /**
+     * Set the data of the contract.
+     * Only stateless contracts (without stateType) can set data.
+     * Stateful contracts should use the state property instead.
+     * @param value the data to set
+     */
+    set data(value: ByteString);
     utxo?: ExtUtxo;
     /**
      * The state of the contract UTXO, usually committed to the first OP_RETURN output, is revealed when spending.
      * @onchain
      */
     state: StateT;
+    /**
+     * Raw data for stateless contracts (contracts without stateType).
+     * For stateful contracts, use the `state` property instead.
+     * Access this field through the `data` getter/setter.
+     * @private
+     * @onchain
+     */
+    private _data;
     private contractHeader;
     /**
      * Locking script corresponding to the SmartContract

package/dist/types/smart-contract/smartContract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smartContract.d.ts","sourceRoot":"","sources":["../../../src/smart-contract/smartContract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"smartContract.d.ts","sourceRoot":"","sources":["../../../src/smart-contract/smartContract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opcat-labs/scrypt-ts-opcat",
   "description": "A TypeScript library for building OPCAT smart contracts with sCrypt.",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "author": "OP_CAT Labs",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -31,8 +31,9 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "npm run test:local",
+    "test": "npm run test:local && npm run test:dist",
     "test:local": "cross-env DUMMY_PROVIDER=1 mocha",
+    "test:dist": "node test-esm/test.mjs && node test-cjs/test.cjs",
     "test:testnet": "cross-env NETWORK=opcat-testnet mocha --timeout=0 --jobs=1",
     "test:mainnet": "cross-env NETWORK=opcat-mainnet mocha --timeout=0 --jobs=1",
     "build:cjs": "tsc -p tsconfig.cjs.json",
@@ -40,6 +41,7 @@
     "build:esm": "tsc -p tsconfig.esm.json",
     "build": "yarn run build:cjs && yarn run build:esm",
     "gen:assets": "tspc -p tsconfig.assets.json && node injectAsm.cjs",
+    "gen:contract": "tsx scripts/genContract.ts",
     "prebuild": "yarn run clean",
     "beta": "yarn publish  --tag beta  --access public",
     "genkey": "tsx test/utils/privateKey.ts",
@@ -66,7 +68,7 @@
   },
   "dependencies": {
     "@noble/curves": "^1.8.1",
-    "@opcat-labs/opcat": "2.0.2",
+    "@opcat-labs/opcat": "2.1.0",
     "bip174": "^3.0.0-rc.1",
     "cbor2": "^2.0.1",
     "cross-fetch": "^4.1.0",

package/scrypt.index.json

@@ -69,6 +69,10 @@
       "symbol": "StateLib",
       "path": "smart-contract/builtin-libs/stateLib.scrypt.tpl"
     },
+    {
+      "symbol": "Genesis",
+      "path": "smart-contract/builtin-libs/genesis.scrypt.tpl"
+    },
     {
       "symbol": "P2PK",
       "path": "smart-contract/builtin-libs/p2pk.scrypt.tpl"

package/src/smart-contract/builtin-libs/backtrace.ts

@@ -1,11 +1,11 @@
-import { method } from '../decorators.js';
+import { method, prop } from '../decorators.js';
 import { assert } from '../fns/assert.js';
 import { SmartContractLib } from '../smartContractLib.js';
 import { ByteString } from '../types/index.js';
 import { BacktraceInfo, Prevouts, TxHashPreimage } from '../types/structs.js';
 import { TxUtils } from './txUtils.js';
 import { TX_INPUT_BYTE_LEN, TX_OUTPUT_BYTE_LEN, TX_OUTPUT_SATOSHI_BYTE_LEN, TX_OUTPUT_SCRIPT_HASH_LEN } from '../consts.js';
-import { slice } from '../fns/byteString.js';
+import { slice, toByteString } from '../fns/byteString.js';
 import { StdUtils } from './stdUtils.js';
 import { TxHashPreimageUtils } from './txHashPreimageUtils.js';
 
@@ -25,6 +25,25 @@ export type ChainTxVerifyResponse = {
  * @onchain
  */
 export class Backtrace extends SmartContractLib {
+  /**
+   * SHA256 hash of the Genesis contract script (including header).
+   * Used to validate that prevPrevScript is the Genesis contract when tracing back to genesis outpoint.
+   *
+   * ## How this hash is generated
+   * This is the SHA256 hash of the Genesis contract's full locking script, including:
+   * - Contract header (name, version metadata)
+   * - Compiled bytecode
+   *
+   * To verify or regenerate: `sha256(toByteString(new Genesis().lockingScript.toHex()))`
+   *
+   * ## Important
+   * If the Genesis contract is updated, this hash MUST be updated accordingly.
+   * Use the test in genesis.test.ts to verify this hash remains correct.
+   *
+   * @see packages/scrypt-ts-opcat/test/local-test/genesis.test.ts - GENESIS_SCRIPT_HASH validation tests
+   */
+  @prop()
+  static readonly GENESIS_SCRIPT_HASH: ByteString = toByteString('8f6157664f8f7cd43e6bba7f3209bb803d4d0fb2fb6e59fdc548989ed3901f15');
 
   /**
    * Verifies that the transaction hash preimage matches the previous transaction hash 
@@ -47,6 +66,37 @@ export class Backtrace extends SmartContractLib {
   /**
    * Back-to-genesis backtrace verification for a contract which can be backtraced to the genesis outpoint.
    * It will be a valid backtraceInfo if the prevPrevOutpoint is the genesis outpoint or the prevPrevScript is the selfScript.
+   *
+   * ## Multiple Genesis Support
+   * A single transaction can create multiple Genesis outputs at different indices (output[0], output[1], etc.).
+   * Each Genesis output can be spent separately to deploy a different contract, with each contract having
+   * its own unique genesisOutpoint. This allows batch creation of Genesis contracts in one transaction
+   * while maintaining independent contract lineages.
+   *
+   * ```
+   *                         Genesis Creation Tx
+   *                        +-------------------+
+   *                        |    output[0]      |---> Genesis_0 (outpoint: txid:0)
+   *   UTXOs -------------->|    output[1]      |---> Genesis_1 (outpoint: txid:1)
+   *                        |    output[2]      |---> Genesis_2 (outpoint: txid:2)
+   *                        +-------------------+
+   *                                 |
+   *          +----------------------+----------------------+
+   *          |                      |                      |
+   *          v                      v                      v
+   *   +-------------+        +-------------+        +-------------+
+   *   | Deploy Tx A |        | Deploy Tx B |        | Deploy Tx C |
+   *   +-------------+        +-------------+        +-------------+
+   *   | spend Gen_0 |        | spend Gen_1 |        | spend Gen_2 |
+   *   | output[0]:  |        | output[0]:  |        | output[0]:  |
+   *   | Contract_A  |        | Contract_B  |        | Contract_C  |
+   *   +-------------+        +-------------+        +-------------+
+   *          |                      |                      |
+   *          v                      v                      v
+   *   genesisOutpoint:       genesisOutpoint:       genesisOutpoint:
+   *      txid:0                 txid:1                 txid:2
+   * ```
+   *
    * @param backtraceInfo backtrace info to verify, including prevTx and prevPrevTx informations
    * @param t_genesisOutpoint expected genesis outpoint of the contract which usually is a contract property and trustable
    * @param t_selfScript expected self locking script, i.e. this.ctx.spentScript, of the currect spending UTXO context which is trustable
@@ -60,6 +110,13 @@ export class Backtrace extends SmartContractLib {
     t_prevTxInputList: ByteString,
   ): void {
     const res = Backtrace.verifyChainTxs(backtraceInfo, t_prevTxInputList);
+    // When at genesis outpoint, verify the prevPrevScript (scriptHash) matches the Genesis contract
+    if (res.prevPrevOutpoint === t_genesisOutpoint) {
+      assert(
+        res.prevPrevScript == Backtrace.GENESIS_SCRIPT_HASH,
+        `prevPrevScript does not match Genesis contract script`,
+      );
+    }
     assert(
       res.prevPrevOutpoint === t_genesisOutpoint || res.prevPrevScript == t_selfScript,
       `can not backtrace to the genesis outpoint`,
@@ -104,17 +161,19 @@ export class Backtrace extends SmartContractLib {
     // check if the passed prevTxInput and prevTxInputIndexVal are matched
     assert(
       slice(
-        t_prevTxInputList, 
+        t_prevTxInputList,
         backtraceInfo.prevTxInputIndex * TX_INPUT_BYTE_LEN,
         (backtraceInfo.prevTxInputIndex + 1n) * TX_INPUT_BYTE_LEN
       ) ==
       TxUtils.mergeInput(backtraceInfo.prevTxInput),
+      'prevTxInput does not match prevTxInputList at specified index',
     );
     // check if prevTxHash of passed prevTxInput and prevPrevTx are matched
     const prevPrevTxHash = backtraceInfo.prevTxInput.prevTxHash;
     assert(
       prevPrevTxHash ==
         TxHashPreimageUtils.getTxHashFromTxHashPreimage(backtraceInfo.prevPrevTxPreimage),
+      'prevPrevTxHash mismatch: prevTxInput.prevTxHash does not match prevPrevTxPreimage hash',
     );
     // all fields in backtraceInfo have been verified
     const prevPrevScript =