Reading the chain with code

Typing commands works for looking; it doesn’t work for monitoring. Nobody builds a treasury dashboard by manually refreshing a screen. This chapter makes chain-reading programmable — and that’s where it earns its place in a payments curriculum: the moment you can aggregate on-chain data, you can produce a number like “stablecoin volume.” The last two lessons show why that number, taken raw, is one of the most misleading figures in the industry — and how to read it honestly.

What we deliberately skip in this chapter (you can build the monitor without them): writing or signing transactions, wallet and private-key management, DeFi protocol mechanics, indexer architecture, and Dune SQL. We stay entirely on the read side of the chain.

The stack

In Chapter 2, the stack looked like this:

You typing a command (Cast)
        ↓
JSON-RPC  ← the message standard
        ↓
RPC provider  ← your gateway to the network
        ↓
Ethereum

In this chapter, only the top layer changes:

Your program (TypeScript)
        ↓
viem  ← a software library that writes the messages for you
        ↓
JSON-RPC
        ↓
RPC provider
        ↓
Ethereum

Translation to familiar territory:

One clarification that saves confusion later: the RPC endpoint URL your program points at is not “Ethereum itself.” It’s one provider’s door into the network — exactly as your SWIFT gateway is not “SWIFT.”

The same stack, in real code

In Chapter 2, checking a balance was one command typed into a terminal — Cast hand-delivering a single JSON-RPC message:

cast balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --rpc-url $ETH_RPC_URL

In this chapter, a program asks instead. The shared plumbing — the client every snippet below imports — is one real file:

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const client = createPublicClient({
  chain: mainnet,
  transport: http(process.env.ETH_RPC_URL),
})

Read it against the diagram: viem is the SDK, http(process.env.ETH_RPC_URL) is the door to your provider, mainnet names the network. The whole five-layer stack, in six lines.

Native balance vs contract balance

ETH is Ethereum’s native asset. Every account’s ETH balance is part of the chain’s base ledger. Reading it is one direct question:

import { formatEther } from 'viem'
import { client } from './client'

const balanceWei = await client.getBalance({
  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
})

console.log(balanceWei)              // 6634031455680168742n — wei
console.log(formatEther(balanceWei)) // "6.634031455680168742"

USDC is not part of that base ledger. It’s a balance inside the USDC smart contract — a program on Ethereum that maintains its own internal table of who holds what. To read a USDC balance, you don’t ask Ethereum; you ask the USDC contract:

import { erc20Abi, formatUnits } from 'viem'
import { client } from './client'

const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'

const balance = await client.readContract({
  address: USDC,               // which contract
  abi: erc20Abi,               // its API spec — the ABI
  functionName: 'balanceOf',   // which question
  args: ['0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'], // about whom
})

console.log(balance)                 // 9739943715n — minor units
console.log(formatUnits(balance, 6)) // "9739.943715"

(Cast can ask the identical question — same contract, same function, its signature typed inline:)

cast call 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  "balanceOf(address)(uint256)" \
  0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  --rpc-url $ETH_RPC_URL

The payments translation: the USDC contract is the issuer’s ledger, published on a shared network. Ethereum’s base ledger records ETH; Circle’s contract records USDC claims. Same network, two different books.

Two precision points your analysts will care about:

1. A balance inquiry is not a payment. readContract() is read-only. It needs no key, no signature, no gas, and it never appears on-chain — like an account statement request, not a transfer instruction.
2. Amounts come back as exact integers in minor units. A balance arrives as something like 6634031455680168742 — an integer, never a decimal. Payments people already know why: you never store money as floating point. On-chain amounts use the same discipline, just with more decimal places (USDC uses 6, ETH uses 18). The formatting into “6.63 ETH” happens in your program, explicitly, at display time.

The ABI — the contract’s API spec

How does your program know the USDC contract answers a question called balanceOf? From the contract’s ABI: a machine-readable description of its interface — the erc20Abi import in the snippet above, which in plain terms says:

balanceOf(address) → integer
decimals()         → integer
symbol()           → text

Think of it as the API documentation for the issuer’s ledger. Under the hood, the library converts your typed request into raw bytes the contract understands, and decodes the raw bytes that come back. You’ll never do this by hand — but knowing it happens keeps the library from being magic.

Instruction vs confirmation

These are separate objects, fetched separately:

import { client } from './client'

const hash = '0x…' // any transaction hash

const tx = await client.getTransaction({ hash })             // the instruction
const receipt = await client.getTransactionReceipt({ hash }) // the confirmation

An instruction existing proves intent; only the receipt proves execution. Every monitoring system reads receipts, not just transactions, for exactly this reason.

Logs — the statement entries

When a contract executes, it can emit events, which are stored as logs attached to the receipt. When USDC moves, the contract emits a Transfer event recording sender, recipient, and amount.

Logs are the closest thing on-chain to statement entries: the posting record of what a contract did. A monitoring program queries them like a database:

all logs
  → only from the USDC contract
  → only Transfer events
  → only this block range
  → decoded into structured records

And the database analogy runs deeper. Each log has a few indexed fields (called topics) and a payload:

log     ≈ a row
topics  ≈ indexed, searchable columns  (event type, from, to)
data    ≈ the non-indexed payload       (amount)

Because sender and recipient are indexed, you can efficiently ask the network “give me every USDC transfer from this address” — without downloading everything and filtering yourself. That one design choice is what makes address-level monitoring practical.

The same funnel, as the real query:

import { parseAbiItem } from 'viem'
import { client } from './client'

const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'

const logs = await client.getLogs({
  address: USDC,           // only from the USDC contract
  event: parseAbiItem(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),                       // only Transfer events
  args: { from: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
  fromBlock: 23_000_000n,  // only this block range
  toBlock: 23_000_100n,
})

A decoded event, as your program sees it:

{
  eventName: 'Transfer',
  args: {
    from:  '0x…',
    to:    '0x…',
    value: 9739943715n,   // 9,739.943715 USDC (6 decimals)
  },
}

One caveat before you trust a log: logs prove execution — they’re written only when a transaction actually ran. The instruction’s attached data proves only intent. Monitoring systems are built on logs for precisely this reason.

And one caveat before you trust an address: the chain tells you that address 0x51… received funds. It does not tell you the address belongs to Circle, Binance, or anyone. Mapping addresses to organizations requires external attribution data — explorer labels, entity datasets, verified documentation. On-chain: facts. Off-chain: names. Address ≠ wallet owner ≠ legal entity ≠ customer.

One transaction, many transfers

Here is a real pattern from Ethereum mainnet:

ONE transaction
     ↓
contract execution
     ├── Transfer #1
     ├── Transfer #2
     ├── Transfer #3
     └── Transfer #4

A single instruction can trigger a chain of contracts, each moving tokens, each emitting its own Transfer event. You can see it in two lines:

const receipt = await client.getTransactionReceipt({ hash })

receipt.logs.length // 4 — four Transfer events from ONE instruction

Immediately:

transaction count ≠ transfer count

The forensic case

Investigating one unusually large USDC Transfer event — pulling the transaction, its receipt, and all its logs — revealed that the “large transfer” was one leg of a complex multi-contract operation in which most of the token movements reversed before the transaction finished. Enormous gross flow; almost no net economic movement. All inside a single atomic transaction.

Payments professionals have seen this shape before: it’s the difference between gross ledger movement and customer payments. An RTGS system’s gross settlement flow dwarfs the underlying customer activity; interbank funding legs aren’t remittances. On-chain, the same distinction applies — but the headline numbers usually ignore it.

So the full inequality chain is:

transaction count  ≠  transfer count  ≠  payment count
gross transfer volume  ≠  payment volume

What honest measurement requires

Summing Transfer events gives you accounting evidence of token movement — nothing more. Turning that into a payments figure requires classification: filtering out bot activity, exchange-internal shuffling, protocol round-trips, and self-transfers, then attributing what remains to real-world context. (This is exactly the adjustment ladder from Episode 2 of the stablecoin series: raw volume shrinks by orders of magnitude before it resembles payments.)

To be fair in both directions: this is not unique dishonesty by the crypto industry — incumbent payment networks also quote flattering gross figures. The difference is that on-chain data is public, so here the inflation is checkable. That’s a genuine advantage, if you know how to check.

Proving there’s no magic

As a final check, we removed the library entirely and sent one raw JSON-RPC message to the provider — the equivalent of hand-writing a SWIFT message instead of using the vendor SDK:

const rpcUrl = process.env.ETH_RPC_URL

if (!rpcUrl) {
  throw new Error('ETH_RPC_URL is not set')
}

const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

const response = await fetch(rpcUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_getBalance',
    params: [address, 'latest'],
  }),
})

const data = await response.json()

console.log('RAW JSON-RPC RESPONSE')
console.log(data)

if ('result' in data) {
  const balanceWei = BigInt(data.result)

  console.log('\nDecoded manually')
  console.log('Hex:', data.result)
  console.log('Wei:', balanceWei)
  console.log('ETH:', Number(balanceWei) / 1e18)
}

What it prints:

RAW JSON-RPC RESPONSE
{ jsonrpc: '2.0', id: 1, result: '0x5c10d075d8958326' }

Decoded manually
Hex: 0x5c10d075d8958326
Wei: 6634031455680168742n
ETH: 6.634031455680169

(Look closely at the last line: dividing through Number rounded the final digits — the float trap this chapter keeps warning about, demonstrated live. Production code formats from the integer.)

The result matched the library exactly. Everything viem does is convenience: message construction, decoding, typing. Useful — but replaceable, inspectable, and never a source of truth on its own. Having proven that once, there’s no virtue in avoiding the library for real work.

Also learned in practice: your gateway has policies. Providers rate-limit, restrict deep historical queries, and require authentication tiers — your code can be perfectly correct while the provider refuses the request. Anyone who has worked with banking APIs will find this deeply familiar.

Named skips

Consistent with this series’ rule of saying what we’re not covering, this chapter deliberately excludes: writing or signing transactions, key and wallet management, DeFi protocol mechanics (the forensic case needed none of them), indexer and archive-node architecture, and large-scale entity attribution. They’re real topics; they’re simply not on the critical path to reading and measuring stablecoin activity honestly.

Self-test

You’ve absorbed this chapter if you can answer these without looking back.

Optional hands-on lab (for readers who code)

A minimal TypeScript project reproduces everything in this chapter with the viem library: one shared read-only client (the client.ts from Lesson 3.1), then one small script per concept — latest block, ETH balance, USDC balanceOf, a transaction and its receipt, a Transfer log query with a sender filter, and a raw JSON-RPC call with fetch() as the no-magic proof. You’ll need a free RPC endpoint from any provider (Alchemy, Infura, or similar). The lab ships as a companion repository rather than inline scripts — this chapter stays readable for non-coders.

Glossary — Chapter 3 additions

Bridge to Chapter 4

Everything so far read generic chain data. Chapter 4 applies the identical stack — contract, ABI, events, log queries — to a question with direct compliance weight: when does a stablecoin issuer freeze an address? USDT’s administrative events (blacklisting, freezing) are just another event type to filter and decode. The result is a working Freeze Tracker v0.1 — the first genuinely payments-native artifact of this curriculum.

Next — Chapter 4: The Freeze Tracker. The same five layers, one new event type, and the first tool you’ll actually want to keep running.