# BTC-RUST-APP — Local Bitcoin Provenance & Tax (MVP)

Lokales (offline-first) Rust-Projekt für **Bitcoin Asset Management** mit Fokus auf:
- **Provenance / Herkunftsketten** (SEPA → Exchange → Withdrawal → Self-Custody → Deposit → Sell)
- **Beleg- und Auditfähigkeit** (strukturierte Events/Links, Export-Report)
- **Deterministische Testvektoren** via **Bitcoin Core regtest**

Aktueller Stand (Phase 1):
- Regtest-Flow **Flow A** ist reproduzierbar (Fixtures + Onchain TxIDs + Descriptor).
- `btc-cli` kann DB initialisieren, FlowA importieren, FlowA linken, FlowA reporten.
- Shell-Automation für End-to-End Pipeline ist vorhanden.

---

## Inhaltsverzeichnis

- [Überblick](#überblick)
- [Repo-Struktur](#repo-struktur)
- [Voraussetzungen](#voraussetzungen)
- [Installation](#installation)
  - [Bitcoin Core (bitcoind/bitcoin-cli) lokal](#bitcoin-core-bitcoindbitcoin-cli-lokal)
  - [Rust Toolchain](#rust-toolchain)
- [Quickstart](#quickstart)
- [Binaries / Tools](#binaries--tools)
  - [`btc-cli`](#btc-cli)
  - [`bitcoind` / `bitcoin-cli` (regtest)](#bitcoind--bitcoin-cli-regtest)
- [Scripts](#scripts)
- [Flow A](#flow-a)
- [DB / Datenmodell (MVP)](#db--datenmodell-mvp)
- [btc-cli: Flow A komplett durchspielen]
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [Security / Privacy](#security--privacy)

---

## Überblick

Ziel: eine lokale Software, die alle relevanten **Ereignisse (Events)** und **Belege (Proofs)** aus Bank/Exchange/Onchain zusammenführt, sie zu einer lückenlosen **Provenance Chain** verknüpft und daraus **exportierbare Reports** erzeugt.

**Wichtig:** In Phase 1 wird bewusst **nur Flow A** hart-deterministisch unterstützt (kein Heuristik-Zauber). Das ist Absicht, um einen stabilen Kern zu bauen, bevor Komplexität (weitere Flows, DEX, Lightning, Mining, MiCA/DAC8 Bundles, etc.) kommt.

---

## Repo-Struktur

~/devel/BTC-RUST-APP ├── btc-app/ │ ├── Cargo.toml # Rust workspace │ ├── btc-cli/ # CLI binary │ ├── fixtures/flowA/ # FlowA CSV/JSON fixtures + generated manifest/descriptor │ ├── proofs/flowA/ # Proof placeholders (Dateien/Ordner) │ ├── exports/ # Reports │ └── .data/dev.sqlite # SQLite DB (MVP) └── scripts/ ├── 003a-RegtestNode.sh ├── 003b-FlowA-Onchain.sh ├── 004a-Wallet-Descriptor-Sanity.sh ├── 005a-FlowA-Fixtures.sh ├── 006a-FlowA-Validator.sh ├── 010a-Create-MVP-Scripts.sh ├── 011a-Preflight-Dev.sh ├── 012a-Regtest-Ensure.sh ├── 013a-FlowA-Generate-And-Validate.sh ├── 014a-Rust-Build.sh ├── 015a-DB-Init.sh ├── 016a-Import-FlowA.sh ├── 017a-Link-FlowA.sh ├── 018a-Report-FlowA.sh └── 019a-MVP-Pipeline.sh

---

## Voraussetzungen

### System-Pakete
Empfohlen (Ubuntu/Debian):
```bash
sudo apt update
sudo apt install -y \
  build-essential pkg-config \
  curl ca-certificates tar xz-utils \
  jq ripgrep sqlite3

• jq/rg: Preflight/Script-Checks
• sqlite3: optional, aber praktisch zum Debuggen
• build-essential/pkg-config: nötig, falls Rust-Crates native libs bauen

Netzwerk / Node

• Für Phase 1 reicht lokaler regtest.
• Mainnet-Node und electrs sind nicht nötig für den MVP-Kernpfad (kommen später als Integrations-Backends).

---

Installation

Bitcoin Core (bitcoind/bitcoin-cli) lokal

Warum nicht apt/snap? Je nach Distribution gibt es keine passenden Pakete. Lösung: offizielle Bitcoin Core Binaries (tarball).

Beispiel (Version/Arch ggf. anpassen):

mkdir -p ~/bin /tmp/bitcoin-core
cd /tmp/bitcoin-core

VER="30.2"
ARCH="x86_64-linux-gnu"

curl -O "https://bitcoincore.org/bin/bitcoin-core-$VER/bitcoin-$VER-$ARCH.tar.gz"
tar -xzf "bitcoin-$VER-$ARCH.tar.gz"

install -m 0755 "bitcoin-$VER/bin/bitcoind"    ~/bin/bitcoind
install -m 0755 "bitcoin-$VER/bin/bitcoin-cli" ~/bin/bitcoin-cli
install -m 0755 "bitcoin-$VER/bin/bitcoin-tx"  ~/bin/bitcoin-tx

PATH setzen:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/bin:$PATH"

Check:

bitcoind --version
bitcoin-cli --version

Rust Toolchain

Rust installieren (z. B. via rustup) und prüfen:

rustc --version
cargo --version

---

Quickstart

1) Regtest Config & Datadir

Standard im Projekt:

• Datadir: ~/devel/BTC-RUST-APP/.regtest/bitcoin
• Conf: ~/devel/BTC-RUST-APP/.regtest/bitcoin/bitcoin.conf

Empfohlene Env-Variablen:

export BTC_HOME="$HOME/devel/BTC-RUST-APP"
export BTC_REGTEST_DATADIR="$BTC_HOME/.regtest/bitcoin"
export BTC_REGTEST_CONF="$BTC_REGTEST_DATADIR/bitcoin.conf"

2) End-to-End FlowA (regtest) + Rust Pipeline

Einmalige Script-Generierung (falls nicht schon passiert):

cd "$BTC_HOME/scripts"
FORCE=1 ./010a-Create-MVP-Scripts.sh

FlowA erzeugen + validieren:

cd "$BTC_HOME/scripts"
./013a-FlowA-Generate-And-Validate.sh

Rust build + DB init + import + link + report:

cd "$BTC_HOME/scripts"
./019a-MVP-Pipeline.sh

Ergebnis:

• DB: btc-app/.data/dev.sqlite
• Report: btc-app/exports/flowA_report.json

---

Binaries / Tools

btc-cli

Build:

cd ~/devel/BTC-RUST-APP/btc-app
cargo build

Run (direkt via cargo):

cd ~/devel/BTC-RUST-APP/btc-app
cargo run -p btc-cli -- --help

Commands (Phase 1)

1) init-db Legt SQLite Schema v1 an (idempotent).

cargo run -p btc-cli -- init-db --db btc-app/.data/dev.sqlite

2) import flowA Importiert Fixtures (CSV/JSON) in events (idempotent).

cargo run -p btc-cli -- import flowA --db btc-app/.data/dev.sqlite --fixtures btc-app/fixtures/flowA

3) link flowA Erzeugt deterministische Links in links (idempotent).

cargo run -p btc-cli -- link flowA --db btc-app/.data/dev.sqlite

4) report flowA Exportiert JSON Report aus DB.

cargo run -p btc-cli -- report flowA --db btc-app/.data/dev.sqlite --out btc-app/exports/flowA_report.json

---

bitcoind / bitcoin-cli (regtest)

Node starten/stoppen/minen (über Scripts):

cd ~/devel/BTC-RUST-APP/scripts
./003a-RegtestNode.sh start
./003a-RegtestNode.sh mine 101 miner
./003a-RegtestNode.sh stop

Direkt prüfen:

bitcoin-cli -regtest -conf "$BTC_REGTEST_CONF" -datadir "$BTC_REGTEST_DATADIR" getblockchaininfo | jq -r .chain
# erwartet: regtest

---

Scripts

Alle Scripts liegen unter ~/devel/BTC-RUST-APP/scripts.

Kernscripts (FlowA / regtest)

• 003a-RegtestNode.sh

  • start|stop|status|mine [blocks] [wallet]
  • Nutzt lokal regtest mit -conf/-datadir.

• 005a-FlowA-Fixtures.sh

  • Erzeugt FlowA CSV/JSON Fixtures und Proof placeholders.
  • FORCE=1 überschreibt bestehende Fixtures.

• 003b-FlowA-Onchain.sh

  • Erzeugt FlowA Onchain TxIDs im regtest, schreibt:

    • fixtures/flowA/chain_manifest.json
    • fixtures/flowA/wallet_descriptor.txt
    • aktualisiert kraken_funding_sidecar.json

• 004a-Wallet-Descriptor-Sanity.sh

  • Prüft Descriptor-Datei und leitet testweise Adressen ab.
  • Wichtig: nutzt explizit regtest -conf/-datadir (kein Default ~/.bitcoin).

• 006a-FlowA-Validator.sh

  • Validiert, dass Fixtures/Sidecar/Manifest konsistent sind (Phase 1 “static validation”).

MVP Automations

• 011a-Preflight-Dev.sh Tool checks + regtest check.

• 012a-Regtest-Ensure.sh Startet Node und mined initial 101 Blocks falls nötig.

• 013a-FlowA-Generate-And-Validate.sh Orchestriert FlowA: Fixtures → Onchain → Descriptor sanity → Validator.

• 015a-DB-Init.sh btc-cli init-db

• 016a-Import-FlowA.sh btc-cli import flowA

• 017a-Link-FlowA.sh btc-cli link flowA

• 018a-Report-FlowA.sh btc-cli report flowA

• 019a-MVP-Pipeline.sh End-to-End: 013a → build → init-db → import → link → report

---

Flow A

Flow A ist der aktuelle Testvektor und Kern für Phase 1.

Konzeptuell:

1. SEPA → Exchange Deposit (Fiat)
2. Buy BTC (Trade)
3. Withdrawal BTC → Self-Custody
4. Deposit BTC zurück zur Exchange
5. Sell BTC
6. Fiat Auszahlung

In Phase 1 ist der Fokus:

• Fixture-getrieben (CSV/JSON + Sidecar + Manifest)
• deterministische Links
• exportierbarer Report

---

DB / Datenmodell (MVP)

SQLite DB (btc-app/.data/dev.sqlite) enthält aktuell:

• events: normalisierte Ereignisse (CSV rows + JSON blobs)
• links: deterministische Verknüpfungen zwischen Events
• meta: breadcrumbs (z. B. last_import_flowA_at, last_link_flowA_at)
• tx_cache: reserviert für Phase 2 (Onchain resolve + caching)
• proofs: reserviert/placeholder für echte Belegverwaltung

Debug:

sqlite3 btc-app/.data/dev.sqlite 'select kind, count(*) from events group by kind order by kind;'
sqlite3 btc-app/.data/dev.sqlite 'select link_type, count(*) from links group by link_type order by link_type;'

---

btc-cli: Flow A komplett durchspielen (Phase 1 + Phase 2)

Dieser Abschnitt zeigt, wie du Flow A mit der btc-cli end-to-end ausführst – von DB-Init über Import/Link bis hin zu Report (und optional: On-Chain Resolve in Phase 2).

Annahmen:

• Repo liegt unter ~/devel/BTC-RUST-APP
• Fixtures liegen unter btc-app/fixtures/flowA
• DB liegt unter btc-app/.data/dev.sqlite
• Regtest Bitcoin Core liegt unter ~/devel/BTC-RUST-APP/.regtest/bitcoin

1) Voraussetzungen prüfen

cd ~/devel/BTC-RUST-APP/btc-app

# Rust toolchain
cargo --version

# bitcoin-cli muss verfügbar sein (für Phase 2 / resolve)
bitcoin-cli --version

Optional (praktisch, um Tippfehler zu vermeiden):

export BTC_HOME="$HOME/devel/BTC-RUST-APP"
export APP_DIR="$BTC_HOME/btc-app"
export DB="$APP_DIR/.data/dev.sqlite"
export FIX="$APP_DIR/fixtures/flowA"
export DATADIR="$BTC_HOME/.regtest/bitcoin"
export CONF="$DATADIR/bitcoin.conf"

---

2) btc-cli bauen

cd "$APP_DIR"
cargo build -p btc-cli

Du kannst anschließend entweder mit cargo run … arbeiten oder den Binary direkt starten (je nach Setup/target-Pfad).

---

3) DB initialisieren (Schema anlegen)

cd "$APP_DIR"
cargo run -p btc-cli -- init-db --db "$DB"

Erwartung:

• DB-Datei existiert danach.
• Schema ist idempotent (mehrfach ausführen ist ok).

---

4) Flow A importieren (Fixtures → events)

Der Import erwartet die FlowA Fixtures (CSV/JSON) in btc-app/fixtures/flowA.

cd "$APP_DIR"
cargo run -p btc-cli -- import flowA --db "$DB" --fixtures "$FIX"

Erwartung:

• In der DB gibt es Events der Typen:

  • bank_transfer
  • kraken_trade
  • kraken_ledger
  • kraken_sidecar
  • chain_manifest

Debug (optional):

sqlite3 "$DB" 'select kind, count(*) from events group by kind order by kind;'

---

5) Flow A linken (events → links)

Linking erzeugt deterministische Kanten (links) zwischen Events, um eine Provenance-Kette zu modellieren.

cd "$APP_DIR"
cargo run -p btc-cli -- link flowA --db "$DB"

Erwartung:

• In der DB existieren Link-Types im Namespace flowA.*
• Linking ist idempotent (erneut ausführen fügt keine Duplikate hinzu)

Debug (optional):

sqlite3 "$DB" 'select link_type, count(*) from links group by link_type order by link_type;'

---

6) Report exportieren (DB → JSON Report)

cd "$APP_DIR"
cargo run -p btc-cli -- report flowA --db "$DB" --out "$APP_DIR/exports/flowA_report.json"

Check:

jq '.counts, .meta.schema_version, (.links[0] // null)' -C "$APP_DIR/exports/flowA_report.json"

---

Phase 2 (optional, aber empfohlen): On-Chain Resolve + erweiterter Report

In Phase 2 wird Flow A nicht nur “statisch” gelinkt, sondern die beiden regtest TxIDs aus chain_manifest werden gegen Bitcoin Core RPC aufgelöst und gecached.

7) Resolve Flow A (chain_manifest → tx_cache/tx_outputs)

Wichtig: resolve arbeitet nur gegen regtest und bricht ab, wenn die Node nicht regtest ist.

Vorab: Node/Chain prüfen:

bitcoin-cli -regtest -conf "$CONF" -datadir "$DATADIR" getblockchaininfo | jq -r .chain
# muss "regtest" sein

Resolve ausführen:

cd "$APP_DIR"
cargo run -p btc-cli -- resolve flowA --db "$DB" --datadir "$DATADIR" --conf "$CONF"

Optional, um Cache zu überschreiben:

cd "$APP_DIR"
cargo run -p btc-cli -- resolve flowA --db "$DB" --datadir "$DATADIR" --conf "$CONF" --force

Erwartung:

• tx_cache enthält 2 TxIDs (withdrawal + deposit)
• tx_outputs enthält vouts mit sat-Werten + (best-effort) addresses

Debug (optional):

sqlite3 "$DB" 'select txid, confirmations, blocktime from tx_cache order by txid;'
sqlite3 "$DB" 'select txid, count(*) as outputs from tx_outputs group by txid order by txid;'

---

8) Report erneut erzeugen (jetzt mit onchain Abschnitt)

cd "$APP_DIR"
cargo run -p btc-cli -- report flowA --db "$DB" --out "$APP_DIR/exports/flowA_report.json"

Onchain-Sektion prüfen:

jq '.onchain.resolved, .onchain.checks, (.onchain.txs[] | {label, txid, confirmations, outputs_count:(.outputs|length)})' \
  -C "$APP_DIR/exports/flowA_report.json"

Erwartung:

• onchain.resolved == true

• Checks enthalten u. a.:

  • withdrawal_resolved
  • deposit_resolved
  • withdrawal_expected_address_in_outputs
  • deposit_expected_address_in_outputs

---

Typische Fehlerbilder

“No chain_manifest event in DB…”

Du hast import flowA noch nicht ausgeführt oder Fixtures fehlen. → erst import flowA ausführen.

“Refuse to resolve: chain=main (expected regtest)”

Du triffst den falschen Node/datadir/conf. → --datadir/--conf prüfen und getblockchaininfo kontrollieren.

bitcoin-cli will ~/.bitcoin/bitcoin.conf

Du hast bitcoin-cli ohne -conf/-datadir ausgeführt. → immer -regtest -conf "$CONF" -datadir "$DATADIR" verwenden.

---

Minimaler “alles in Reihenfolge” Ablauf

cd ~/devel/BTC-RUST-APP/btc-app
export BTC_HOME="$HOME/devel/BTC-RUST-APP"
export APP_DIR="$BTC_HOME/btc-app"
export DB="$APP_DIR/.data/dev.sqlite"
export FIX="$APP_DIR/fixtures/flowA"
export DATADIR="$BTC_HOME/.regtest/bitcoin"
export CONF="$DATADIR/bitcoin.conf"

cargo build -p btc-cli
cargo run -p btc-cli -- init-db --db "$DB"
cargo run -p btc-cli -- import flowA --db "$DB" --fixtures "$FIX"
cargo run -p btc-cli -- link flowA --db "$DB"
cargo run -p btc-cli -- resolve flowA --db "$DB" --datadir "$DATADIR" --conf "$CONF"   # optional Phase 2
cargo run -p btc-cli -- report flowA --db "$DB" --out "$APP_DIR/exports/flowA_report.json"

Troubleshooting

“chain=main” statt regtest

Du triffst den falschen Node/Datadir/Conf.

• Nutze immer:

  • bitcoin-cli -regtest -conf "$CONF" -datadir "$DATADIR" ...

• Die Scripts sind darauf angepasst; wenn du manuell testest, nicht ohne Flags.

RPC credentials / cookie Fehler

Beispiel:

Could not locate RPC credentials… Configuration file: (~/.bitcoin/bitcoin.conf)

Ursache: bitcoin-cli wurde ohne -conf/-datadir aufgerufen und fällt auf ~/.bitcoin zurück. Fix: immer -conf/-datadir angeben (wie in den Scripts).

Fixtures/Manifest/Descriptor fehlen

• 003b-FlowA-Onchain.sh erzeugt chain_manifest.json und wallet_descriptor.txt.
• Wenn du überschreiben willst: FORCE=1 setzen.

“bitcoind not found”

• Prüfe ~/bin ist im PATH:

  which bitcoind
  echo $PATH
  

---

Roadmap

Phase 1 (done)

• ✅ regtest setup + deterministische FlowA Fixtures
• ✅ btc-cli: init-db, import flowA, link flowA, report flowA
• ✅ End-to-end Scripts + Validator

Phase 2 (nächste Schritte, high value)

1. Resolve / TxResolver (regtest RPC)

   • btc-cli resolve flowA: TxIDs aus manifest → getrawtransaction → tx_cache
   • Optional: Tabelle tx_outputs (vout/value/script/address) für Reports

2. Report Upgrade

   • report flowA zieht tx_cache und schreibt parsed onchain details
   • counts pro kind und pro link_type im Report
   • optional: checksums/sha256 für Proof-Dateien

3. Strengere Guardrails

   • hartes “chain must be regtest” bei Resolve/Generate
   • Script-Flags vereinheitlichen (NETWORK/CONF/DATADIR überall)

Phase 3 (Erweiterung / echte Daten)

• Bitcoin Core mainnet integration (read-only) und/oder electrs backend (optional)
• Adapter-Struktur für Exchanges (Kraken API/CSV)
• Proof Management “richtig”: Import PDFs/CSVs/Screenshots + Hashing + Bundle Export (ZIP + JSON)
• Steuerlogik (FIFO / Specific ID) mit Testfällen
• BitBox02 Integration (PSBT / notes import/export) – optional, nach Architekturentscheidung
• UI (TUI/GUI) für Visualisierung von Provenance Graphen

---

Security / Privacy

• Phase 1 ist lokal und arbeitet mit regtest.
• Keine privaten Keys in der DB (MVP speichert keine Keys).
• Für echte Daten später: Belege verschlüsselt speichern, Hashes für Integrität, Auditlog für manuelle Zuordnungen.

---

Lizenz

TBD (noch nicht festgelegt).