[GH-ISSUE #3747] [Feature] Solana transaction reverse engineering: instructions, CPIs, account roles, logs and state-change graphs #1454

New issue

Open

opened 2026-10-16 21:05:35 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:35 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3747

Problem Statement & Context

Solana executes smart contracts through high-performance SeaLevel runtime running Solana Bytecode Format (sBPF). While REA issue #2003 addresses static disassembly of standalone sBPF binaries and Anchor IDL introspection, analyzing a recorded Solana transaction on-chain requires a distinct runtime reverse engineering approach:

Transaction Wire Format: Signatures array, message header (num_required_signatures, num_readonly_signed_accounts, num_readonly_unsigned_accounts), account keys array, recent blockhash, instructions array, and Address Lookup Tables (ALT / v0 transactions).
Instruction & Inner Instruction (CPI) Hierarchy: Top-level instructions invoking programs, which in turn spawn nested Cross-Program Invocations (CPI) recorded as inner instructions in execution metadata.
Account Metas & Roles: Explicit account declarations (Signer, Writable, Read-Only, Program ID) determining parallel execution scheduling.
Program Log Traces: Execution logs emitting Program <id> invoke [depth], Program log: ..., Program data: ..., and Program <id> success/failed.
Pre/Post State Balances & Token Balances: Pre-execution vs post-execution SOL balances and SPL Token account balances (preTokenBalances, postTokenBalances) used to reconstruct asset transfers.

REA needs a Solana transaction semantic engine capable of ingesting raw transaction wire formats or JSON-RPC trace responses, resolving Address Lookup Tables, untangling nested CPI call trees, and reconstructing the asset flow and state mutation graph.

Proposed Architecture

flowchart TD
    A["Solana Transaction (Wire Base64 / RPC JSON Transaction Response)"] --> B["Solana Transaction Semantic Engine"]
    B --> C["Wire Format & Address Lookup Table Resolver"]
    B --> D["Instruction & CPI Call Tree Reconstructor"]
    B --> E["Program Log & Event Deserializer"]
    B --> F["Account Balance & Asset Flow Analyzer"]
    
    C --> C1["Message Header & Account Keys Parsing"]
    C --> C2["v0 Address Lookup Table (ALT) Index Expansion"]
    
    D --> D1["Top-Level Instructions (Program ID, Accounts, Data)"]
    D --> D2["Inner Instructions (CPI Invocation Depth 1..N)"]
    
    E --> E1["Program Invoke / Success / Revert Log Parsing"]
    E --> E2["Anchor Event Log Decoding (Base64 Discriminators)"]
    
    F --> F1["SOL Pre/Post Balance Diffs"]
    F --> F2["SPL Token Pre/Post Balance Diffs (Mint, Owner, Amount)"]
    
    C & D & E & F --> G["Synthesized Solana Transaction Execution Tree & Asset Flow Graph"]

Technical Capabilities & Modules

Transaction Wire Format Deserialization:
- Parse compact-u16 encoded signatures array and transaction message.
- Support both Legacy and Versioned (v0) transaction formats.
- Resolve Address Lookup Table (ALT) indices (loadedAddresses.writable, loadedAddresses.readonly) to reconstitute the complete runtime account address array.
Hierarchical Instruction & CPI Reconstruction:
- Map instruction accounts from local index arrays to resolved public keys.
- Reconstruct the nested execution call tree by correlating top-level instructions with meta.innerInstructions (tracking invocation depth).
- Identify well-known programs: System Program, Token Program, Associated Token Account Program, Compute Budget Program, BPF Loader.
Instruction Data & Discriminator Decoding:
- Ingest Anchor IDLs or known program schemas (#2003) to decode 8-byte instruction discriminators (e.g. sha256("global:instruction_name")[..8]).
- Decode instruction parameters (amounts, public keys, options).
Program Log Stream Slicing:
- Parse execution log messages to track stack frames:
  - Program <pubkey> invoke [depth] -> Push call frame.
  - Program <pubkey> success -> Pop call frame.
  - Program <pubkey> failed: <error> -> Flag failure site.
- Decode Anchor base64 event logs (Program data: <base64>).
Asset Flow & Balance Diff Reconstruction:
- Calculate exact net SOL balance changes across all involved accounts.
- Parse preTokenBalances and postTokenBalances to model SPL token transfers, mints, and burns.
- Generate an asset flow diagram showing token movements between sender, recipient, and pool accounts.

Acceptance Criteria

Automated decoding of raw Solana transactions (Legacy and v0) from base64 wire bytes.
Resolution of Address Lookup Table (ALT) account keys.
Reconstruction of nested Cross-Program Invocation (CPI) call trees.
Decoding of instruction data for standard programs (Token, System, ComputeBudget) and Anchor-based programs.
Generation of an interactive execution trace and token flow diagram.

Complements #2003 (Solana sBPF/Anchor reverse engineering)
Complements #3621 (Unknown binary file-format inference)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3747 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Blockchain RE](https://img.shields.io/badge/domain-blockchain_RE-orange.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context Solana executes smart contracts through high-performance SeaLevel runtime running Solana Bytecode Format (sBPF). While REA issue #2003 addresses static disassembly of standalone sBPF binaries and Anchor IDL introspection, analyzing a recorded Solana transaction on-chain requires a distinct runtime reverse engineering approach: 1. **Transaction Wire Format**: Signatures array, message header (num_required_signatures, num_readonly_signed_accounts, num_readonly_unsigned_accounts), account keys array, recent blockhash, instructions array, and Address Lookup Tables (ALT / v0 transactions). 2. **Instruction & Inner Instruction (CPI) Hierarchy**: Top-level instructions invoking programs, which in turn spawn nested Cross-Program Invocations (CPI) recorded as inner instructions in execution metadata. 3. **Account Metas & Roles**: Explicit account declarations (Signer, Writable, Read-Only, Program ID) determining parallel execution scheduling. 4. **Program Log Traces**: Execution logs emitting `Program <id> invoke [depth]`, `Program log: ...`, `Program data: ...`, and `Program <id> success/failed`. 5. **Pre/Post State Balances & Token Balances**: Pre-execution vs post-execution SOL balances and SPL Token account balances (`preTokenBalances`, `postTokenBalances`) used to reconstruct asset transfers. REA needs a Solana transaction semantic engine capable of ingesting raw transaction wire formats or JSON-RPC trace responses, resolving Address Lookup Tables, untangling nested CPI call trees, and reconstructing the asset flow and state mutation graph. ### Proposed Architecture ```mermaid flowchart TD A["Solana Transaction (Wire Base64 / RPC JSON Transaction Response)"] --> B["Solana Transaction Semantic Engine"] B --> C["Wire Format & Address Lookup Table Resolver"] B --> D["Instruction & CPI Call Tree Reconstructor"] B --> E["Program Log & Event Deserializer"] B --> F["Account Balance & Asset Flow Analyzer"] C --> C1["Message Header & Account Keys Parsing"] C --> C2["v0 Address Lookup Table (ALT) Index Expansion"] D --> D1["Top-Level Instructions (Program ID, Accounts, Data)"] D --> D2["Inner Instructions (CPI Invocation Depth 1..N)"] E --> E1["Program Invoke / Success / Revert Log Parsing"] E --> E2["Anchor Event Log Decoding (Base64 Discriminators)"] F --> F1["SOL Pre/Post Balance Diffs"] F --> F2["SPL Token Pre/Post Balance Diffs (Mint, Owner, Amount)"] C & D & E & F --> G["Synthesized Solana Transaction Execution Tree & Asset Flow Graph"] ``` ### Technical Capabilities & Modules 1. **Transaction Wire Format Deserialization:** - Parse compact-u16 encoded signatures array and transaction message. - Support both Legacy and Versioned (v0) transaction formats. - Resolve Address Lookup Table (ALT) indices (`loadedAddresses.writable`, `loadedAddresses.readonly`) to reconstitute the complete runtime account address array. 2. **Hierarchical Instruction & CPI Reconstruction:** - Map instruction accounts from local index arrays to resolved public keys. - Reconstruct the nested execution call tree by correlating top-level instructions with `meta.innerInstructions` (tracking invocation depth). - Identify well-known programs: System Program, Token Program, Associated Token Account Program, Compute Budget Program, BPF Loader. 3. **Instruction Data & Discriminator Decoding:** - Ingest Anchor IDLs or known program schemas (#2003) to decode 8-byte instruction discriminators (e.g. `sha256("global:instruction_name")[..8]`). - Decode instruction parameters (amounts, public keys, options). 4. **Program Log Stream Slicing:** - Parse execution log messages to track stack frames: - `Program <pubkey> invoke [depth]` -> Push call frame. - `Program <pubkey> success` -> Pop call frame. - `Program <pubkey> failed: <error>` -> Flag failure site. - Decode Anchor base64 event logs (`Program data: <base64>`). 5. **Asset Flow & Balance Diff Reconstruction:** - Calculate exact net SOL balance changes across all involved accounts. - Parse `preTokenBalances` and `postTokenBalances` to model SPL token transfers, mints, and burns. - Generate an asset flow diagram showing token movements between sender, recipient, and pool accounts. ### Acceptance Criteria - [ ] Automated decoding of raw Solana transactions (Legacy and v0) from base64 wire bytes. - [ ] Resolution of Address Lookup Table (ALT) account keys. - [ ] Reconstruction of nested Cross-Program Invocation (CPI) call trees. - [ ] Decoding of instruction data for standard programs (Token, System, ComputeBudget) and Anchor-based programs. - [ ] Generation of an interactive execution trace and token flow diagram. ### Related Issues & Dependencies - Complements #2003 (Solana sBPF/Anchor reverse engineering) - Complements #3621 (Unknown binary file-format inference)

bsakaguchi referenced this issue

2026-10-17 21:11:36 +00:00

[PR #1461] [MERGED] fix(mcp): validate doctor probe against its discovered output contract #2902

bsakaguchi referenced this issue

2026-10-31 00:44:46 +00:00

[GH-ISSUE #6452] [Bug] mcp doctor checks the wrong server when output flags precede doctor #3866