What Matters
Onchain data is transparent, not self-explanatory. An agent must resolve chain, contract, event, entity, protocol state, price and timing before turning transactions into a financial conclusion. Wallet labels and dashboards accelerate analysis, but every important claim needs a reproducible path back to raw evidence.
DN Evidence Block
Reviewed: 20 November 2026. Primary evidence: Ethereum JSON-RPC, Dune, Etherscan, Nansen and CoinGecko onchain documentation.
Boundary: providers decode, index, label and price data differently. DN did not certify any label or query result.
The Seven-Layer Onchain Evidence Stack
| Layer | Question | Primary evidence | Common error |
|---|---|---|---|
| 1. Raw chain | What block, transaction and log occurred? | Node JSON-RPC | Ignoring reorg or finality |
| 2. Decoding | Which contract function and event? | Verified ABI and bytecode | Wrong proxy implementation |
| 3. Asset identity | Which token and units? | Chain ID, contract and decimals | Symbol collision or decimal error |
| 4. Entity labels | Who may control the address? | Provider label plus provenance | Treating label as legal identity |
| 5. Protocol state | What position or claim existed? | Contract state and protocol logic | Counting transfers without position context |
| 6. Market context | What was the executable value? | Pool, quote and depth data | Using current or illiquid price |
| 7. Evidence lineage | Can another analyst reproduce it? | Query, code, versions and timestamps | Screenshot-only conclusion |
1. Start With Raw RPC Evidence
Ethereum clients expose a common JSON-RPC interface for blocks, transactions, receipts, logs and state. Retain chain ID, block number and hash, transaction hash, log index and raw values. A provider API can simplify access but should not be the only record for material findings.
Choose a finality policy. Recently mined blocks can be reorganized, and different chains have different settlement assumptions.
2. Decode Contracts and Proxies Correctly
Use verified ABIs where available and identify proxy implementations and upgrades at the relevant block. The same proxy address can execute different logic over time. Unknown signatures and custom events should remain unresolved rather than guessed.
For a swap router, one transaction can call several pools and tokens. Follow the event sequence and resulting balances rather than relying on one decoded method name.
3. Resolve Assets With Contracts, Not Symbols
Use chain ID plus contract address as the primary asset key. Verify decimals at the historical block where possible. Native, wrapped, bridged and issuer-native tokens are separate assets even when interfaces show one symbol.
4. Treat Entity Labels as Hypotheses
Nansen and other providers offer exchange, DeFi, behavioral and “smart money” labels. These are useful for grouping flows but can change or reflect inferred relationships. Record provider, label version, confidence and retrieval time.
For legal ownership, use verified disclosures, exchange records or counterparty evidence. A label cannot prove beneficial ownership.
5. Reconstruct Positions, Not Just Transfers
A lending deposit creates a claim; an LP mint represents multiple assets; a bridge locks or burns on one chain and mints or releases on another. Count the economic lifecycle once and preserve each onchain leg.
Query contract state at the analysis block to understand collateral, debt, shares, accrued fees and maturity. Token transfers alone can misstate value.
6. Add Executable Market Context
Attach a historical price from a relevant pool or venue and record quote direction, timestamp, liquidity and size. CoinGecko’s onchain APIs expose pool and trade data, but analysts must still choose the relevant pool and handle missing fields.
A large transfer valued at a thin pool’s last trade is not necessarily realizable. Use price impact and multiple sources for material amounts.
7. Build Reproducible Queries
Dune and other indexed systems accelerate cross-chain analytics. Store the query text, version, parameters, execution time and data catalog. Provider schemas can change, so export results and record the source version for published research.
Common Analytical Traps
- Double-counting bridge legs or router transfers.
- Classifying exchange hot-wallet reshuffling as deposits or withdrawals.
- Using token mint events as revenue.
- Ignoring fee-on-transfer or rebasing behavior.
- Valuing with current price instead of event-time price.
- Assuming all addresses in a cluster share beneficial ownership.
- Ignoring failed transactions and reverted internal calls.
DN Rule
Every agent-generated onchain claim should include a reproducible query and an uncertainty statement.
DN Onchain Evidence Quality Test
Score one analysis before publishing or trading from it.
Worked Example
An agent reports that a fund “sold $50 million of token X” because a labeled wallet transferred tokens to an exchange address. The transfer may be internal custody movement, a loan, a market-maker allocation or a deposit that was never sold.
A defensible conclusion needs label provenance, related wallets, exchange deposit behavior, subsequent balances, market trades and a price/size model. Until then, the statement should be “tokens moved to an address labeled as exchange-related.”
Methodology and Limitations
DN mapped onchain analysis from raw RPC through decoding, identity, protocol state, market context and evidence lineage. Offchain ownership, exchange books, contracts and intentions may remain unknowable from public data.
Frequently Asked Questions
Can an AI agent understand raw blockchain transactions?
It can decode and summarize transactions when it has correct ABIs, chain context and protocol state, but complex proxies and offchain dependencies still require verification.
Are wallet labels facts?
No. Labels are provider claims with provenance and confidence. They can be incomplete, stale or wrong and should not replace direct ownership evidence.
How should bridge transfers be counted?
Track the burn, lock, mint or release as one cross-chain lifecycle so the same economic transfer is not counted twice.
Why do onchain and market-data totals disagree?
They may use different timestamps, token contracts, decimals, pools, price sources, finality and entity mappings.
What should every onchain conclusion include?
Chain, block range, contract addresses, query or code, data source, retrieval time, assumptions, label provenance and known exclusions.
Primary Sources
- Ethereum JSON-RPC
- Dune Documentation
- Etherscan API Documentation
- Nansen API Documentation
- CoinGecko API Documentation
Editorial disclosure: no data provider paid for inclusion or methodology.