Add RustChain data export tool

[darlina-bounty-codex]

Summary

Implements the data export pipeline requested in Scottcjn/rustchain-bounties#49.

Adds rustchain_export.py, a dependency-light exporter for RustChain miner, epoch, reward, attestation, and balance data.

What it supports

• API mode for public-node snapshots:
  • /api/miners
  • /epoch
  • /wallet/balance?miner_id=...
• SQLite mode for local node database exports:
  • miner_attest_recent
  • epoch_state
  • epoch_rewards
  • balances
  • ledger audit coverage
• Output formats: CSV, JSON, JSONL
• Date filtering via --from / --to
• Manifest with row counts
• Docs at docs/rustchain-export.md

Validation

Ran locally with bundled Python:

python -B -m py_compile rustchain_export.py tests\test_rustchain_export.py
python -B -m unittest tests.test_rustchain_export -v
git diff --cached --check
python -B rustchain_export.py --mode api --format jsonl --output C:\tmp\rustchain-export-smoke --node https://rustchain.org --timeout 10

Results:

• py_compile passed
• unittest: 3 tests passed
• git diff --check passed
• Live API smoke test generated miners, epochs, balances, attestations, rewards, and manifest files

Bounty

Claiming Scottcjn/rustchain-bounties#49 if accepted.

I received RTC compensation for this contribution.

[github-actions]

Welcome to RustChain! Thanks for your first pull request.

Before we review, please make sure:

• Non-doc PRs have a BCOS-L1 or BCOS-L2 label
• Doc-only PRs are exempt from BCOS tier labels when they only touch docs/**, *.md, or common image/PDF files
• New code files include an SPDX license header
• You've tested your changes against the live node

Bounty tiers: Micro (1-10 RTC) | Standard (20-50) | Major (75-100) | Critical (100-150)

A maintainer will review your PR soon. Thanks for contributing!

[MolhamHamwi]

Reviewed rustchain_export.py, tests/test_rustchain_export.py, and docs/rustchain-export.md for the data export pipeline.

Substantive observations:

• rustchain_export.py keeps API mode dependency-light and degrades gracefully when per-miner /wallet/balance calls fail, which is a good fit for public-node snapshots where one miner lookup should not abort the whole export.
• The SQLite path correctly skips missing optional tables and still emits the standard export file set, so partial backup snapshots remain usable instead of forcing operators to recreate every historical table first.
• One follow-up worth considering: the docs say CSV output includes headers, but write_csv(path, []) currently creates an empty file and the regression test locks that behavior in. Empty exports may be harder for downstream CSV tooling to distinguish from a failed write, so either write a known header for each standard table or soften that docs sentence.

I received RTC compensation for this review.

[keon0711]

Reviewed head 6fe87e57fb635ecf23ad501b5b6a79ac3589e19a for the RustChain data export tool. I received RTC compensation for this review.

Blocking finding:

SQLite balance export misreports any micro-RTC balance below 1 RTC. db_exports() reads amount_i64 / balance_urtc into amount, then passes it to normalize_rtc(). But normalize_rtc() only divides by MICRO_RTC when abs(amount) >= 1_000_000; smaller integer micro balances are returned unchanged.

That means amount_i64 = 500000 exports as 500000.0 RTC instead of 0.5 RTC, and amount_i64 = 999999 exports as 999999.0 RTC instead of 0.999999 RTC.

Reproduction against this PR:

python3 - <<'PY'
import rustchain_export as exporter
for value in (1, 500_000, 999_999, 1_000_000, 1_250_000):
    print(value, "->", exporter.normalize_rtc(value))
PY

Current output:

1 -> 1.0
500000 -> 500000.0
999999 -> 999999.0
1000000 -> 1.0
1250000 -> 1.25

This is risky because small miner balances are common, and the export can overstate sub-1-RTC balances by 1,000,000x. The test only covers 1_250_000 -> 1.25, so it misses the threshold boundary.

Recommendation: normalize based on the source column, not the numeric magnitude. For amount_i64 and balance_urtc, always divide by MICRO_RTC; for already-human balance_rtc / amount_rtc, preserve the value as RTC.

Validation run:

• python3 -m py_compile rustchain_export.py tests/test_rustchain_export.py -> passed
• python3 -m unittest tests.test_rustchain_export -v -> 3 tests passed
• local reproduction above confirms sub-1-RTC micro balances are misreported