Getting Started

What you'll learn on this page: what txray is, how its three tools fit together, and how to run your first command in under a minute.

What is txray?

txray is a toolkit that takes raw Bitcoin data and turns it into something a human can actually read. It answers three kinds of questions.

• What is inside this transaction? Use Lens.
• What can we infer about the people behind it? Use Sherlock.
• How do I build a better one myself? Use Smith.

You can use it through a web interface or through a command-line tool. Both call the same Rust core underneath.

A tiny glossary

If you are new to Bitcoin, these three words come up constantly. Skim them now and come back later if needed.

• UTXO, short for Unspent Transaction Output. A discrete chunk of bitcoin you can spend. Think of it like a banknote: you cannot spend half of it, you spend the whole note and get change back.
• Script, the tiny program attached to every output that says how it can be spent (for example, "whoever can sign with this public key").
• Witness, the signatures and extra proof data stored separately from the main transaction body. Introduced by Segregated Witness (SegWit) to save space and fix transaction malleability.

Other terms are explained the first time they appear in later pages.

Your first command

The fastest way to feel txray working is to run it against a famous block. The famous subcommand ships with a handful of hand-picked transactions baked into the binary, so you do not need to download anything.

txray famous

You get back a list that looks like this:

Famous Bitcoin moments bundled with txray:
  genesis      Block 0, the first Bitcoin block (2009-01-03)
  pizza        Block 57043, Laszlo's 10,000 BTC pizza (2010-05-22)
  finney       Block 170, Hal Finney receives the first Bitcoin transfer
  wasabi       Block 530484, a large Wasabi CoinJoin round
  ...

Pick one and parse it.

txray famous pizza

txray prints the 10,000 BTC pizza transaction: inputs, outputs, fee, script types, and the human-readable story behind it. That is Lens in action.

Running the web interface

The web UI wraps the same core with an interactive frontend. From the repo root:

docker compose up -d --build
# open http://localhost:3000

Pick Lens, Sherlock, or Smith from the top navigation, paste a transaction or choose a preset, and read the analysis.

Installing from source

If you would rather build it yourself:

git clone https://github.com/keshav0479/txray.git
cd txray
cargo build --release
./target/release/txray famous pizza

The Rust toolchain version is pinned in rust-toolchain.toml, so rustup picks the right compiler automatically.

Where to go next

• The UTXO model. Why Bitcoin looks like cash, not a bank account.
• Transaction structure. The parts every transaction contains.
• Privacy basics. Why on-chain privacy is harder than it looks.
• Common-input-ownership heuristic. The first forensic rule most analysts learn.

txray is for education and analysis. Treat every result as a strong hint, not proof. Always verify independently before making decisions that matter.