# flamingoponderado/stateless-pancaketh architecture

> Architecture diagram of the GitHub repository flamingoponderado/stateless-pancaketh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flamingoponderado/stateless-pancaketh
- Repository: https://github.com/flamingoponderado/stateless-pancaketh

## Overview

stateless-pancaketh is experimental research software implementing an Ethereum stateless guest in Pancake. Its main workflow takes framed execution inputs, runs the guest’s stateless EVM logic, and produces output for Spike or ZisK; EEST tooling runs fixtures against the compiled guest to assess conformance. The tree also exposes transaction, state, trie, and precompile domains, plus cryptographic acceleration. Those source-level stages are represented by their named modules, but their internal call relationships were not sampled, so the graph avoids asserting them. README-documented runtime links are shown explicitly.

Main entry points: [`guest/src/main.pnk`](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/main.pnk) (Guest entry), [`tools/eest-run.py`](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/eest-run.py) (EEST runner), [`tools/compare-clients.py`](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/compare-clients.py) (Client comparison), [`tools/spike/spike_run.cc`](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/spike/spike_run.cc) (Spike runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guest["Stateless guest"]
  node_entry["Guest entry<br/>[main.pnk]"]
  node_elf["Compiled guest ELF"]
end

subgraph group_execution["Execution domains"]
  node_evm["EVM execution<br/>[evm.pnk]"]
  node_transactions["Transactions<br/>[tx.pnk]"]
  node_blocks["Block context<br/>[block.pnk]"]
  node_state["State access<br/>[state.pnk]"]
  node_mpt["Merkle Patricia trie<br/>[mpt.pnk]"]
end

subgraph group_crypto["Cryptography"]
  node_precompiles["Precompiles<br/>[precompiles.pnk]"]
  node_bls["BLS precompiles"]
  node_bn254["BN254 precompiles"]
  node_kzg["KZG precompile"]
  node_p256["P-256 precompile"]
  node_crypto_libs["Crypto libraries"]
end

subgraph group_runtime["Runtime and evaluation"]
  node_spike["Spike runner<br/>[spike_run.cc]"]
  node_zisk["ZisK emulator"]
  node_eest["EEST runner<br/>[eest-run.py]"]
  node_compare["Client comparison<br/>[compare-clients.py]"]
  node_accel["Crypto CSR acceleration<br/>[zisk_accel.cc]"]
end

node_user(("Input provider"))
node_fixtures["EEST fixtures"]

node_user -->|"supplies input"| node_entry
node_entry -->|"compiled as"| node_elf
node_elf -->|"runs under"| node_spike
node_elf -->|"runs under"| node_zisk
node_fixtures -->|"provides cases"| node_eest
node_eest -->|"runs guest"| node_elf
node_compare -->|"measures costs"| node_zisk

click node_entry "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/main.pnk"
click node_evm "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/evm.pnk"
click node_transactions "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/tx.pnk"
click node_blocks "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/block.pnk"
click node_state "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/state.pnk"
click node_mpt "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/mpt.pnk"
click node_precompiles "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles.pnk"
click node_bls "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_bls.pnk"
click node_bn254 "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_bn254.pnk"
click node_kzg "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_kzg.pnk"
click node_p256 "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_p256.pnk"
click node_crypto_libs "https://github.com/flamingoponderado/stateless-pancaketh/tree/main/guest/src/lib"
click node_spike "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/spike/spike_run.cc"
click node_eest "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/eest-run.py"
click node_compare "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/compare-clients.py"
click node_accel "https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/spike/zisk_accel.cc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_elf toneBlue
class node_evm,node_transactions,node_blocks,node_state,node_mpt toneAmber
class node_precompiles,node_bls,node_bn254,node_kzg,node_p256,node_crypto_libs toneMint
class node_spike,node_zisk,node_eest,node_compare,node_accel toneRose
class node_user,node_fixtures toneIndigo
```

## Components

### Stateless guest

- [Guest entry](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/main.pnk): `guest/src/main.pnk`
- **Compiled guest ELF**

### Execution domains

- [EVM execution](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/evm.pnk): `guest/src/evm.pnk`
- [Transactions](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/tx.pnk): `guest/src/tx.pnk`
- [Block context](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/block.pnk): `guest/src/block.pnk`
- [State access](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/state.pnk): `guest/src/state.pnk`
- [Merkle Patricia trie](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/mpt.pnk): `guest/src/mpt.pnk`

### Cryptography

- [Precompiles](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles.pnk): `guest/src/precompiles.pnk`
- [BLS precompiles](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_bls.pnk): `guest/src/precompiles_bls.pnk`
- [BN254 precompiles](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_bn254.pnk): `guest/src/precompiles_bn254.pnk`
- [KZG precompile](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_kzg.pnk): `guest/src/precompiles_kzg.pnk`
- [P-256 precompile](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/guest/src/precompiles_p256.pnk): `guest/src/precompiles_p256.pnk`
- [Crypto libraries](https://github.com/flamingoponderado/stateless-pancaketh/tree/main/guest/src/lib): `guest/src/lib`

### Runtime and evaluation

- [Spike runner](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/spike/spike_run.cc): `tools/spike/spike_run.cc`
- **ZisK emulator**
- [EEST runner](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/eest-run.py): `tools/eest-run.py`
- [Client comparison](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/compare-clients.py): `tools/compare-clients.py`
- [Crypto CSR acceleration](https://github.com/flamingoponderado/stateless-pancaketh/blob/main/tools/spike/zisk_accel.cc): `tools/spike/zisk_accel.cc`

### Other components

- **Input provider**
- **EEST fixtures**

## Connections

- Input provider → Guest entry: supplies input (evidence: `README.md`)
- Guest entry → Compiled guest ELF: compiled as (evidence: `README.md`)
- Compiled guest ELF → Spike runner: runs under (evidence: `README.md`)
- Compiled guest ELF → ZisK emulator: runs under (evidence: `README.md`)
- EEST fixtures → EEST runner: provides cases (evidence: `README.md`)
- EEST runner → Compiled guest ELF: runs guest (evidence: `README.md`)
- Client comparison → ZisK emulator: measures costs (evidence: `tools/compare-clients.py`)
