# EVM chain (JSON-RPC)

Source module: `app/connectors/evm_chain.py`. Kind: **facts** only. Display name: "EVM chain (JSON-RPC)".

## Purpose

Reads the record an agent that trades onchain cannot edit: the chain itself. For the wallets you name (a Coinbase
CDP Server Wallet's EVM account, an AgentKit wallet, any EVM address) the connector reads the ERC-20 `Transfer`
events that name them, pairs the legs of each transaction, and keys the facts on the wallet address. The Coinbase
Agent Trade pack's `place_wallet_swap` workflow verifies an agent's onchain swap against these facts: the token sold,
the token bought, the network, the amount sold, the amount bought within the slippage allowed, once, in the window.

Coinbase's wallet APIs sign and send; they do not list a wallet's past swaps (the CDP v2 reference offers account
lists and current token balances, not transaction history, as read on 2026-11-12). The chain does. Nothing here
needs a CDP key or a wallet secret: a JSON-RPC endpoint for the network is enough, and only read methods are used.

## Auth and scopes

| Item | Value |
|---|---|
| Method | A JSON-RPC endpoint URL over https (your node provider's URL, which usually carries a key in its path or query, or a public endpoint). Stored encrypted; requests go to the URL exactly as given |
| Credentials stored (encrypted) | `rpc_url`; non-secret settings `network` (CAIP-2, `eip155:8453` is Base, `eip155:1` Ethereum), `wallets` (comma-separated addresses), optional `start_block` |
| Least-privilege permissions | None to grant: the methods used are reads any endpoint serves (`eth_chainId`, `eth_blockNumber`, `eth_getLogs`, `eth_getBlockByNumber`, `eth_getTransactionByHash`, `eth_call` for `decimals()`). Nothing is signed, nothing is sent, no private key or wallet secret is ever asked for |
| Connection test | `eth_chainId` must equal the network's chain id (an endpoint for another chain is refused with the reason), then `eth_blockNumber` |

## Fields pulled and why

| Call | Fields | Used for |
|---|---|---|
| `eth_getLogs` with `topics [Transfer, [wallets]]` and `[Transfer, null, [wallets]]`, 2 000 blocks per call | `address` (token contract), `topics[1]` from, `topics[2]` to, `data` (amount), `transactionHash`, `blockNumber`, `logIndex`, `removed` | Every leg the wallet sent or received; a log the node marks `removed` (reorganised away) is skipped |
| `eth_getBlockByNumber(block, false)` | `timestamp` | The fact's time (the block's), and the watermark |
| `eth_getTransactionByHash` | `to` | The router or contract the wallet called (`router` on the facts) |
| `eth_call decimals()` per token (`0x313ce567`) | the token's decimals | `amount` in token units beside the atomic amount; null when the token does not answer |

## Incremental sync and watermark

- The connection remembers the last block it read (`config.last_block`). Every sync re-reads from 64 blocks behind
  it to the tip (a short reorg rewrites the tip; facts are keyed on transaction and log index, so the re-read is
  idempotent), at most 60 chunks of 2 000 blocks per sync; a connection further behind says how many blocks remain
  and continues on the next sync.
- First sync: from `start_block` when given, otherwise about a day of blocks behind the tip (43 200 blocks).
- Watermark = the timestamp of the last block read, so coverage and settlement reason about time as for every
  other source.

## Fact types produced

Subject id is the wallet address, lowercase; subject kind `wallet`. Token addresses are lowercase too. Every fact
carries `tx_hash`, `network` (CAIP-2), `router` (the transaction's `to`), `block` and `status: confirmed`
(`eth_getLogs` returns the events of mined, successful transactions only).

| `fact_type` | When | Extra attributes | `raw_ref` |
|---|---|---|---|
| `token_sent` | A `Transfer` from the wallet | `token`, `atomic_amount`, `amount`, `decimals`, `counterparty` (the receiver), `log_index` | `chain:{network}:{tx}:{log_index}` |
| `token_received` | A `Transfer` to the wallet | as above; `counterparty` is the sender | `chain:{network}:{tx}:{log_index}` |
| `swap_executed` | A transaction in which the wallet both sent and received tokens | `sold_token`, `sold_amount`, `sold_atomic_amount` (the largest sent leg), `bought_token`, `bought_amount`, `bought_atomic_amount` (the largest received leg), `sent_legs`, `received_legs` | `chain:{network}:{tx}:swap:{wallet}` |

A chain watcher of your own may push facts of the same source with an evidence key (`POST /v1/facts`, source
`chain`): the pack's contracts accept `shared` trust for them. A watcher can also report what the connector cannot:
`swap_executed` with `status: pending` for a transaction it saw in the mempool (the pack reads that as UNKNOWN), and
`swap_reverted` when it was dropped or reverted (the pack reads that as a reversal). When a chain connection is
live, pushed `chain` facts are refused (`409 source_served_by_connector`), as for every connector-served source.

## What is hashed / never stored

- Addresses and transaction hashes are public chain data; nothing identifies a person and nothing is hashed.
- No balance, no native-currency movement, no contract state and no transaction other than the watched wallets'
  ERC-20 transfers is requested. The endpoint URL is stored as a secret because provider URLs carry keys.

## Rate-limit handling

Shared `HttpClient` (Retry-After, exponential backoff on `429`/`5xx`, 6 attempts). Public endpoints often cap
`eth_getLogs` ranges; the 2 000-block chunk stays under the common caps.

## Known limitations

- **Native-currency legs are not events.** ETH (or the chain's native coin) sent as transaction value does not emit
  a `Transfer`, so a swap whose sold or bought side is native ETH rather than WETH shows only one leg and is not a
  `swap_executed`; it appears as a single `token_received` or `token_sent`. Agents that swap through WETH are read
  in full.
- **Routes with several legs.** A swap through two pools emits several transfers; the sold and bought legs are the
  largest sent and received amounts, and the leg counts are recorded. Fee legs (a small transfer to a fee
  collector) are recorded as their own `token_sent`.
- **A wallet that never traded** has no record, so an action on it answers UNKNOWN (`identity_unmatched`) rather
  than FAIL until any transfer that names it exists.
- **Chain data only.** Prices, the quote the agent received and the agent's intended slippage are not on the
  chain; the contract compares the amount bought with the `expected_bought_amount` the agent recorded, within the
  tolerance set in the wizard.
- A `removed` log the connector had already stored before the reorganisation is not deleted; it stays with the
  block it was read in. Reorganisations deeper than 64 blocks are not re-read.
- The connector has been tested against recorded JSON-RPC responses in the shape of the specification, not yet
  against a live endpoint; the first live sync is on the backlog.
