fetch-evm-logs

Fetch EVM Logs

Pull event logs from any EVM contract on any EVM-compatible chain (Ethereum mainnet/testnets, L2s, sidechains, custom chains) — not limited to a specific protocol or event type. You only need chainId, contractAddress, an RPC, and an ABI (auto-fetched or user-provided).

Self-contained skill: scaffold → chainId + address → get ABI → pick events → pull + parse.

init-project.sh
  → ask chainId + contractAddress (+ rpc)
  → ABI: public fetch OR user-provided
  → list events → user picks → contract.ts → pnpm s1 → pnpm s2

Templates: this skill's templates/ (no external repo).

When to use (triggers)

Scope: any EVM contract / any chain that speaks JSON-RPC eth_getLogs — ERC-20, NFT, distributor, DEX, custom contracts, etc.

Use this skill when the user wants raw/on-chain event logs from an EVM smart contract. Typical asks:

If they only have a vague ask (「帮我获取智能合约的日志」) without address/chainId, still start this skill, then ask for chainId + contractAddress in Step 1.

Do not use for:

• Aggregating / stats / CSV claim rates → evm-log-stats
• Deploying contracts, writing Solidity, or general chain Q&A without wanting logs

Step 0 — Initialize project

If no project yet:

bash ~/.cursor/skills/fetch-evm-logs/scripts/init-project.sh [target_dir]

Default: ./fetch_evm_logs. Then continue below.

Step 1 — Ask for chainId + contractAddress

Required from user:

Ask clearly, e.g.:

请提供 chainId 和合约地址 contractAddress。如有专用 RPC 也可一并提供。

Step 2 — Get ABI (public fetch or user-provided)

ABI cannot be read from JSON-RPC bytecode alone. Two valid ways to obtain it:

A. Try public verified-contract sources first

node ~/.cursor/skills/fetch-evm-logs/scripts/fetch-abi.mjs \
  --chainId  --address <0x...> --out /src/abi

1. Sourcify (no API key)
2. Etherscan-compatible API if ETHERSCAN_API_KEY is set (or user provides a key)

B. User-provided ABI (always allowed; required if A fails)

If public fetch fails, the contract is unverified, or the user already has the ABI — ask the user to provide it:

公开源未能找到该合约 ABI。请粘贴完整合约 ABI JSON（或至少包含目标 event 的 fragment），也可提供本地 ABI 文件路径。

Accept:

• Paste JSON in chat
• Point to a local file

Then write it to:

src/abi/abi_{address}_{chainId}.json

(address lowercase). Do not invent or guess ABI.

List events and confirm

node ~/.cursor/skills/fetch-evm-logs/scripts/list-events.mjs \
  --abi /src/abi/abi_{address}_{chainId}.json

Show the event list to the user and ask which to fetch:

该合约 ABI 中有以下 event：…
需要拉取哪些？可选：全部 / 指定若干个 event 名称。

Do not skip this confirmation when multiple events exist (unless they already said “全部”).

Step 3 — Configure

ABI path

src/abi/abi_{address}_{chainId}.json

(address lowercase)

src/contract.ts

export const Contracts = {
  contracts: {
    MyContract: {
      address: '0x...',
      chainId: 41443,
      // string OK; array = ordered failover on RPC errors
      rpc: ['https://primary-rpc.example', 'https://backup-rpc.example'],
      startBlock: 0,
      endBlock: 'latest',
      // '*' = all ABI events; or string[] of event names
      eventNames: ['Transfer', 'Approval'],
      tokenDecimals: 18,
    },
  },
};

• rpc: string | string[] — on failure, retries then rotates to the next URL
• eventNames: '*' → pull all logs from the contract (no topic filter)
• eventNames: ['Foo', 'Bar'] → topic0 OR filter for those events
• ABI loaded automatically via address + chainId

Step 4 — Run

cd 
pnpm s1    # → output/{address}_{chainId}/logs.txt
pnpm s2    # → output/{address}_{chainId}/logs.json

Stop after s2.

Output layout

output/{address}_{chainId}/
  ├── logs.txt
  └── logs.json

Parsed log:

{
  txHash: string;
  logIndex: number;
  blockNumber: number;
  eventName: string;
  data: Record;
}

Checklist

- [ ] Project scaffolded (if needed)
- [ ] User gave chainId + contractAddress
- [ ] ABI obtained (public fetch **or** user-provided) → abi_{address}_{chainId}.json
- [ ] Events listed; user chose which to fetch
- [ ] contract.ts configured
- [ ] pnpm s1 && pnpm s2

Pitfalls

• Unverified / private-chain contracts → public fetch fails; ask user for ABI (do not block)
• Prefer multiple RPCs in rpc: [...] so failover can recover from rate limits / outages
• Large block ranges → lower pageSize in s1 (default 1000)
• ABI filename must be abi_{address}_{chainId}.json (lowercase address)

Additional Resources

• scripts/init-project.sh
• scripts/fetch-abi.mjs
• scripts/list-events.mjs
• reference.md
• examples.md