Fetch Solana Logs

中文版：SKILL.zh.md

Agent-first workflow: when the user wants txs for a Solana address, do not stop at explaining — configure the address and start pulling.

address from user
  → validate with isSolanaAddress (must pass)
  → ensure project (scaffold if needed)
  → write target_solana_addr.json
  → ensure .env (HELIUS_API_KEY)
  → pnpm s1 → pnpm s2
  → report output paths

When to use (triggers)

Start this skill immediately on asks like:

| User says | Action | |-----------|--------| | 「帮我获取 / 拉取某个 Solana 地址的 tx」 | Auto-config + pull | | 「帮我拉这个 program 的交易 / instruction」 | Auto-config + pull | | 「fetch txs for <base58>」 | Auto-config + pull | | Pastes a Solana address + wants history / logs | Auto-config + pull |

Do not use for EVM logs (→ fetch-evm-logs), stats-only analytics, or general Solana Q&A without wanting txs.

Mandatory agent behavior

Once the user names an address, execute the following. Do not pull until validation passes.

0. Validate address (isSolanaAddress) — required before anything else

Use the project helper (do not invent your own check):

import { isSolanaAddress } from './src/utils/utils';
isSolanaAddress(addr) // must be true

Or run:

pnpm validate -- --addr <ADDR>
# or after writing JSON:
pnpm validate

• If false / exits non-zero → stop, tell the user it is not a valid Solana address, ask for a corrected base58 pubkey. Do not write it to target_solana_addr.json or call s1.
• s1/s2 also call isSolanaAddress via validateAddresses in common.ts as a second guard.

1. Ensure project

If cwd (or an agreed dir) already has src/tx_logs/s1.pull.tx.ts, use it.

Otherwise scaffold:

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

Default dir: ./fetch_solana_logs.

2. Write target_solana_addr.json

Only after isSolanaAddress passes. Persist the user’s address(es) here (project root):

["DLvbp3sZCdoK6FoGnMdLSP2NZCCZdVfSGHD8KAGazZQH"]

Rules:

• Multiple addresses → JSON array; each must pass isSolanaAddress
• New request for a different address → replace or append as the user implies (default: set to the address(es) they just named)

3. Ensure .env

Need HELIUS_API_KEY for reliable pulls.

• If the user provides HELIUS_API_KEY, create <project>/.env immediately and write:

  HELIUS_API_KEY=<user-provided-key>
  

• Write the key directly to the project being operated on; do not put it in the skill directory or print the key in logs/responses

• If .env already exists, update only HELIUS_API_KEY and preserve unrelated entries

• If .env is missing and no key was supplied → copy from .env.example

• If key is empty → ask once for the key, write it, then continue

• If user has no key → still run with --limit (public RPC fallback); warn about rate limits

When scaffolding and the key is already available, pass it through the environment so init-project.sh creates .env:

HELIUS_API_KEY="$HELIUS_API_KEY" \
  bash ~/.cursor/skills/fetch-solana-logs/scripts/init-project.sh [target_dir]

4. Pull + parse (start immediately)

Default for a new “帮我拉一下” request (user did not specify full history):

pnpm s1 -- --limit 50
pnpm s2

This reads addresses from target_solana_addr.json.

Overrides:

| User intent | Command | |-------------|---------| | Recent N txs | pnpm s1 -- --limit N then pnpm s2 | | Only one addr while JSON has many | pnpm s1 -- --addr <ADDR> --limit 50 then same for s2 | | Full history (needs Helius) | pnpm s1 (no --limit) then pnpm s2 | | Re-pull clean | delete output/<addr>/ then s1/s2 |

5. Report results

Tell the user:

• Which address(es) were written to target_solana_addr.json
• Output paths under output/<addr>/
• Whether IDL was auto-saved; if program has no on-chain IDL and decode is needed, ask for IDL JSON and write output/<addr>/idl_<addr>.json, then re-run pnpm s2

If address is missing

User said “帮我获取 Solana 的 tx” with no address → ask only:

请提供 Solana 地址（base58）。

Then go straight to steps 2–5. Do not ask for unnecessary options up front.

IDL notes

• s1 auto-tries on-chain Anchor IDL → output/<addr>/idl_<addr>.json
• Optional probe: node ~/.cursor/skills/fetch-solana-logs/scripts/probe-idl.mjs --addr <ADDR> (run inside project after pnpm install)
• Never invent an IDL

Output layout

output/<addr>/
  ├── idl_<addr>.json              # if found / user-provided
  ├── tx_logs_<addr>.txt           # s1 NDJSON
  └── tx_logs_parsed_<addr>.json   # s2 (+ parsed instructions when IDL works)

Checklist (agent)

- [ ] isSolanaAddress(addr) === true (pnpm validate)
- [ ] Project ready (existing or init-project.sh)
- [ ] Address(es) written to target_solana_addr.json
- [ ] HELIUS_API_KEY in .env (or public-RPC fallback acknowledged)
- [ ] pnpm s1 (default --limit 50) completed
- [ ] pnpm s2 completed
- [ ] User told output paths / IDL status

Pitfalls

• Invalid address → fail validation; never write/pull
• Always use pnpm s1 -- --limit 50 form (-- before flags)
• Full sync without --limit requires Helius
• Wallets / non-Anchor programs may have no IDL — txs still pull fine

Additional Resources

• SKILL.zh.md — Chinese version
• scripts/init-project.sh
• scripts/probe-idl.mjs
• reference.md
• examples.md