Architecture Overview

Dolphin enables Python-to-Solana development through a sophisticated compilation pipeline that transforms Python code into native Solana programs. This page explains how Dolphin works under the hood.

Key Concepts

Dolphin's architecture is built around three main principles:

1. Python Frontend: Provide a clean, Pythonic interface for defining Solana programs

2. IR-Based Transformation: Use an Intermediate Representation (IR) as a bridge between languages

3. Native Compilation: Generate standard Solana BPF bytecode for optimal performance

High-Level Overview

sequenceDiagram
    participant Dev as Developer
    participant Py as Python Frontend
    participant IR as Intermediate Representation
    participant Rust as Rust Backend
    participant BPF as Solana BPF
    
    Dev->>Py: Writes Python code
    Py->>IR: Parse to IR
    IR->>Rust: Generate Rust code
    Rust->>BPF: Compile to BPF
    BPF-->>Dev: Deployable program

Components

Component	Language	Purpose	Key Files
Parser & IR Gen	Python	Convert Python to IR	parser.py, ir_gen.py
IR Definitions	Both	Cross-language data contract	ir.py (Py), ir.rs (Rust)
Code Generator	Rust	Convert IR to Solana code	codegen.rs
Compiler Driver	Rust	Build pipeline management	mod.rs, generator/

How It Works

1. Python Parsing: The Python parser reads your code and identifies Dolphin-specific decorators, types, and structures

2. IR Generation: Your program is converted into a language-agnostic intermediate representation (IR)

3. Rust Generation: The IR is transformed into Solana-compatible Rust code

4. BPF Compilation: Standard Solana tooling compiles the Rust code to BPF bytecode

Common Misconceptions

❌ "PyO3 is used to run Python on Solana" ✅ Reality: PyO3 is only used during development time to share IR definitions between the Python-based frontend and Rust-based compiler

❌ "Python code is directly executed on-chain" ✅ Reality: Python is compiled to standard Solana programs through multiple transformation stages

For a deeper dive into specific components, continue to Compilation Pipeline and Key Components.