A Solana transaction is easy to find and hard to read. An explorer gives you a signature, a list of account keys, and instructions whose data is a string of bytes. To know what really happened you have to remember that the first byte of a Token instruction is a tag, that amounts are little-endian integers without decimals, and that an Anchor program hides the instruction name behind an 8-byte discriminator.
tx-explainer does that reading for you. You give it a signature, raw transaction bytes or a saved getTransaction response, and it prints what each instruction did in plain sentences, followed by the fee, the compute units and the balance changes.
It is a read-only decoder: it never signs or sends anything. The README is also clear about its limits: the project is not audited, it is meant for devnet, testnet and localnet first, and the plain-language output is a best effort that does not replace reading the program's code.
What it does
Here is the output for a real devnet transaction that ships as a test fixture:
$ tx-explainer --file test/fixtures/devnet-memo.json
Transaction 5zhK… [legacy]
Status: succeeded
Fee: 0.0000155 SOL (of which priority ≈ 0.0000105 SOL)
Compute units: 26,021 of 70,000 requested
What happened:
1. [Compute Budget] Set compute unit limit to 70,000
2. [Compute Budget] Set priority fee to 150,000 micro-lamports per compute unit
3. [Associated Token Account] Create (if missing) the associated token account Expy…TCA6 for wallet 6a1w…BNqd and mint 4wMp…jY4y, paid by 2VyJ…TeEs (fee payer)
4. [SPL Token] Transfer 1,236.871165 tokens of mint 4wMp…jY4y from 55Xo…AmDQ to Expy…TCA6 (authority 2VyJ…TeEs (fee payer))
5. [Memo] Memo: "helm-payout-v1:…"
Token balance changes:
55Xo…AmDQ (owner 2VyJ…TeEs): -1,236.871165 of mint 4wMp…jY4y
Expy…TCA6 (owner 6a1w…BNqd): +1,236.871165 of mint 4wMp…jY4y
Built-in programs. The decoder knows the programs that appear in almost every transaction:
- System: CreateAccount, Assign, Transfer, CreateAccountWithSeed, the nonce operations, Allocate and TransferWithSeed.
- SPL Token and Token-2022: mint and account initialization, Transfer and TransferChecked, Approve, Revoke, SetAuthority, MintTo, Burn, CloseAccount, Freeze and Thaw, SyncNative and a few more. Token-2022 extension instructions are named by number only.
- Associated Token Account: Create, CreateIdempotent and RecoverNested.
- Compute Budget: SetComputeUnitLimit, SetComputeUnitPrice, RequestHeapFrame and SetLoadedAccountsDataSizeLimit.
- Memo (v1 and v2), shown as UTF-8 text.
Any Anchor program, through its IDL. Pass the program's IDL with --idl (Anchor 0.30+ format) and the tool shows the instruction name, the Borsh-decoded arguments (structs, enums, vec, option, arrays), the account names, and custom error names when the transaction failed.
The RPC metadata. When the input comes from getTransaction, the output also includes the status (with Anchor error names), the fee, an estimate of the priority fee (compute unit limit × compute unit price), the compute units used, the inner instructions (CPIs), SOL balance changes, and token balance changes with the right decimals.
Legacy and v0 messages. Both formats are supported. Address lookup table entries are resolved from meta.loadedAddresses. For raw input, where that metadata does not exist, they are shown as table[index].
Three ways to run it. The same decoder is available as a CLI, as a TypeScript library, and as a small web UI that runs entirely in the browser and calls the selected cluster's public RPC directly. The README links a live demo of that UI at https://abdeldjalilchougui.github.io/tx-explainer/.
How to use it
You need Node.js 20 or later. Clone the repository and build it:
git clone https://github.com/AbdeldjalilChougui/tx-explainer
cd tx-explainer
pnpm install
pnpm build
Then run the CLI from the checkout:
node dist/cli.js <signature> --cluster devnet # fetch via getTransaction
node dist/cli.js <signature> --rpc http://127.0.0.1:8899
node dist/cli.js --raw <base64-or-base58 tx bytes> # offline, no metadata
node dist/cli.js --file saved-getTransaction.json --idl target/idl/my_program.json
node dist/cli.js ... --json # machine-readable
node dist/cli.js serve --port 8787 # web UI on 127.0.0.1
The first two forms fetch the transaction from a cluster or from your local validator. --raw works offline on base64 or base58 bytes. --file reads a saved getTransaction response, which is handy for bug reports and tests. --json gives the same explanation as structured data, so a script can consume it.
As a library, three functions cover the common case:
import { explain, render, fetchTransaction } from "tx-explainer";
const e = explain({ rpc: await fetchTransaction(sig, "https://api.devnet.solana.com") }, { idls: [myIdl] });
console.log(render(e));
fetchTransaction gets the transaction, explain builds the structured explanation, and render turns it into the text you saw above.
How it works inside
The README describes four small modules, and the split is worth knowing if you want to add a decoder:
-
message.tsparses the wire format by hand: compact-u16 lengths, signatures, the message header, account keys, compiled instructions and v0 lookup tables. It then derives the signer and writable flags of each key from the header. -
programs.tshas one small decoder per built-in program. Each one reads the instruction tag (au32for System, au8for Token) and its fields with a little-endianReader. -
anchor.tsmatches the first 8 bytes of the instruction data against each IDL instruction'sdiscriminator, then Borsh-decodes the arguments from the IDL type tree. -
explain.tscombines all of this with the RPC metadata: token balances give the mint and the decimals, inner instructions give the CPIs, and pre and post balances give the deltas.
Things to know
- Not audited, and best effort. The sentences are an aid for reading a transaction. They do not replace reading the program's code, and you should not make a decision about real funds from them alone.
- Token-2022 extensions are shown by number only. Transfer fees, confidential transfers and the other extension instructions are not decoded into sentences.
- Some programs are only named. Stake, Vote, Address Lookup Table and loader instructions are recognized but not decoded.
-
The priority fee is an estimate. It is computed as
ceil(limit × price / 1e6). When the transaction sets no limit, the tool assumes the default of 200k compute units per instruction. -
Raw input has no metadata. With
--rawthere is no status, no fee, no balance changes and no inner instructions, because those come from the RPC, not from the transaction bytes. -
What was tested.
pnpm testuses only fixtures committed intest/fixtures/. Four are synthetic transactions built by a script with@solana/web3.jsfrom fixed public keys. They are left unsigned, so no keypair is ever created, and they carry hand-written metadata: a SOL transfer with memo and compute budget, an ATA creation with TransferChecked and CPIs, a v0 lookup-table Token-2022 mint, and a failed Anchor call. The fifth is one real devnet transaction, captured once over a read-only RPC.
Why I built it
The raw view of a transaction answers "which bytes were sent", while the question people ask is "what happened". Getting from one to the other means decoding instruction tags, scaling token amounts by the mint's decimals, matching Anchor discriminators against an IDL, and reading inner instructions and balance deltas from the metadata. Each step is simple, but doing all of them by hand for every transaction is slow, and it is easy to misread an amount.
I wanted one tool that does these steps the same way every time, works on a local validator as well as devnet, runs offline on raw bytes, and can be used from a terminal, from code, or from a browser tab. Parsing the wire format by hand, instead of hiding it behind a large dependency, also keeps the decoder small enough to read and extend.
Get the code
The source, the fixtures, the tests and the web UI are on GitHub: https://github.com/AbdeldjalilChougui/tx-explainer. It is MIT licensed. Issues and pull requests are welcome, especially decoders for programs that are only named today.
Originally published at abdeldjalilchougui.biz.
Top comments (0)