Reading a Bitcoin address or transaction
What Forensia fetches for Bitcoin, how balances and fees are worked out, and how much history one lookup covers.
#Plain languageIn plain terms
Bitcoin does not keep account balances. It keeps a record of individual coins, each one created by a transaction and later spent by another. An address's balance is simply the coins sent to it that have not been spent yet.
Forensia reads an address's totals and its most recent transactions, or one transaction in full with every input and output. It reports the newest page of history, not all of it.
#How it worksHow it works
For an address, four requests go out together: the address's totals, its most recent transactions, and the height and hash of the newest block. For a transaction, the transaction itself and the spend status of each of its outputs are fetched, together with the same newest-block height and hash.
#Technical detailThe exact rules
The source is a public Bitcoin index that follows the Esplora interface. Requests time out at 10 seconds and responses are capped at 2 MiB. Each response is fingerprinted and stored as an evidence record.
A request that gets no response at all (a dropped connection, a failed name lookup, a timeout) is tried again, up to three attempts in total, after pauses of 0.4 and 1.2 seconds. All attempts share one deadline of twice the request's timeout, which is 20 seconds for a 10 second request, and no further attempt starts unless at least one second would remain after the pause. Any HTTP answer is final and is not retried, including not found and rate limited. So is a source that is switched off or cooling down after repeated failures, and a spent request budget. The record's capture time is that of the attempt that answered.
Address figures
| Figure | How it is computed |
|---|---|
| Funded | Total value of outputs sent to the address, confirmed plus unconfirmed |
| Spent | Total value of those outputs that have been spent |
| Balance | Funded minus spent |
| Unspent outputs | Count of outputs funded minus count spent |
| Transactions | Confirmed count plus unconfirmed count |
All amounts are handled as whole satoshis in exact integer arithmetic. The individual unspent outputs are not listed; the count is derived from the totals.
Only the first page of the address's transactions is read, up to 50 unconfirmed and 25 confirmed, and 32 are shown. For each one the address's net effect is the value it received minus the value it spent, labelled incoming, outgoing or self.
Transaction figures
| Figure | How it is computed |
|---|---|
| Fee | As reported by the index |
| Virtual size | Weight divided by 4, rounded up |
| Fee rate | Fee divided by virtual size, in satoshis per virtual byte, to two decimals |
| Confirmations | Newest block height minus the transaction's block height, plus one |
Accepted transactions retain every input and output, up to 2,048 combined records within the 2 MiB source-response limit. Larger transactions are refused rather than analysed from a prefix. Activity and the receipt show pages of 12 records; changing pages does not fetch more data. Spent outputs retain their downstream reference. The graph remains a bounded sample, not a picture of every retained record.
When every previous-output value is available, all inputs, outputs and the reported fee are reconciled in integer satoshis. Missing previous outputs stay unavailable, not zero. Missing or conflicting accounting withholds value-based change and privacy-pattern leads. Allocation comparisons have their own smaller limits, described separately.
One transaction is handled specially: the mainnet genesis transaction, recognised only by its exact transaction ID together with block height 0 and the genesis block hash. Its outputs finding is titled "Genesis subsidy is unspendable", and a warning states that the index's unspent flag is not evidence that the 50 BTC can be spent. If the index reports that output as spent, the lookup stops with an error instead of showing it. The rule does not apply to later payments to the same address.
Findings: finding:bitcoin-address-state, finding:bitcoin-structure, finding:bitcoin-confirmation and finding:bitcoin-outspends, all class observed, plus finding:bitcoin-address-coverage, class limitation.
#LimitsWhat it does not tell you
- History beyond the first page is not read. Older transactions exist but are not shown.
- Addresses are checked by shape only: a
1or3followed by 25 to 34 base58 characters, orbc1followed by 11 to 71 bech32 characters. Their checksum is not verified. - There is one Bitcoin source. A not-found answer from it ends the lookup. No second source is tried.
- Input details come from the index. Forensia does not validate Bitcoin's consensus rules itself.
- Spend status is the index's current view. An unspent output today can be spent tomorrow.
- Mainnet only.