[GH-ISSUE #3732] [Feature] Starknet reverse engineering: Cairo, Sierra/CASM, class hashes, entrypoints and storage graphs #1443

New issue

Open

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

bsakaguchi commented

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

Owner

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

Problem Statement & Context

Starknet is the leading validity rollup (zk-STARK Layer 2) on Ethereum, executing provable smart contracts compiled via the Cairo programming language.

Unlike standard register or stack virtual machines, Starknet smart contracts operate through a unique two-stage intermediate compilation architecture:

Cairo Assembly (CASM): Low-level algebraic assembly executed on the Cairo CPU, operating over field elements in the Stark prime field (P = 2^{251} + 17 \cdot 2^{192} + 1). Instructions manipulate memory cells ([fp + N], [ap + M]) ensuring all operations satisfy polynomial algebraic constraints.
Sierra (Safe Intermediate Execution Representation): An intermediate representation that guarantees every program execution is provable (preventing non-halting loops and out-of-gas reverts from evading proof generation). Sierra code consists of strongly-typed libfunc calls (branch_align, array_new, felt252_add, u256_sub).
Contract Class Artifacts (contract_class.json): Compiled contract artifacts declaring ABI, Sierra program bytecode, entrypoint selectors (External, L1 Handler, Constructor), and Cairo compiler versions.
Class Hash & Identity: Unique Pedersen or Poseidon cryptographic hash over the contract class definition uniquely identifying code on-chain.
Storage Layout & State Mapping: Storage variables addressed via Poseidon hashes of variable names and key mappings.

Reverse engineering a deployed Starknet contract requires decompiling Sierra and CASM bytecode, mapping entrypoints to function selectors, and modeling contract storage layouts.

Proposed Architecture

flowchart TD
    A["Starknet Artifact (contract_class.json / compiled_class.json)"] --> B["Starknet / Cairo Semantic Engine"]
    B --> C["Contract Class Header & ABI Parser"]
    B --> D["Sierra IR Decompiler & Libfunc Slicer"]
    B --> E["CASM CPU Assembly Disassembler"]
    B --> F["Storage Variable & Entrypoint Mapper"]
    
    C --> C1["Compiler Version & Entrypoint Selectors (External, Constructor)"]
    C --> C2["Class Hash Computation (Poseidon Hash Matrix)"]
    
    D --> D1["Sierra Type Registry (felt252, u128, ContractAddress)"]
    D --> D2["Libfunc Invocations & Branch Alignments"]
    D --> D3["Control Flow Graph & High-Level Statement Reconstruction"]
    
    E --> E1["CASM Opcode Decoding (Assertions, Call, Jump, Ret)"]
    E --> E2["Register State ([fp], [ap]) & Prime Field Constants"]
    
    F --> F1["Storage Variable Poseidon Hashes (sn_keccak / poseidon)"]
    F --> F2["L1 <-> L2 Messaging Handlers"]
    
    C & D & E & F --> G["Synthesized Starknet Contract Specification & Decompiled Cairo Source"]

Technical Capabilities & Modules

Starknet Contract Class Deserialization:
- Ingest modern Cairo 1.x / 2.x contract_class.json and compiled CASM classes.
- Parse ABI descriptors: function signatures, event definitions, struct definitions, and custom enum types.
- Verify Starknet class hash calculation (Poseidon hash of contract class components).
Sierra IR Decompilation & Libfunc Analysis:
- Parse Sierra type declarations and libfunc declarations (core::integer, core::array, core::starknet).
- Disassemble Sierra statement lists into basic blocks.
- Reconstruct high-level control flow: match expressions, loops, and conditional branches.
CASM (Cairo Assembly) Disassembly:
- Disassemble raw CASM instructions into mnemonic statements: [ap] = [fp + 1] + [fp + 2], jmp rel X if [fp] != 0, call rel Y.
- Validate prime field arithmetic constants (P = 2^{251} + 17 \cdot 2^{192} + 1).
- Correlate compiled CASM byte offsets with corresponding Sierra statement indices.
Storage Layout & Entrypoint Selector Resolution:
- Map entrypoint selectors (250-bit hashes of function names via sn_keccak) to corresponding Sierra functions.
- Reconstruct storage variable names and calculate their base storage address slots.
L1 ↔ L2 Messaging Handler Reconstruction:
- Map L1 Handler entrypoints (#[l1_handler]) receiving messages from Ethereum Layer 1 contracts.
- Model outgoing send_message_to_l1 call signatures.

Acceptance Criteria

Parsing and structural validation of Cairo contract class artifacts (contract_class.json).
Disassembly and control flow graph generation for Sierra program bytecodes.
Disassembly of CASM algebraic instructions with register offset resolution.
Accurate resolution of entrypoint selectors to public functions.
Reconstruction of contract storage variables and L1 handler entrypoints.

Complements #3621 (Unknown binary file-format inference)
Complements #3716 (Common Bytecode and VM Framework)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3732 [![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 Starknet is the leading validity rollup (zk-STARK Layer 2) on Ethereum, executing provable smart contracts compiled via the Cairo programming language. Unlike standard register or stack virtual machines, Starknet smart contracts operate through a unique two-stage intermediate compilation architecture: 1. **Cairo Assembly (CASM)**: Low-level algebraic assembly executed on the Cairo CPU, operating over field elements in the Stark prime field ($P = 2^{251} + 17 \cdot 2^{192} + 1$). Instructions manipulate memory cells (`[fp + N]`, `[ap + M]`) ensuring all operations satisfy polynomial algebraic constraints. 2. **Sierra (Safe Intermediate Execution Representation)**: An intermediate representation that guarantees every program execution is provable (preventing non-halting loops and out-of-gas reverts from evading proof generation). Sierra code consists of strongly-typed libfunc calls (`branch_align`, `array_new`, `felt252_add`, `u256_sub`). 3. **Contract Class Artifacts (`contract_class.json`)**: Compiled contract artifacts declaring ABI, Sierra program bytecode, entrypoint selectors (External, L1 Handler, Constructor), and Cairo compiler versions. 4. **Class Hash & Identity**: Unique Pedersen or Poseidon cryptographic hash over the contract class definition uniquely identifying code on-chain. 5. **Storage Layout & State Mapping**: Storage variables addressed via Poseidon hashes of variable names and key mappings. Reverse engineering a deployed Starknet contract requires decompiling Sierra and CASM bytecode, mapping entrypoints to function selectors, and modeling contract storage layouts. ### Proposed Architecture ```mermaid flowchart TD A["Starknet Artifact (contract_class.json / compiled_class.json)"] --> B["Starknet / Cairo Semantic Engine"] B --> C["Contract Class Header & ABI Parser"] B --> D["Sierra IR Decompiler & Libfunc Slicer"] B --> E["CASM CPU Assembly Disassembler"] B --> F["Storage Variable & Entrypoint Mapper"] C --> C1["Compiler Version & Entrypoint Selectors (External, Constructor)"] C --> C2["Class Hash Computation (Poseidon Hash Matrix)"] D --> D1["Sierra Type Registry (felt252, u128, ContractAddress)"] D --> D2["Libfunc Invocations & Branch Alignments"] D --> D3["Control Flow Graph & High-Level Statement Reconstruction"] E --> E1["CASM Opcode Decoding (Assertions, Call, Jump, Ret)"] E --> E2["Register State ([fp], [ap]) & Prime Field Constants"] F --> F1["Storage Variable Poseidon Hashes (sn_keccak / poseidon)"] F --> F2["L1 <-> L2 Messaging Handlers"] C & D & E & F --> G["Synthesized Starknet Contract Specification & Decompiled Cairo Source"] ``` ### Technical Capabilities & Modules 1. **Starknet Contract Class Deserialization:** - Ingest modern Cairo 1.x / 2.x `contract_class.json` and compiled CASM classes. - Parse ABI descriptors: function signatures, event definitions, struct definitions, and custom enum types. - Verify Starknet class hash calculation (Poseidon hash of contract class components). 2. **Sierra IR Decompilation & Libfunc Analysis:** - Parse Sierra type declarations and libfunc declarations (`core::integer`, `core::array`, `core::starknet`). - Disassemble Sierra statement lists into basic blocks. - Reconstruct high-level control flow: match expressions, loops, and conditional branches. 3. **CASM (Cairo Assembly) Disassembly:** - Disassemble raw CASM instructions into mnemonic statements: `[ap] = [fp + 1] + [fp + 2]`, `jmp rel X if [fp] != 0`, `call rel Y`. - Validate prime field arithmetic constants ($P = 2^{251} + 17 \cdot 2^{192} + 1$). - Correlate compiled CASM byte offsets with corresponding Sierra statement indices. 4. **Storage Layout & Entrypoint Selector Resolution:** - Map entrypoint selectors (250-bit hashes of function names via `sn_keccak`) to corresponding Sierra functions. - Reconstruct storage variable names and calculate their base storage address slots. 5. **L1 ↔ L2 Messaging Handler Reconstruction:** - Map L1 Handler entrypoints (`#[l1_handler]`) receiving messages from Ethereum Layer 1 contracts. - Model outgoing `send_message_to_l1` call signatures. ### Acceptance Criteria - [ ] Parsing and structural validation of Cairo contract class artifacts (`contract_class.json`). - [ ] Disassembly and control flow graph generation for Sierra program bytecodes. - [ ] Disassembly of CASM algebraic instructions with register offset resolution. - [ ] Accurate resolution of entrypoint selectors to public functions. - [ ] Reconstruction of contract storage variables and L1 handler entrypoints. ### Related Issues & Dependencies - Complements #3621 (Unknown binary file-format inference) - Complements #3716 (Common Bytecode and VM Framework)

bsakaguchi referenced this issue

2026-10-17 21:01:31 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

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

[PR #1443] [MERGED] test(android): retain incomplete cleanup failure reasons #2890

bsakaguchi referenced this issue

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

[PR #1448] [MERGED] test(javascript): reuse comparison node fixtures #2894