bitcoin-util: Add evalscript subcommand #35788

Adds an evalscript subcommand for using bitcoin's consensus logic to evaluate script fragments. Intended for debugging and development.

Examples:

# check a script fragment's behaviour
$ bitcoin-util evalscript '1 2 ADD'
{
  "script": {
    "asm": "1 2 OP_ADD",
    "hex": "515293",
    "type": "nonstandard"
  },
  "sigversion": "witness_v0",
  "script_flags": [
    "CHECKLOCKTIMEVERIFY",
    "CHECKSEQUENCEVERIFY",
    "DERSIG",
    "NULLDUMMY",
    "P2SH",
    "TAPROOT",
    "WITNESS"
  ],
  "dummy_sig_checker": true,
  "stack_after": [
    "03"
  ],
  "sigop_cost": 0,
  "success": true
}

# validate a real signature
$ bitcoin-util -sigversion=base \
    -spentoutput=00f2052a0100000043410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3ac \
    -tx=0100000001c997a5e56e104102fa209c6a852dd90660a20b2d9c352423edce25857fcd3704000000004847304402204e45e16932b8af514961a1d3a1a25fdf3f4f7732e9d624c6c61548ab5fb8cd410220181522ec8eca07de4860a4acdd12909d831cc56cbbac4622082221a8768d1d0901ffffffff0200ca9a3b00000000434104ae1a62fe09c5f51b13905f07f06b99a2f7159b2225f374cd378d71302fa28414e7aab37397f554a7df5f142c21c1b7303b8a0626f1baded5c72a704f7e6cd84cac00286bee0000000043410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3ac00000000 \
    evalscript '0x410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3 CHECKSIG' \
    '304402204e45e16932b8af514961a1d3a1a25fdf3f4f7732e9d624c6c61548ab5fb8cd410220181522ec8eca07de4860a4acdd12909d831cc56cbbac4622082221a8768d1d0901'
{
  "script": {
    "asm": "0411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3 OP_CHECKSIG",
    "hex": "410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3ac",
    "type": "pubkey"
  },
  "sigversion": "base",
  "script_flags": [
    "CHECKLOCKTIMEVERIFY",
    "CHECKSEQUENCEVERIFY",
    "DERSIG",
    "NULLDUMMY",
    "P2SH",
    "TAPROOT",
    "WITNESS"
  ],
  "dummy_sig_checker": false,
  "stack_after": [
    "01"
  ],
  "sigop_cost": 4,
  "success": true
}

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35788.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process.

If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #29247 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/29247.svg">} (CAT in Tapscript (BIP-347) by arminsabouri)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

Previously included in bitcoin-inquisition (https://github.com/bitcoin-inquisition/bitcoin/pull/58, also https://github.com/bitcoin-inquisition/bitcoin/pull/64 and https://github.com/bitcoin-inquisition/bitcoin/pull/79).

Makes minimal changes to consensus logic, but still has to duplicate a bunch of code to get equivalent behaviour, might be worthwhile simplifying that API in followups, and potentially exposing as a kernel API of some sort?

tACK a64f2ac5b11ac95a43d11c2846e461de0b6eb48a

Ran tool_utils, the script unit tests and feature_taproot on the head, and both examples from the description reproduce here.

The PR description mentions -tx, but I noticed no case in bitcoin-util-test.json uses -tx, so that path goes uncovered. To confirm, I disabled the -input range check and the suite still passes. Would it be worth adding a case like that?

Rebased, added a test that uses -tx

Tested 598427fd07.

I ran the 1214 rows of script_tests.json that evalscript can express, each as a chain of calls (scriptSig, then scriptPubKey, then the redeem or witness script) with -tx and -spentoutput. All 1214 gave the expected result, and so did the 5 tapscript rows. The other 18 rows fail in checks that VerifyScript makes outside EvalScript.

I also ran 10,000 random scripts under each sigversion with NONE, MANDATORY and STANDARD flags, 90,000 runs, and compared them with btclib's interpreter. Success and error matched on all but 246 runs. In those, both sides failed with different error codes, and all come from three btclib bugs. evalscript never crashed.

One trap: a script argument that is valid hex is read as raw bytes. evalscript 16 runs the byte 0x16 and fails with "Opcode missing or not understood", while evalscript '16 ' runs OP_16. Could the help say so, or raw hex need a 0x prefix?