onchain-monitor

<!-- autoresearch: variation B — sharper output (decoded transfers + counterparty labels + ranked USD-denominated one-liners + TL;DR lede); folds in A's Alchemy+Etherscan-v2 input path and C's persistent state + source-status footer + dedup. -->

${var} — Watch label or chain to check. Empty = all watches. add-address:<0x… [chain]> is the shape the Telegram force-reply sends — it appends a new watch and exits (see step 0).

If ${var} is set, only monitor the watch with that label or watches on that chain.

Config

Reads memory/on-chain-watches.yml. If the file is missing or watches: [], offer to add the first watch via a Telegram force-reply (only if no add-address prompt was offered in the last 2 days of memory/logs/ — dedup so an unconfigured fork isn't nagged every run), then log ON_CHAIN_NO_CONFIG and exit cleanly (do not send an alert — empty config is not an error):

./notify "No addresses on watch yet. Paste one to monitor — a 0x… wallet, optionally its chain." \
  --force-reply --placeholder "0x… base" \
  --context "onchain-monitor::add-address"

The reply routes back as var=add-address:<0x… [chain]>, handled by the config-capture branch in step 0. Record FORCE_REPLY_OFFERED: add-address in the log when you send it.

# memory/on-chain-watches.yml
watches:
  - label: My Wallet
    address: "0x1234...abcd"
    chain: ethereum          # ethereum | base | arbitrum | optimism | polygon | robinhood
    type: wallet             # wallet | contract
    threshold_usd: 1000      # alert on transfers ≥ this USD value (default 1000)
  - label: Uniswap Pool
    address: "0xabcd...5678"
    chain: ethereum
    type: contract
    event_topics:            # optional — only alert on these topic0 hashes
      - "0xddf252ad..."      # ERC20 Transfer

Optional memory/known-addresses.yml — counterparty label dictionary used to humanize alerts. Lowercase keys, free-text values:

labels:
  "0x28c6c06298d514db089934071355e5743bf21d60": "Binance 14"
  "0xa9d1e08c7793af67e9d92fe308d5697fb81d3e43": "Coinbase 10"
  "0xe592427a0aece92de3edee1f18e0157c05861564": "Uniswap V3 Router"
  "0x0000000000000000000000000000000000000000": "Zero (mint/burn)"

State

memory/on-chain-state.json — per-watch state, persisted atomically after each successful run:

{
  "My Wallet": {
    "last_block": 19345678,
    "last_run": "2026-04-20T12:00:00Z",
    "last_block_hash": "0x…",
    "alerted_tx": [
      {"hash": "0xabc...", "block_number": 19345690, "first_seen": "2026-04-20T12:00:00Z"},
      {"hash": "0xdef...", "block_number": 19345702, "first_seen": "2026-04-20T12:00:00Z"}
    ],
    "median_usd_30d": 8500
  }
}

• last_block — start block for the next run's fetch. Initialise to current_block − 2400 (≈ 8h ETH) on first run; on robinhood (~0.1s blocks) use current_block − 280000 for the same ≈ 8h window. On robinhood, also cap every later run at that span: if current_block − last_block is more than 280000 (a delayed or caught-up run; 12h late is ~420k blocks, 15 windows per direction per watch), start from current_block − 280000 and log CLAMPED: skipped <n> blocks for that watch, so a late run degrades to "last ~8h" instead of walking the whole gap.
• last_block_hash — the canonical hash observed for last_block on the previous successful run. Before fetching new events, read that block again. If the hash differs, log REORG: block <n> changed <old> → <new>, rewind the watch to max(0, last_block − 12) (or the chain's documented finality depth), and replay the range. Do not send an alert until the replay completes. Keep normal transaction-hash dedup during the replay: a reorg can re-mine the same transaction in a new block, and that must not alert twice. Legacy string entries from earlier state are hashes and dedup the same way.
• alerted_tx — objects {hash, block_number, first_seen} for txs alerted in the last 7 days, capped at 200. Used for cross-run dedup by hash; purge by first_seen. block_number is the block the alert was seen in, kept for the audit trail.
• median_usd_30d — rolling median USD size of transfers at this watch; powers the WHALE-TRANSFER tag.

Write the file via mv from a tempfile so a mid-run failure cannot corrupt state. mv is not an allowed Bash command here, so do that move inside one python3 -c call (write the tempfile, then os.replace it onto the target), or write the whole file in one step with Write.

Steps

Read memory/MEMORY.md, memory/on-chain-watches.yml, memory/on-chain-state.json, and the last 2 days of memory/logs/ (for visibility only — state lives in the JSON file).

0. Config capture (Telegram force-reply)

Before the per-watch loop, intercept the add-a-watch reply. When ${var} starts with add-address:, the operator replied to the force-reply prompt (offered in the Config section on an empty config) - append a watch and exit (no monitoring this invocation). The remainder is <address> [chain].

Shell shape. Each Bash call is one allowed command (pipes are fine). The run refuses a call that sets a variable (ADDR="$(...)", KEYQ="", cutoff=$(date ...)), uses case / if / for or a [ ... ] && test, joins commands with ;, && or ||, or appends to a repo file with >> / cat >>, and sed, awk, printf, touch, rm and mv are not allowed commands; each refusal costs a model turn. So parse ${var} in your head, edit memory/ files with Write/Edit, write every network slug, chain id, address, block number and window into each command literally (the <ADDRESS>, <FROM_BLOCK> style placeholders in the snippets), make one call per watch, direction and window, and do file pruning and atomic writes inside one python3 -c call.

Work it out in your head, not in a shell script:

1. REST = the text after add-address:, leading spaces trimmed. ADDR = its first word; CHAIN = its second word lowercased, or ethereum when there is none. A CHAIN that is not one of ethereum|base|arbitrum|optimism|polygon|robinhood becomes ethereum.
2. If ADDR is not 0x plus 40 hex characters (case-insensitive), send this (ADDR written in literally) and stop:

   ./notify "Couldn't read \"<ADDR>\" as an address. Reply with a 0x… wallet, optionally a chain."
   

3. Read memory/on-chain-watches.yml (Read; create it with Write as watches: if it is missing). With Edit, turn a watches: [] line into watches:, and add a watches: line if there is none, so block items can be appended.
4. If the file already contains ADDR (case-insensitive), send ./notify "Already watching <ADDR>." and stop.
5. Otherwise SHORT = ADDR's first 6 characters (0x plus 4), then …, then its last 4. Append this block to the end of the file with Edit:

     - label: "<SHORT>"
       address: "<ADDR>"
       chain: <CHAIN>
       type: wallet
       threshold_usd: 1000
   

   then send:

   ./notify 'Now watching <SHORT> on <CHAIN> (wallet, moves ≥$1000). Edit memory/on-chain-watches.yml to tune.'
   

6. Log under ### onchain-monitor: - view: add-address (var="${var}") → <ADDR> on <CHAIN>, then exit.

Defaults for a captured watch: type: wallet, threshold_usd: 1000, label = the shortened address. The operator refines chain/type/threshold by editing memory/on-chain-watches.yml directly. (This appends to the end of the file, which is correct because watches: is the only top-level key — if a future config grows more keys, insert under watches: instead of at EOF.)

For each watch (filtered by ${var}):

1. Fetch raw activity from last_block → the pinned to_block

Once per chain at the start of the run, resolve current_block and its hash. That number is the chain's to_block: every watch on that chain, and every source (Alchemy, Etherscan, RPC), queries up to it and no further. Never send latest, endblock=99999999 or an open-ended range. Each watch keeps its own from_block (its last_block, after the clamp and any reorg rewind). For a watch with last_block_hash, perform the reorg check above before constructing any query windows.

Path A — Alchemy (preferred, if ALCHEMY_API_KEY set).

Wallets use alchemy_getAssetTransfers - one call returns categorized in/out history with value, asset, category, hash, from, to, metadata.blockTimestamp. Run it twice per watch (once with toAddress, once with fromAddress) and merge. Write the network slug, the address and both blocks in literally; <FROM_BLOCK_HEX> / <TO_BLOCK_HEX> are the block numbers as hex digits without the 0x (convert them yourself):

./secretcurl -m 10 -s -X POST "https://<NETWORK>.g.alchemy.com/v2/{ALCHEMY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"alchemy_getAssetTransfers","params":[{
    "fromBlock":"0x<FROM_BLOCK_HEX>",
    "toBlock":"0x<TO_BLOCK_HEX>",
    "toAddress":"<ADDRESS>",
    "category":["external","internal","erc20","erc721","erc1155"],
    "withMetadata":true,"excludeZeroValue":true,"maxCount":"0x32"
  }]}'

Contracts use eth_getLogs against the same Alchemy URL, with numeric hex fromBlock / toBlock set to the watch's from_block / the chain's to_block. Alchemy allows any block range while the response stays under 10,000 logs, and unlimited results for ranges of 5,000 blocks or fewer; on Log response size exceeded, re-query in 5,000-block windows (a busy robinhood contract hits this within minutes of ~0.1s blocks).

Chain → network slug: ethereum=eth-mainnet, base=base-mainnet, arbitrum=arb-mainnet, optimism=opt-mainnet, polygon=polygon-mainnet, robinhood=robinhood-mainnet. On robinhood, drop "internal" from the wallet category list: Alchemy rejects it there ("The 'internal' category is not supported for this network").

Path B — Etherscan v2 unified (fallback, if Alchemy path fails or key unset).

Single endpoint, all 50+ chains via chainid. Works keyless at lower rate limit. Key check: read the "Keys set for this run" line in your run notes, never a shell test (those are refused and cost a turn). Append the key only when ETHERSCAN_API_KEY is on that line: then <KEYQ> below is &apikey={ETHERSCAN_API_KEY} (./secretcurl's placeholder; a bare $ETHERSCAN_API_KEY is refused by the Bash permission analyzer), otherwise <KEYQ> is left out (keyless works). Chain id, address and decimal blocks are written in literally, one call each.

Wallet, token transfers:

./secretcurl -m 10 -s "https://api.etherscan.io/v2/api?chainid=<CHAINID>&module=account&action=tokentx&address=<ADDRESS>&startblock=<FROM_BLOCK>&endblock=<TO_BLOCK>&sort=desc<KEYQ>"

Wallet, normal transactions:

./secretcurl -m 10 -s "https://api.etherscan.io/v2/api?chainid=<CHAINID>&module=account&action=txlist&address=<ADDRESS>&startblock=<FROM_BLOCK>&endblock=<TO_BLOCK>&sort=desc<KEYQ>"

Contract:

./secretcurl -m 10 -s "https://api.etherscan.io/v2/api?chainid=<CHAINID>&module=logs&action=getLogs&address=<ADDRESS>&fromBlock=<FROM_BLOCK>&toBlock=<TO_BLOCK><KEYQ>"

Chain → chainid: ethereum=1, base=8453, arbitrum=42161, optimism=10, polygon=137, robinhood=4663. Etherscan's free tier refuses chainid=4663 ("Free API access is not supported for this chain"), so a keyless robinhood watch skips Path B and uses Path C.

Path C — Robinhood Chain public RPC (robinhood only; keyless fallback when Path A is unavailable and Path B is refused).

Wallets: ERC-20 Transfer logs with the watch address as recipient, then as sender. The public RPC caps a query without an address filter at 30,000 blocks, so walk from_block → to_block (the chain's pinned block) in 30,000-block windows (≈ 10 windows per direction per 8h, ≈ 28 per day). Contracts: eth_getLogs with address set (no 30,000 cap). For both wallets and contracts, if a window answers logs matched by query exceeds limit of 10000, halve it and query both halves, repeating until each piece fits; a busy address hits this inside one 30,000-block window (the v4 PoolManager returns ~29.7k logs there, which takes 3 splits and 7 calls). One call per window and direction, everything written in literally: topic0 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef is the ERC-20 Transfer; <ADDR_TOPIC> is the 32-byte topic 0x000000000000000000000000 followed by the watch address without its 0x; <LO_HEX> / <HI_HEX> are the window bounds (hi - lo < 30000) as 0x-hex, converted yourself (the RPC rejects decimal).

Incoming:

curl -m 15 -s -X POST https://rpc.mainnet.chain.robinhood.com -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"<LO_HEX>","toBlock":"<HI_HEX>","topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",null,"<ADDR_TOPIC>"]}]}'

Outgoing:

curl -m 15 -s -X POST https://rpc.mainnet.chain.robinhood.com -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"<LO_HEX>","toBlock":"<HI_HEX>","topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef","<ADDR_TOPIC>"]}]}'

ERC-721 Transfer has the same topic0 and also matches these filters. Tell them apart by topic count: 3 topics = ERC-20 (amount in data); 4 topics = ERC-721 (data is empty, the token id is topics[3]). Keep 3-topic logs as erc20; tag 4-topic logs erc721 and never call decimals() on them (NFT contracts revert). Read symbol() / decimals() per distinct ERC-20 token with eth_call (0x95d89b41 / 0x313ce567) on the same RPC. Path C sees token transfers only, not native ETH transfers; note path=rpc (tokens only) in the source footer. On HTTP 429, back off and retry the window; if it still fails, mark the watch fail as below.

Fetch fallback. Both Alchemy and Etherscan carry their key in the URL via ./secretcurl ({ALCHEMY_API_KEY} / {ETHERSCAN_API_KEY} placeholders), so if a call fails, retry the exact same URL via WebFetch. For POSTs, WebFetch accepts the JSON body. Path C needs no key; on a non-429 failure, retry the same RPC POST through WebFetch the same way before marking the watch fail.

If every path for a watch fails, mark the watch fail in the source footer and continue to the next — never abort the whole run.

2. Decode every transfer

Required fields per event (normalised across Alchemy / Etherscan payloads):

Field	Source
tx_hash	hash / txHash
block_number, timestamp	blockNum / metadata.blockTimestamp
category	external_eth | erc20 | erc721 | erc1155 | internal | log
direction	in if to == watch, else out
token.symbol, token.decimals	Alchemy returns inline; for Etherscan, use tokenSymbol/tokenDecimal fields
value_token	human amount, e.g. 1,234,567.89 USDC
value_usd	value_token × price_usd (see step 3)
counterparty	the non-watch address on the transfer
counterparty_label	lookup in known-addresses.yml, else null

3. USD-enrich in one bulk call

Collect distinct (chain, token_contract) pairs from decoded transfers. Bulk price via CoinGecko, one call per chain with the chain and the comma-joined contracts written in literally. <CGQ> is &x_cg_demo_api_key={COINGECKO_API_KEY} when COINGECKO_API_KEY is on the "Keys set for this run" line in your run notes (never a shell test: those are refused and cost a turn), otherwise it is left out:

./secretcurl -m 10 -s "https://api.coingecko.com/api/v3/simple/token_price/<CHAIN>?contract_addresses=<JOINED>&vs_currencies=usd<CGQ>"

Native ETH/MATIC/etc. use simple/price?ids=ethereum,matic-network,.... If CoinGecko is unreachable or returns no price for a token, set value_usd = null and tag the event UNPRICED — keep it in the log, drop it from the notification (can't meaningfully threshold without USD).

4. Filter

Drop an individual event if any of:

• value_usd < threshold_usd (watch config, default $1000)
• value_usd < $0.10 (hard dust floor — prevents airdrop / phishing spam)
• tx_hash matches the hash field (or, for legacy entries, the string itself) of an entry in this watch's alerted_tx (cross-run dedup, also during a reorg replay)
• category == "log" and watch has event_topics: and the topic0 is not in the list

5. Categorize surviving events

Tag each event with one short label so the alert says what kind of move it was:

Tag	Condition
CEX-IN / CEX-OUT	counterparty label contains an exchange name (Binance, Coinbase, Kraken, OKX, Bybit, Bitfinex)
DEX-SWAP	counterparty label contains a router (Uniswap, 1inch, Curve, Sushi, Aerodrome, CoWSwap)
BRIDGE	counterparty label contains a bridge (Across, Stargate, Hop, Synapse, Wormhole, Celer)
MINT / BURN	counterparty is 0x000…000 or the token contract itself
WHALE-TRANSFER	value_usd > 10 × median_usd_30d for this watch
UNKNOWN-IN / UNKNOWN-OUT	fallback — based on direction

A single event can only carry one tag; pick by priority CEX > DEX > BRIDGE > MINT/BURN > WHALE > UNKNOWN.

6. Format the alert

One notification per run. Sort all surviving events globally by value_usd desc; group the output by watch label (watches with zero surviving events are omitted entirely). Lead with a one-sentence TL;DR naming the single biggest move.

*On-Chain Alert - ${today}*
TL;DR: My Wallet sent $1.2M USDC to Binance 14 (biggest move on any watch in 30d).

*My Wallet* (ethereum)
• CEX-OUT $1.2M USDC → Binance 14 - [tx](https://etherscan.io/tx/0x...)
• DEX-SWAP $42k WETH → USDC via Uniswap V3 Router - [tx](https://etherscan.io/tx/0x...)

*Uniswap Pool* (ethereum)
• WHALE-TRANSFER $850k WETH out → 0x9f...a1 - [tx](https://etherscan.io/tx/0x...)

3 events on 2 watches | sources: alchemy=ok, coingecko=ok, etherscan=skipped | last_block→${block}

Cap the notification body at 10 events; if more survived, append +N more — see memory/logs/${today}.md. The ./notify call should use the explorer URL for each chain (etherscan.io, basescan.org, arbiscan.io, optimistic.etherscan.io, polygonscan.com, robinhoodchain.blockscout.com).

Send the alert with ./notify -f alert.md.

6.1 Evidence mode — make every alert replayable

When at least one watch completes, write a compact evidence receipt to memory/evidence/${today}-${run_id}.json before sending the notification. This is an audit trail, not a safety verdict: it records what was queried and which source answered, but it does not prove that an external RPC is honest.

run_id is the UTC start timestamp with : replaced by -. The receipt must contain:

{
  "schema": "aeon.onchain-monitor.evidence.v1",
  "run_id": "2026-04-20T12-00-00Z",
  "chains": [{
    "chain": "robinhood",
    "chain_id": 4663,
    "from_block": 92300000,
    "to_block": 92347891,
    "block_hash": "0x…",
    "sources": {"rpc": "ok", "alchemy": "skipped", "coingecko": "ok"},
    "query_windows": 12,
    "watches": 2,
    "raw_events": 16,
    "kept_events": 2,
    "dropped_events": 14,
    "unpriced_events": 0,
    "tx_hashes": ["0x…"]
  }],
  "sha256": "<digest of this object without sha256>"
}

Rules:

• Emit one entry in chains for every chain represented by the completed watches; never merge ranges, block hashes, source statuses, counters, or tx hashes across chains. A run may span multiple chains.
• Pin each chain entry's from_block and to_block to its actual request range. Do not use latest in the receipt; resolve it to a number first.
• Fetch each chain entry's block_hash for to_block from the same source when possible. If the source cannot provide it, use null and mark that source degraded.
• Record every split query in each chain entry's query_windows; this makes the Robinhood 10,000-log fallback visible instead of silently changing the sample.
• Lowercase each chain entry's tx_hashes and block_hash, sort the hashes lexicographically and remove duplicates. Never include API keys, full RPC URLs containing credentials, or raw response bodies.
• Canonicalise the JSON with sorted keys, compact separators and UTF-8 text with no \u escapes (in Python: json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()), compute SHA-256 using a standard-library implementation, then add the sha256 field and write atomically via a temporary file and mv (os.replace in the same python3 -c call, since mv is not an allowed Bash command). Python's default ensure_ascii=True produces a different digest as soon as a label contains non-ASCII text.
• Before writing, create memory/evidence/ if needed and prune receipts older than 30 days by the date in the filename, not by mtime (every Actions run is a fresh checkout, so mtime is always today). Files that do not start with a YYYY-MM-DD- date are left alone: First date -u -d '30 days ago' +%Y-%m-%d as its own call (it prints CUTOFF), then one python3 -c call with CUTOFF written in literally (a shell for loop with rm is refused):

  python3 -c 'import glob, os, re; [os.remove(f) for f in glob.glob("memory/evidence/*.json") if os.path.isfile(f) and re.match(r"\d{4}-\d{2}-\d{2}-", os.path.basename(f)) and os.path.basename(f)[:10] < "<CUTOFF>"]'
  

  A pruning failure is non-fatal but must make the source footer evidence=fail.
• Include the receipt path and digest in the alert footer before calling ./notify: evidence: memory/evidence/<file> · sha256:<first 12 hex chars>.
• If receipt writing fails, continue the monitor run but mark the source footer evidence=fail; never claim that the alert is independently verified.

6.2 Verify a receipt offline (optional)

Operators can verify a receipt written by step 6.1 without contacting a chain, RPC, price API, or GitHub:

node scripts/verify-onchain-evidence.mjs memory/evidence/<file>.json

The verifier accepts only aeon.onchain-monitor.evidence.v1. It recomputes the SHA-256 over the receipt with sha256 removed, recursively sorts object keys, uses compact UTF-8 JSON, and checks chain-local ranges, counters, block hashes, source degradation, and sorted unique transaction hashes. It also rejects credential-bearing URLs, secret-like fields, and raw response-body fields.

Exit code 0 means the file is internally consistent. Exit code 1 identifies the failed field or invariant; exit code 2 means the input path was omitted. This checks internal checksum and schema consistency only. Anyone able to replace the receipt can also recompute its digest, so this is not a signature or proof of authorship. It does not prove that an RPC was honest, that the chain was final, or that the receipt describes external reality. Secret detection is best-effort, not a guarantee that all sensitive content is absent. The verifier performs no network access.

7. Persist state and log

For each watch whose fetch succeeded (success ≠ "events found"):

• last_block ← to_block (the chain's pinned current_block)
  • last_block_hash ← hash(to_block) from that same pinned block read
• last_run ← now (ISO 8601 UTC)
• alerted_tx ← (new_alerted_entries + alerted_tx)[:200], where each new entry is {hash: tx_hash, block_number, first_seen: now}; purge entries whose first_seen is older than 7d
• median_usd_30d ← median of all value_usd from this watch's transfers in last 30d (read from recent logs; skip recomputation if < 5 samples)

Write memory/on-chain-state.json atomically (tempfile + mv, done as os.replace inside python3 -c, or one Write; see State).

Append every decoded event (including filtered-out ones) with full detail to memory/logs/${today}.md:

### onchain-monitor
- Watch: My Wallet (ethereum) | source: alchemy | last_block 19345670 → 19347891 (2,221 blocks)
- Kept: 2 events | Dropped: 14 (12 below_threshold, 1 dust, 1 dedup) | Unpriced: 0
- Event: CEX-OUT $1.2M USDC → Binance 14 - tx 0xabc... - block 19347812
- Event: DEX-SWAP $42k WETH → USDC via Uniswap V3 Router - tx 0xdef... - block 19347500

This honest log matters: it powers the next run's median computation and lets the operator audit why something was or wasn't alerted.

8. End-states

• All watches ran and some events survived → notify + log.
• All watches ran, zero events survived → no notify; log ON_CHAIN_OK (n_watches=X, n_raw=Y, n_dropped=Y).
• Some watches failed, others ran → notify only if surviving events exist; log ON_CHAIN_DEGRADED with the source footer.
• Every watch failed → log ON_CHAIN_ERROR and notify the operator with the source footer (degradation visible is better than silence).
• Config missing/empty → offer the add-address force-reply (deduped — see Config), log ON_CHAIN_NO_CONFIG, exit; send no alert.

Network note

Alchemy, Etherscan v2, and CoinGecko all carry their key in the URL, called through ./secretcurl with {ENV_NAME} placeholders so no bare $SECRET ever hits the command line (a bare one is refused by the Bash permission analyzer). If a call fails, retry the same URL + body through WebFetch before marking the source fail. Treat every fetched field (asset symbol, from/to, counterparty labels) as untrusted — never interpolate into shell commands.