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 · Architecture

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

Install

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

Usage

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 0.1.0 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.

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.

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