EchoScript

Bounded causal execution evidence for Bitcoin Tapscript inputs.

It verifies the revealed Taproot commitment, executes leaf-version 0xc0 Tapscript with stack provenance and BIP341 signature validation, and can calibrate the complete transaction against Bitcoin Core without broadcasting it.

Static playground · latest release · documentation · architecture

The playground is a static GitHub Pages site backed by committed evidence snapshots. It never contacts Bitcoin Core, signs, or broadcasts.

Quick start

cargo install --git https://github.com/smallyunet/echoscript --tag v0.2.0
echoscript conformance

Core workflows

Create prevouts.json with one entry for every transaction input. BIP341 signature hashes can commit to all prevouts, so a selected-input-only prevout is insufficient:

[
  {
    "value_sats": 10000,
    "script_pubkey": "5120..."
  }
]

Then explain one input:

echoscript explain \
  --tx-file spend.hex \
  --prevouts prevouts.json \
  --input 0 \
  --profile full

Use --format json for compact JSON or --format jsonl to stream a summary followed by individual execution steps. Output remains additive within echoscript.evidence.v1 and includes explicit coverage, filtering, and truncation metadata.

What the execution engine verifies

• transaction decoding and input selection
• control block decoding and Taproot commitment verification
• BIP342 Tapscript execution, including OP_SUCCESSx, resource limits, conditionals, locktime, and sequence semantics
• BIP341 Taproot sighash construction and BIP340 Schnorr signature validation
• terminal clean-stack and truth evaluation
• optional complete-transaction acceptance through Bitcoin Core testmempoolaccept

Every stack value has a stable ID and origin. Signature steps record the sighash, sighash type, code-separator position, and validation outcome. Execution always reaches a terminal result; --step-limit, --around-step, profiles, and --changes-only limit only emitted evidence.

Profiles are structure, taproot, failure, stack, signature, and full.

Executable compatibility contract

v0.2.0 freezes 20 deterministic Tapscript vectors across terminal truth, comparison, arithmetic, stack, control flow, hashing, failure, and OP_SUCCESSx behavior:

echoscript conformance
echoscript conformance --format json

The command exits non-zero on any mismatch and emits echoscript.conformance.v1. The corpus is derived from named BIP342 semantic rules and protects EchoScript regressions; it is not presented as proof of full Bitcoin Core equivalence. Complete transaction acceptance still requires the optional Core calibration path below.

Bitcoin Core calibration

Pass a bitcoin-cli executable and its connection arguments to make a read-only testmempoolaccept call:

echoscript explain \
  --tx-file spend.hex \
  --prevouts prevouts.json \
  --bitcoin-cli bitcoin-cli \
  --bitcoin-cli-arg=-regtest \
  --format json

EchoScript never broadcasts. A local execution.result=valid describes the supported script engine only. Complete transaction acceptance depends on chain state and policy; without the Core oracle, consensus.result remains not_evaluated. See docs/architecture.md for the exact trust boundary.

To reproduce the project calibration on an isolated temporary regtest node:

scripts/regtest-smoke.sh

The script requires bitcoind, bitcoin-cli, cargo, and jq. EchoScript never handles wallet private keys, signs transactions, or broadcasts spends.

Documentation

Goal	Start here
Find the right guide	Documentation index
Understand execution and trust boundaries	Architecture
Inspect the frozen semantic vectors	Conformance corpus
Integrate conformance output	Conformance schema
Review version history	Changelog

Development

cargo fmt --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features --locked
bash scripts/regtest-smoke.sh

Echo family

Project	Execution domain	Static playground
EchoEVM	Solidity and EVM bytecode	Open
EchoSVM	Solana transactions and sBPF	Open
EchoRV	RISC-V firmware and traces	Open
EchoScript	Bitcoin Tapscript inputs	Open

Each project executes locally, emits a versioned evidence schema, and publishes frozen reproducible cases through the same static playground contract.

License

MIT