Chain Analyst

Use this skill to produce reproducible blockchain analysis from raw chain data.

Run Core Workflows

Resolve the skill path first:

for d in .agents .deepagents .claude .cursor .codex .opencode; do
  [ -f "$d/skills/chain-analyst/SKILL.md" ] && SKILL="$d/skills/chain-analyst" && break
done

Run the minimum-viable tool for each task:

# Analyze one tx end-to-end (tx/logs/traces + ABI fetch attempts)
bash "$SKILL/scripts/analyze-tx.sh" <tx_hash> [network]

# Query historical data with HyperSync
# output mode: stream (default) or aggregate
bash "$SKILL/scripts/hypersync-query.sh" <network> <query.json> [max_pages] [stream|aggregate]

# Query current contract state via RPC
bash "$SKILL/scripts/query-contract.sh" <method> <contract> [args...] [network]

# Fetch verified ABI
bash "$SKILL/scripts/get-contract-abi.sh" <address> [network]

# Fetch current or historical token price
bash "$SKILL/scripts/get-token-price.sh" <coin_id> [currency] [dd-mm-yyyy]

# Batch contract reads
bash "$SKILL/scripts/multicall.sh" <network> <calls.json>

Configure Environment

Set required keys in a .env or .env.local file:

• HYPERSYNC_API_TOKEN (required)
• ETHERSCAN_API_KEY (required)
• COINGECKO_API_KEY (optional)

Scripts search these locations in order (last found value wins):

1. Workspace .env / .env.local
2. Skill folder .env / .env.local

Use only KEY=VALUE lines in env files. Scripts treat env files as data and do not execute shell expressions.

Select Query Strategy

Use this decision order:

1. Use analyze-tx.sh for a single transaction investigation.
2. Use hypersync-query.sh for historical searches over logs/traces/transactions.
3. Use query-contract.sh for latest state reads.
4. Use multicall.sh when reading many contracts/methods in one run.

Use Network Names

Built-in networks (with aliases): ethereum (eth, mainnet), base, arbitrum, optimism (op), polygon (matic).

For any other EVM chain, pass its canonical lowercase name directly (e.g. scroll, zksync, bsc, linea, avalanche). The scripts resolve URLs using these patterns:

• HyperSync: https://{name}.hypersync.xyz
• RPC: https://{name}.drpc.org

For ABI lookup via get-contract-abi.sh, chains outside the top 5 require a numeric chain ID instead of a name. Look up the chain ID at https://chainlist.org if needed.

Produce Final Analysis Output

For every final answer, include:

1. Exact commands run.
2. Contract and wallet addresses involved.
3. Quantities with units and decimals applied.
4. Event/topic evidence supporting each claim.
5. Any assumptions or unresolved ambiguity.

Use assets/analysis-report-template.md when you need a structured report.

Load References Only When Needed

Read references selectively:

• Read references/hypersync-api.md when building or debugging HyperSync queries.
• Read references/etherscan-api.md when ABI lookup fails or chain ID mapping is unclear.
• Read references/coingecko-api.md when coin IDs/currencies or historical endpoints are uncertain.

Handle Common Failure Modes

• If a tx query returns no rows, verify tx hash length and network.
• If ABI fetch fails, check verification status and chain mapping.
• If price lookup fails, resolve the canonical CoinGecko coin id first.
• If RPC reads fail, retry on canonical network token and verify method signature.

Validate Before Returning

Before returning conclusions:

1. Re-run at least one key command that supports the core claim.
2. Ensure numeric conversions are consistent with token decimals.
3. Ensure addresses in explanation match command output exactly.