{"name":"prove-a-transaction","title":"Prove a transaction","category":"Prove","summary":"One call returns the proof; two more check it against the chain and the root.","use_when":"You must show, or check, that a transaction happened and is under the superroot.","not_when":"You need a quality verdict on work, or a cross-chain transfer.","description":"Get a proof that one transaction is inside the Taifoon superroot and check it yourself: GET /v1/proof/tx/{chain}/{tx} returns the block, the superroot that commits to it, the portable V5 blob and the checks made; compare the block hash against your own RPC and the root against GET /v1/root. Use when an agent must show a counterparty that a payment, a delivery or any transaction happened on Base, Arc, Ethereum or another included chain, or must verify such a claim. Do NOT use to grade whether work met its spec (use grade-with-jev) or to move funds between chains (use bridge-with-proof).","license":"TSUL","compatibility":"bash, curl, jq; Taifoon coordination API v1 at https://coord.taifoon.dev/v1; any public RPC of the chain for the independent check","first_call":"GET /v1/proof/tx/{chain}/{tx}","success":"proof_state proven with every check true","verified":"2026-10-04","hash":"sha256:b5075d83313a36510207f4e69a30d09de835ebac821cace0bf20766ca799aa29","commands":{"ok":true,"blocks":7,"ran_at":"2026-10-04T09:42:40.628Z"},"urls":{"page":"https://www.taifoon.io/skills/prove-a-transaction","markdown":"https://www.taifoon.io/skills/prove-a-transaction.md","json":"https://www.taifoon.io/skills/prove-a-transaction.json","well_known":"https://www.taifoon.io/.well-known/skills/prove-a-transaction/SKILL.md","github":"https://github.com/taifoon-io/skills/tree/main/prove-a-transaction"},"install":{"cli":"npx skills add https://www.taifoon.io --skill prove-a-transaction","curl":"curl -sL https://www.taifoon.io/skills/prove-a-transaction.md"},"markdown":"---\nname: prove-a-transaction\ndescription: \"Get a proof that one transaction is inside the Taifoon superroot and check it yourself: GET /v1/proof/tx/{chain}/{tx} returns the block, the superroot that commits to it, the portable V5 blob and the checks made; compare the block hash against your own RPC and the root against GET /v1/root. Use when an agent must show a counterparty that a payment, a delivery or any transaction happened on Base, Arc, Ethereum or another included chain, or must verify such a claim. Do NOT use to grade whether work met its spec (use grade-with-jev) or to move funds between chains (use bridge-with-proof).\"\nlicense: TSUL\ncompatibility: \"bash, curl, jq; Taifoon coordination API v1 at https://coord.taifoon.dev/v1; any public RPC of the chain for the independent check\"\nmetadata:\n  title: \"Prove a transaction\"\n  category: \"Prove\"\n  summary: \"One call returns the proof; two more check it against the chain and the root.\"\n  use_when: \"You must show, or check, that a transaction happened and is under the superroot.\"\n  not_when: \"You need a quality verdict on work, or a cross-chain transfer.\"\n  first_call: \"GET /v1/proof/tx/{chain}/{tx}\"\n  success: \"proof_state proven with every check true\"\n  verified: \"2026-10-04\"\n---\n\n# Prove a transaction under the superroot\n\n## What this is\n\nThe layer folds the chains it includes into one superroot about every 10 seconds (`GET /v1/root` lists\n`chains_included`). `GET /v1/proof/tx/{chain}/{tx}` answers where a transaction landed, the superroot that commits to that\nblock, whether it is final, a portable V5 proof blob, and `checks` naming what was verified, including that the proof's\nblock hash equals the one in the transaction's own receipt. Proofs are free inside the free rate (90 a minute per key); past it a proof is 0.2 GRID from the key's balance (`GET /v1/access`).\n\n## Before you start\n\n- Base URL: `https://coord.taifoon.dev/v1`. No key needed.\n- A transaction hash and its chain id (8453 Base, 5042 Arc, 1 Ethereum, …).\n- For the independent check: any RPC of that chain you trust more than this API.\n\n```sh\nexport TAIFOON=https://coord.taifoon.dev/v1\ntf() { curl -sS -m 90 -H \"X-Taifoon-Client: taifoon-skill-prove-a-transaction\" -H \"content-type: application/json\" ${TAIFOON_API_KEY:+-H \"X-API-Key: $TAIFOON_API_KEY\"} \"$@\"; }\nCHAIN=${CHAIN:-8453}\nTX=${TX:-0x81464f5e6a8b6322e4bec8f609a08e8ec1f1ef11d39e5f5d51e3fa676c5f042a}   # a USDC burn on Base, block 52043043\n```\n\n## Pitfalls\n\n1. Reading `ok: true` as proven. Read `proof_state` and every entry of `checks`; `within_verifiable_range: false` means\n   the block is newer than the newest provable one (`verifiable_block`): ask again shortly.\n2. Comparing `super_root_hash` with a later `GET /v1/root`. The root changes about every 10 seconds; a proof is under the\n   root of its own `batch_id`. Compare the block hash, which never changes, and keep the blob.\n3. Trusting the same API for both sides of a comparison. Read the receipt's `blockHash` from your own RPC.\n4. Using `/gw/rpc` for the receipt. The gateway serves `eth_blockNumber`, `eth_call`, `eth_getLogs` and `eth_chainId`\n   only.\n5. Expecting a transaction proof on every chain in the root. `GET /v1/protocols/decoders` (`chains`) says which chains\n   the layer reads over RPC, where any transaction is provable, and which are header-committed, where a block proof\n   exists and a transaction proof through these routes does not.\n6. Treating a reverted transaction as a payment. `checks.tx_succeeded` must be true.\n\n## Steps\n\n### 1. The newest provable block of a chain\n\n```sh\ntf \"$TAIFOON/proof/verifiable/$CHAIN\" \\\n  | jq -e '(.superroot.superrootHash | test(\"^0x[0-9a-f]{64}$\")) and .chainHeaders[0].chainId == ('\"$CHAIN\"') and (.chainHeaders[0].blockNumber > 0)' >/dev/null\n```\n\n### 2. The proof of your transaction\n\n```sh\nPROOF=$(tf \"$TAIFOON/proof/tx/$CHAIN/$TX\")\necho \"$PROOF\" | jq -e '.ok and .proof_state == \"proven\" and .is_finalized\n  and .checks.receipt_found and .checks.tx_succeeded and .checks.proof_served and .checks.block_hash_matches and .checks.within_verifiable_range\n  and (.blob.superroot.superrootHash | test(\"^0x[0-9a-f]{64}$\")) and (.blob.superrootProof.siblings | length > 0)' >/dev/null\n```\n\nThe fields: `block_number`, `block_hash`, `is_finalized`, `proof_state`, `super_root_hash`, `batch_id`,\n`verifiable_block`, `checks { receipt_found, tx_succeeded, proof_served, block_hash_matches, within_verifiable_range }`,\nand `blob` (the V5 proof: `superroot`, `chainHeaders`, `superrootProof`, `blockProof`, `finality`).\n\n### 3. Check it against the chain yourself\n\nThe block hash in the proof must equal the one your own RPC gives for the transaction's receipt.\n\n```sh\nRPC=${RPC:-https://mainnet.base.org}\nMINE=$(curl -sS -m 30 -X POST \"$RPC\" -H 'content-type: application/json' \\\n  -d \"{\\\"jsonrpc\\\":\\\"2.0\\\",\\\"id\\\":1,\\\"method\\\":\\\"eth_getTransactionReceipt\\\",\\\"params\\\":[\\\"$TX\\\"]}\" | jq -r '.result.blockHash')\n[ \"$MINE\" = \"$(echo \"$PROOF\" | jq -r .block_hash)\" ]\n```\n\n### 4. Check the chain is in the root\n\n```sh\ntf \"$TAIFOON/root\" | jq -e '(.root | test(\"^[0-9a-f]{64}$\")) and (.chains_included | index('\"$CHAIN\"') != null) and .leaf_count > 0' >/dev/null\n```\n\n`GET /v1/root/chains` says what each chain contributed; `GET /v1/root/proof/{chain}/{block}` is the sibling path from one\nblock to the root; `GET /v1/proof/blocks/{chain}?blocks=a,b,c` proves up to 256 blocks in one call.\n\n### 5. The transaction itself, decoded\n\nUp to 25 transactions in one call: status, block, time, fee and every known event decoded.\n\n```sh\ntf \"$TAIFOON/chain/tx?chain=$CHAIN&hashes=$TX\" | jq -e '.txs[0].status == \"success\" and (.txs[0].events | type == \"array\")' >/dev/null\n```\n\n## Verify it works\n\n```sh\necho \"$PROOF\" | jq -e '.tx == \"'\"$TX\"'\" and .chain_id == ('\"$CHAIN\"')' >/dev/null\necho \"prove-a-transaction: proven in block $(echo \"$PROOF\" | jq -r .block_number), block hash equal to the chain's own\"\n```\n\n## What it costs\n\nInside the free rate, nothing (30 a minute without a key, 90 with a free key). Past it a proof is 0.2 GRID (0.002 USDC) from the key's balance; `GET /v1/access` is the price list, `buy-access` tops a key up. The other proof kinds (log, order, transition, blocks): `prove-anything`.\n\n## Next\n\n- On Base the V5 verifier contract is\n  [`0x2D475a53eAA8F9AC78B69bD2429275a622C644f8`](https://basescan.org/address/0x2D475a53eAA8F9AC78B69bD2429275a622C644f8);\n  the proof API page is https://www.taifoon.io/docs/v5-proof-api.\n- The same call as an MCP tool: `taifoon_proof_tx` (`mcp-server`).\n- A transfer whose two legs are both provable: `bridge-with-proof`.\n"}