Coin lineage

Coin lineage

You are tracing a Chia coin's lineage: walking back through its parents (provenance) or forward through its children (where did it go). Each step is classified by puzzle type — plain XCH, CAT, NFT, DID, settlement-payments — and any known destination address (exchanges, market makers, prefarm wallets) is labelled.

This skill follows the conventions in this repo's SKILLS.md. Read that if anything below is unclear.

Required capabilities

• chia-explorer (mcp__chia-explorer__*) — mandatory. Uses get_coin_by_name, get_coin_records_by_parent_ids, get_puzzle_and_solution, decompile_puzzle, list_prefarm_addresses.

Resolve inputs

You need: $coin_id, $direction, $hops.

• $coin_id — coin name as 0x... hex (32 bytes / 64 hex chars). Required.
• $direction — one of back (walk parents), forward (walk children), or both. Default back.
• $hops — how many hops to walk. Default 5. Hard cap at 20 to keep RPC pressure bounded.

Resolve: arguments → context → ask user.

Validate $coin_id (32 bytes hex). Reject anything else.

If $hops > 20, cap it and tell the user inline ("walking 20 hops max — bump in the skill if you need more").

Walk back (provenance)

Start from the supplied coin. For each hop:

1. Look up the coin record by name. Capture: parent_coin_info, puzzle_hash, amount, spent_block, created_block.
2. Decompile the puzzle at the spent block to classify the coin (XCH / CAT / NFT / DID / settlement / unknown).
3. Convert the puzzle_hash to a bech32m address. Check chia-explorer's prefarm registry for a label; if matched, attach it (prefarm: swiss_cold, exchange: HTX, etc.).
4. Move to parent_coin_info as the next coin_id to look up.

Stop conditions:

• Hit the configured $hops limit.
• Reach a coin whose parent is a coinbase / farming reward (height-encoded parent). Note this as the lineage origin.
• Reach a coin that can't be resolved (chia-explorer returns nothing). Note "lineage broken".

Walk forward (where did it go)

Start from the supplied coin. For each hop:

1. Verify the coin is spent. If unspent, the chain ends here — note "still unspent".
2. Call get_coin_records_by_parent_ids with the current coin as the parent to fetch the children.
3. For each child:
   • Classify (XCH / CAT / NFT / DID / etc.).
   • Resolve the puzzle_hash to an address; check the prefarm registry for a label.
4. If there's more than one child, the lineage branches. Walk each branch up to $hops levels deep but note the branching so the report is honest.

Stop conditions:

• Hit $hops.
• All children are unspent at the current frontier.
• A child has a known destination label (exchange / market maker) and the user only wanted "where did the money go": stopping at the labelled destination is more useful than walking further.

Both

Run back and forward independently. Render two trees in the report.

Compose the report

Inline ASCII tree, one line per hop, classification and address label visible.

Coin lineage — 0xabc...123 (back, 5 hops)

  0xabc...123   3.500 XCH    spent at 6,532,217   XCH (p2)
    → parent
  0xdef...456   3.550 XCH    spent at 6,532,210   XCH (p2)    addr: xch1zzz...
    → parent
  0x789...      10.000 XCH   spent at 6,531,800   XCH (p2)    addr: xch1aaa...  (exchange: Coinbase)
    → parent
  0x654...      10.000 XCH   farming reward at 6,531,799      (lineage origin)

For forward walks, show branching:

Coin lineage — 0xabc...123 (forward, 5 hops)

  0xabc...123   3.500 XCH    spent at 6,532,217   XCH (p2)
  ├─ child  0xfff...   2.000 XCH    XCH (p2)   addr: xch1bbb...
  │  └─ child  0xeee...   2.000 XCH   spent at 6,532,224   XCH (p2)   addr: xch1ccc... (exchange: HTX)
  └─ child  0xggg...   1.500 XCH    XCH (p2)   addr: xch1ddd...   (still unspent)

Trim coin ids and addresses to first 8 / last 6 chars in the tree. Always list the full ids in a short footer for copy-paste.

Risk and provenance notes

When you spot interesting things, surface them at the bottom:

• The lineage passes through a labelled exchange address — common provenance pattern.
• The lineage passes through the prefarm — note which custody wallet and at what height.
• One hop is a CAT melt (CAT → XCH) — note it; can be relevant to tax accounting.
• The lineage branches into many children at one step — possibly a batch send or a CAT puzzle.

Don't editorialise on whether the coin is "clean" or "dirty". Report observations.

Hard rules

• Read-only. Never sign, never broadcast.
• Hop cap is real. Don't trace 10,000 hops; that's an explorer's job, not a skill's.
• Always show full ids in the footer. Truncation in the tree is for readability; full values are for verification.
• Don't invent ownership. An address labelled "Coinbase" means it matches chia-explorer's registry. It does not mean the coin is or isn't legitimately on Coinbase.

Recovery patterns

• Coin not found. Emit STATUS: failed, REASON: coin not found by name.
• Puzzle decompile fails for one hop. Mark that hop "decode failed" but continue the walk.
• Forward walk explodes (200+ children at one step). Stop at that hop, summarise as "fan-out: N children, not walked further".

Output

STATUS: success | partial | failed | aborted
DIRECTION: back | forward | both
HOPS_WALKED: <int, may be less than requested if origin was reached>
TERMINAL: lineage_origin | unspent_frontier | hop_cap | broken_lineage
RISK_NOTES: <comma-separated tags, e.g. exchange_addr, prefarm_passthrough, cat_melt> | none
ARTIFACT: none
REASON: <one line, only when STATUS is failed, partial, or aborted>