SwapChan
Never holds your keys · your wallet signs
Related:All docsChain tableClaimsblocktools: design
blocktools CLI

Getting started

Getting started with blocktools: install from the v0.1.1 release or from source, then your first sealed run on public test data.

DANGEROUS with real funds. Read SECURITY.md first. Practise on the public fixtures below and on mock chains before you touch a real key.

1. Install

Pick one.

Release tarball (Linux x86_64 only, glibc-linked, not static: 40 of 41 tools need glibc 2.34 or newer, sealed-run needs 2.39 or newer; see the README). v0.1.0 ships blocktools-v0.1.0-linux-x86_64.tar.gz and SHA256SUMS. Verify before you unpack:

gh release download v0.1.0 -R TSavo/blocktools
sha256sum -c SHA256SUMS            # blocktools-v0.1.0-linux-x86_64.tar.gz: OK  -- anything else: stop
tar xzf blocktools-v0.1.0-linux-x86_64.tar.gz && cd blocktools-v0.1.0-linux-x86_64
export PATH=$PWD/bin:$PATH MANPATH=$PWD/share/man:

Tools are in bin/, manual pages in share/man/ (man derive, man blocktools, man recover.sh). The tarball has no Dockerfile: for the sealed image, git clone --branch v0.1.0 and run ./blocktools build there (below). In v0.1.0, derive --address-list through redact comes back empty; the README gives the --public-only | jq workaround. Measured on Linux 2026-10-26: checksum OK, man -w blocktools resolves, and the examples in section 3 pass with the release binaries. No macOS asset exists.

From source.

git clone https://github.com/TSavo/blocktools && cd blocktools
cargo build --locked --release --workspace     # binaries in target/release/
./blocktools build                             # sealed Docker image blocktools:local

DEB / RPM / APK (dry-run packaging only, nothing is published): scripts/package-dist.sh and scripts/package-native.sh; install-tested in debian/fedora/alpine containers, man pages under /usr/share/man.

2. The security model in plain words

  • Secrets stay offline. Anything that reads a seed, keystore or wallet file runs inside ./blocktools run (no network, read-only filesystem, no capabilities, redacted stdout).
  • Inputs and secrets are separate. Wallet files go in ./in (seen as /in), passwords in ./secrets (seen as /secrets), one per file, ending in a newline. read-file PW FILE joins them on stdin for the reader tool.
  • Flags are public. Passwords, passphrases and mnemonics never go on argv.
  • What you see is redacted. Key fields print as [REDACTED]. Only ./blocktools reveal, at a real terminal after a typed code, prints keys.
  • Humans confirm spending. tx-sign and broadcast ask for a one-time code on a terminal; optional policy files cap fees and destinations before signing.
  • Unverified chains are labelled. CHAINS.md lists verified and unverified rows.

3. First recovery, on public test data

mkdir -p in secrets
printf '%s\n' 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about' > in/seed.txt

What is it?

./blocktools run 'classify /in/seed.txt'

Repair (checksum, typos), turn into a master key, derive the first address of each Bitcoin type:

./blocktools run 'seed-repair < /in/seed.txt | seed-to-master | derive --chain btc --count 1'

Or let the front door choose the pipeline for any file:

recipes/recover.sh /in/seed.txt - --goal addresses

Many chains at once, as a plain label<TAB>path<TAB>address list (SwapChan SCAN_JS layout; source build after v0.1.0, see the README):

./blocktools run 'seed-repair < /in/seed.txt | seed-to-master | derive --preset scan-js --address-list'

Passphrases: put candidates one per line in a file and use seed-to-master --passphrase-file (the empty passphrase is always tried first), or type one with seed-to-master --passphrase-prompt. Details and --public-only: recipes/derive.md.

4. Your wallet file

Copy it into ./in/, its password into ./secrets/NAME.pw, then follow the recipe for its type. The README has a tested one-liner per type; the recipes add variants, statuses and what is untested:

File Recipe
Bitcoin Core / altcoin wallet.dat input-wallet-dat.md
Ethereum keystore / presale JSON input-keystore.md
Electrum seed or wallet file input-electrum.md
MultiBit .key / bitcoinj .wallet input-multibit.md
Armory .wallet input-armory.md
Seed phrase (BIP39, missing words) input-seed-phrase.md
Don't know input-unknown.md

Statuses you will see: ok, wrong_password, unsupported, bad_input, no_candidates (REFUSALS.md).

5. Before moving funds

Sweeps are exercised end to end only against a mock chain (scripts/e2e-local.sh). Read goal-sweep.md and SECURITY.md, and check the destination on screen, before pointing --url at a real network.

Next