Sources, fallback and cool-downs

#Plain languageIn plain terms

Forensia does not run its own copy of every blockchain. It asks public data sources, the same way a block explorer does. Sources fail, slow down and rate-limit, so each network has a main source and backups.

Whichever server actually answers is written into the evidence record. You can always see who said what.

#How it worksHow it works

1. Send the request to the network's primary source.
2. If it refuses, times out, or says it does not support the request, try the next source in the list.
3. Record the host that answered alongside the response.
4. If a source keeps failing, stop sending it requests for a while.

#Technical detailThe exact rules

When a fallback is tried

• The HTTP status is 401, 403, 429, or 500 and above.
• The response is a JSON-RPC error with code -32600 or -32601 whose message says the method is unsupported or not enabled.
• The request throws, for example on a timeout.
• In a transaction lookup and in network detection only, for eth_getTransactionByHash and eth_getTransactionReceipt: the source answers correctly but with no record (result: null).

That last case covers the two exact hash lookups for the transaction being looked up and nothing else. Receipt checks made during an address lookup or a tracing step do not use it. An empty balance, empty code, an empty log list, a batched request or a provider-specific method is taken as the answer. A reply whose envelope does not match the request is not treated as "no record". Each earlier "no record" reply is kept as a separate evidence record with its own bytes, fingerprint, host and time, but it is never used as the transaction or receipt behind an interpretation. If every source returns no record for the transaction, the lookup stops with an error saying this does not prove the transaction is absent from the network.

A fallback gets a shorter timeout: half the primary's, with a floor of 2 seconds. The two hash lookups and network probes also carry one overall deadline (12 seconds per hash lookup, 7 seconds per probe), and a later source only gets the time left in it. An EVM source is tried once per request: there is no retry against the same source and no delay between sources. Provider-specific methods are never sent to a fallback.

The Bitcoin source is one configured API with no backup, so it is handled differently. A request that gets no response at all, such as a dropped connection or a timeout, is tried again: up to three attempts in total, with pauses of 0.4 and then 1.2 seconds, all inside a deadline of twice the request's timeout (20 seconds for a standard 10 second request). An HTTP answer of any status, a source in cool-down, or a spent request allowance is final and is not retried. Every attempt spends one request.

Cool-downs

On the public deployment, a source that fails twice is rested. A failure here means HTTP 429, a 5xx status, or a thrown error. The first failure only counts. From the second, the source is skipped until a cool-down ends.

If the source sends a Retry-After header, that value is used instead, clamped between 1 and 900 seconds. Any successful response clears the count.

Response size

Every response is read through a byte counter that counts decoded bytes, not the declared length. Over the limit, the response is rejected whole. A partial body is never kept as evidence.

#LimitsWhat it does not tell you

• A source answering is not the same as the source being right. Responses from two sources are not compared with each other.
• Cool-down state lives in each server process. It is not shared or persisted.
• A fallback can return a slightly different view of the chain from the primary, for example if it is a few blocks behind.