ChainStory

ChainStory is an open-source, native Windows program that turns public Ethereum and Bitcoin wallet activity into one readable timeline. It is for someone viewing a wallet they choose to enter—not for identifying, investigating, tracing, or scoring people.

Paste a public address to load current balances, holdings, recent transfers and contract calls, fees, activity patterns, and frequently used destinations. The program is read-only: it cannot connect a wallet, sign a message, trade, or move funds.

Release-candidate status: 0.4.0-rc.3 contains the live-only Ethereum and Bitcoin adapters, activity sorting, and the Bitcoin rate-limit hardening. It must pass LIVE_DATA_TEST_GUIDE.md on Windows before the tag is published. Historical portfolio charts and historical USD transaction values are deliberately unavailable rather than simulated.

Live data sources

Network	Primary source	Fallback / cross-check	Current limitations
Ethereum mainnet	Etherscan V2 with a user-supplied API key	Blockscout for native-balance comparison, token holdings, and no-key fallback	Latest provider page; current USD estimates; Blockscout per-instance deprecation; no swap inference or historical chart
Bitcoin mainnet	Blockchain.com Explorer Gateway, with an optional user-supplied Explorer key	A 60-second local repeat-load cache and a recent in-memory snapshot after HTTP 429	Latest 100 transactions; current USD estimate; anonymous request allowance; multi-input fee attribution warning

Every wallet view reports whether it is LIVE or CACHED, plus its source, original UTC fetch time, and completeness. Provider failures leave the previous view unchanged unless a clearly labeled recent same-address Bitcoin snapshot is available; ChainStory contains no demo wallet or sample-transaction mode.

Blockchain.com's current Explorer Gateway specification includes Bitcoin, Ethereum, and Solana. This release candidate moves Bitcoin to that gateway, while Ethereum deliberately stays on the already-tested Etherscan/Blockscout adapter until a separate migration passes the same accuracy gate.

Windows quick start

Windows 10 or 11 with .NET Framework 4.8 is recommended.

1. Extract the entire ZIP.
2. Double-click START_CHAINSTORY.bat.
3. If ChainStory.exe is present, it opens. Otherwise Windows builds it from ChainStory.cs and LiveData.cs, then opens it.
4. For Ethereum, click SET ETH KEY and enter a free Etherscan API key. Without one, Ethereum uses visibly labeled Blockscout fallback mode.
5. For Bitcoin, SET BTC KEY is optional. Without one, the app uses Blockchain.com's anonymous allowance with request spacing and caching.
6. Paste only a public Ethereum or Bitcoin address and click LOAD LIVE DATA.
7. Click DATA STATUS to inspect source, refresh time, completeness, cache state, and warnings.

The executable is unsigned, so Windows may display SmartScreen. Build it yourself from the readable source or compare a release ZIP with its published SHA-256 checksum.

Make the EXE and GitHub release ZIP

Double-click MAKE_RELEASE.bat. It performs a clean source build and opens the dist folder containing:

• ChainStory-Windows-0.4.0-rc.3.exe — direct Windows program download;
• ChainStory-Windows-0.4.0-rc.3.exe.sha256 — checksum for the standalone EXE;
• ChainStory-Windows-0.4.0-rc.3.zip — portable EXE plus the complete source and documentation;
• ChainStory-Windows-0.4.0-rc.3.sha256 — checksum for that ZIP.

For only the executable, double-click BUILD_EXE.bat. From Command Prompt:

BUILD_EXE.bat --quiet

The compiler and referenced libraries are part of Windows .NET Framework; the app has no NuGet, Node, Python, browser, or web-server runtime dependency.

What is included

• Ethereum and Bitcoin public-address detection;
• background live loading so the interface stays responsive;
• Etherscan-primary Ethereum data with Blockscout fallback and balance mismatch warnings;
• Blockchain.com Explorer Gateway Bitcoin balances, transaction counts, UTXO counts, transactions, confirmations, fees, and current price;
• live transaction hashes, timestamps, directions, confirmations, token decimals, and amounts;
• fee labels that distinguish complete totals from loaded-page totals;
• current native and ERC-20 holdings with explicit unpriced-asset counts;
• activity calendar and most-used destinations derived only from loaded events;
• activity sorting by newest loaded, oldest loaded, highest amount, or lowest amount;
• privacy mode across balances, holdings, details, copied summaries, and CSV exports;
• encrypted local Etherscan and Blockchain.com Explorer key storage using Windows Data Protection API;
• locally saved public addresses with no ChainStory account or telemetry;
• source/completeness metadata in the UI and CSV report;
• resizable black-and-white, square-edged, pixel-inspired interface.

Accuracy boundaries

• Historical portfolio value is not connected. The graph says so instead of showing sample data.
• Timeline USD values are not backfilled at historical exchange rates.
• Ethereum swaps are not guessed from token movements; contract calls and ERC-20 transfers remain separate events until a verified decoder exists.
• Ethereum token holdings and token prices depend on Blockscout coverage.
• Blockscout documents its current per-instance endpoints as scheduled for deprecation, so fallback mode is a release-candidate dependency rather than a permanent contract.
• Bitcoin fees show the full transaction fee when the entered address appears in an input. Collaborative or multi-input transactions may share that fee.
• Blockchain.com's Gateway accepts a public address in its Bitcoin address request. P2PKH, P2SH, Bech32, and Taproot remain separate release-gate cases and must pass the Windows live-data matrix before publication.
• Bitcoin gateway requests are serialized and spaced, the latest same-address result is reused for 60 seconds, and a recent in-memory snapshot can be shown after HTTP 429. The cache is cleared when the app closes.
• Amount sorting compares absolute displayed asset quantities. It does not treat unlike assets such as ETH and USDC as directly equivalent.
• A partial-history label means only the loaded provider page contributes to the timeline, activity view, most-used list, and fee sum.
• ChainStory is a review aid, not financial, legal, accounting, security, or tax advice.

Privacy and product boundaries

• Never enter a seed phrase, private key, wallet password, exchange password, or signing request.
• The optional Etherscan API key is encrypted for the current Windows user in %APPDATA%\ChainStory\etherscan-key.bin and is never exported.
• The optional Blockchain.com Explorer key is encrypted for the current Windows user in %APPDATA%\ChainStory\blockchain-explorer-key.bin and is never exported.
• Saved public addresses are stored in %APPDATA%\ChainStory\saved-wallets.txt.
• Privacy Mode hides values on screen and in exports; it does not make public blockchain activity private or hide requests from data providers.
• ChainStory makes no claim about who controls an address and does not create relationship graphs or owner scores.
• All network operations are read-only HTTPS requests. Blockchain.com's current Gateway uses POST request bodies for public-address queries; ChainStory never signs or submits transactions.

Keyboard shortcuts

Shortcut	Action
Ctrl+L	Focus and select the public address
Ctrl+P	Toggle Privacy Mode
Ctrl+F	Focus activity search
Ctrl+E	Export CSV
F1	Show version, scope, and shortcuts

Repository and release flow

• node tools/validate-source.mjs performs the contributor-side source/package checks.
• Each push and pull request compiles the program on a clean GitHub-hosted Windows runner.
• A tag equal to v plus the exact VERSION value builds the standalone EXE, portable source ZIP, and SHA-256 files.
• A version containing -rc is published as a GitHub pre-release.
• Executables and API keys are ignored by Git. Compiled binaries belong in GitHub Releases, while the repository remains readable source.

Read LIVE_DATA_TEST_GUIDE.md, RELEASE_CHECKLIST.md, and GITHUB_RELEASE_GUIDE.md before tagging the release.

Project map

Path	Purpose
ChainStory.cs	Windows Forms interface, address detection, live-only views, and activity sorting
LiveData.cs	Read-only providers, normalization, exact-unit formatting, key storage, and derived live views
BUILD_EXE.bat	Builds ChainStory.exe from both source files
MAKE_RELEASE.bat	Builds and packages the EXE plus source and checksum
START_CHAINSTORY.bat	Opens a built EXE or builds it when missing
LIVE_DATA_TEST_GUIDE.md	Required provider-by-provider accuracy and failure tests
tools/package-release.ps1	Creates the portable GitHub Release assets
docs/ARCHITECTURE.md	Adapter and chain-neutral normalization design
schema/normalized-transaction.schema.json	Precision-safe shared event contract
.github/workflows/	Clean Windows builds and tagged releases

Contributing and security

Focused issues and pull requests are welcome. New networks must normalize raw chain data instead of leaking provider-specific payloads into the interface. Read CONTRIBUTING.md and report vulnerabilities using SECURITY.md. Never put API keys or other secrets in commits or public issues.

License

MIT License. See LICENSE.