Consistent Blockchain Snapshots Across API Reads
Pin related balances, prices and position reads to compatible state references, and detect when an aggregate combines observations from different chain states.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A portfolio total can be internally inconsistent even when every individual API response is valid. The problem appears when related reads use different state points without declaring that difference.
Choose a shared state boundary
Select a block reference for compatible chain-state reads and verify returned context where available. Market prices may use a separate time-based observation, so record that relationship explicitly. A batch transport request does not guarantee one shared state. Nor does issuing calls quickly eliminate head changes or endpoint lag.
Worked example: a transfer between reads
The application reads wallet A before a transfer and wallet B after it. Adding both balances can count the same units twice. Reading both against one accepted block avoids that inconsistency under the chosen model. If a pinned historical read is unavailable, the aggregate should expose mixed observation context rather than pretend to be one snapshot.
Test aggregate assumptions
Include a changing head, missing historical state and responses from endpoints at different heights. Retain each component’s reference and the aggregate’s policy. Cache keys must include state context. A latest-state cache entry should not satisfy a historical snapshot request simply because the wallet and asset match.
A practical acceptance test
Move units from wallet A to B between two simulated latest reads. Assert that the aggregate detects mixed references or pins both reads consistently. A cache containing latest B must not satisfy a historical B request. When one component lacks the selected state, expose a partial aggregate rather than replacing it with an unlabelled current value.
Questions about the topic
Frequently asked questions
Does calling endpoints simultaneously guarantee one snapshot?
No. Pin and verify state references where required.
Can market prices and balances have different observation rules?
Yes. The aggregate should state how those observations are aligned.
Standards & technical documentation