T1 · What Is Blockchain Data, Really?

A Real-World Problem

A product team gives you a request: notify a user whenever a particular address receives USDC.

It looks like a five-minute job. You open the documentation and immediately face the first question: where should you read this "receipt"?

• Check the address balance every few seconds and notify when it increases?
• Listen for Transfer events from the USDC contract?
• Fetch every block and parse its transactions one by one?
• Take the easy route and use a third-party API?

All four approaches can produce a demo, but they behave very differently in production. Some miss transfers. Some send duplicate notifications. Some notify a transfer that disappears after a chain reorganization.

Choosing badly costs you correctness, not just performance. To choose well, you first need to understand what a chain actually stores.

Thought Experiment

Think of a chain as two things, not one.

First: an append-only transaction journal.

At intervals, a new block collects transactions in order. Once written, an entry cannot be edited or inserted earlier in the queue. This journal records actions only: who called what, with which parameters, and how much fee they paid.

Second: a table of current state derived from that journal.

It shows each account's current balance and the current value of each contract storage slot. This table is not itself "written" into the chain. It is the result of executing every transaction in order, starting from the genesis block.

Now for the key question: when a transaction executes, which parts of state change?

The journal does not say so directly. It records only something like "call contract A's transfer function with address B and amount 100." To learn how many storage slots changed, or whether other contracts were called along the way, you must actually execute it.

That is why there is a third thing: logs. During execution, a contract can announce, "I just transferred 100 from B to C." That announcement is recorded in the transaction receipt for the outside world to hear.

Your Decision

Return to the notification request. Which approach do you choose?

What Happens

All four choices reveal the same thing: what you call "on-chain data" is actually one projection of it.

Which layer to read depends on what your business can tolerate. State is enough to display a balance. Reconciliation of funds requires traces. For notifications and indexing, Events offer the best cost-to-benefit ratio.

There is no single "most accurate layer," only the layer that matches your need.

Build a Model

Lay out a chain's data in layers:

Block                       block: container for a batch of transactions
 ├─ header                  parent hash, height, timestamp, state root
 └─ transactions[]          transactions ordered in the block
      └─ Transaction        one transaction: from, to, value, data, nonce, gas
           └─ Receipt       produced only after execution
                ├─ status   success or failure
                ├─ gasUsed  gas actually consumed
                └─ logs[]   events emitted by contracts
                     └─ Log  topics (indexed for filtering) + data (content)

State                       derived by executing all transactions in order
 ├─ account balance         account balance
 ├─ contract code           contract code
 └─ contract storage        contract storage slots

Four points will save you many detours:

1. A Receipt exists only after execution. Inclusion in a block does not mean success; check status separately. Showing "success" when a transaction was merely broadcast is a common frontend bug, covered further in T14.
2. Log topics are indexed; data is not. This determines which filters are efficient: contract address and topics work, but ordinary fields inside event data do not.
3. State tells you only "now." Reading state at an old block height requires an archive node, covered in T4. This is a common cost trap.
4. An Event is not state. A contract can emit an event that contradicts the actual state change, and attacks have exploited this. To confirm state, read state.

What It Is Called

Hands-on

curl -s -X POST <your-RPC-URL> \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

curl -s -X POST <your-RPC-URL> \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["latest",true]}'

curl -s -X POST <your-RPC-URL> \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionReceipt","params":["<transaction-hash>"]}'

curl -s -X POST <your-RPC-URL> \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{
        "fromBlock":"0x...","toBlock":"0x...",
        "address":"<token-contract-address>",
        "topics":["<Transfer-event-signature-hash>"]}]}'

AI Lab

Step one:
Explain the difference between State and Event on a blockchain, and why they may disagree.

Step two:
Give me three concrete situations in which an indexer listening only for Transfer events would reach the wrong conclusion.
For each, explain what it misses, what happens as a result, and the correct approach.

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check