Dual-Target Compilation Engine

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• VISION.md
• AGENTS.md
• crates/AGENTS.md
• crates/sploosh-parser/src/lib.rs
• crates/sploosh-lexer/src/lib.rs

The Sploosh Dual-Target Compilation Engine is a core architectural component designed to compile a single source code tree into four distinct execution environments: native (LLVM), WASM, EVM bytecode, and Solana SBF. This engine enforces target-specific restrictions at compile time, allowing developers to write high-level code with Rust-grade safety and Elixir-style concurrency that can run on both traditional "web2" infrastructure and decentralized "web3" blockchains.

Sources: VISION.md:5-7, README.md:120-120, README.md:144-144

Architecture and Compilation Flow

The compilation process is structured into phases that map directly to the language specification. The engine operates as a pipeline, transforming raw source text into target-specific bytecode through a series of intermediate representations and validation stages.

Frontend Pipeline

The frontend consists of the lexer and parser, which together transform Sploosh source (.sp files) into a typed Abstract Syntax Tree (AST).

1. Lexical Analysis (sploosh-lexer): Tokenizes source text into §2 and §16.1 compliant tokens, handling 45 keywords and complex numeric literals.
2. Syntactic Analysis (sploosh-parser): Uses a recursive-descent parser to generate a typed AST from the token stream. It enforces block-head restrictions and modifier placements (e.g., rejecting pub on onchain items).

Sources: README.md:154-160, crates/AGENTS.md:20-25, crates/sploosh-parser/src/lib.rs:88-100

The diagram shows the progression from source code through the shared frontend to the differentiated target backends. Sources: README.md:162-171, VISION.md:100-104

Target Backends and Prohibitions

The engine distinguishes between standard execution and on-chain execution via the onchain mod construct. While the syntax remains unified, the compiler rejects non-deterministic or host-restricted operations when the target is a blockchain environment.

Web2 vs. Web3 Capabilities

Feature	Native/WASM (Web2)	EVM/SVM (Web3)
Float Math	Supported	Prohibited
File/Net/IO	Supported	Prohibited
Actors/Mailboxes	Supported	Prohibited
Storage Layout	Native Memory	Solidity-Compatible
Reentrancy	Actor Isolation	Guarded by Default

Sources: VISION.md:110-117, VISION.md:129-130, README.md:144-144

Target Enforcement Logic

The compiler utilizes attributes and specific item types to trigger target-specific validation logic. For example, functions marked with @payable are only valid in on-chain contexts, while onchain mod blocks are subject to strict deterministic checks.

This diagram illustrates how the validator branches logic based on the module type. Sources: VISION.md:58-62, crates/sploosh-parser/src/lib.rs:142-154

Implementation Status (Bootstrap Phase)

The engine is currently in the bootstrap phase (Milestone 1), focusing on the frontend infrastructure.

Parser Capabilities for Dual Targets

The current parser implementation already handles constructs required for dual-target compilation, even though backends are pending.

• onchain mod parsing: Recognizes and enters on-chain modules, though storage blocks are currently consumed and discarded.
• extern blocks: Supports extern onchain mod and extern "C" for cross-environment calls.
• Attribute preservation: Captures @payable, @reentrant, and @mailbox attributes on the AST for downstream consumption.
• Modifier Enforcement: Rejects pub on onchain items as per the grammar specification (§16).

Sources: crates/AGENTS.md:28-36, crates/sploosh-parser/src/lib.rs:92-132

Code Snippet: On-Chain Module Parsing

// crates/sploosh-parser/src/lib.rs:356-378
fn onchain_item(&mut self) -> Option<ItemKind> {
    self.expect_keyword(Keyword::Onchain)?;
    if self.eat_keyword(Keyword::Mod).is_some() {
        let name = self.ident()?;
        self.expect(TokenKind::LBrace)?;
        let mut items = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.eof() {
            self.skip_doc_comments();
            if self.eat_ident_text("storage").is_some() {
                self.skip_balanced(TokenKind::LBrace, TokenKind::RBrace);
                continue; // Storage layout is recognized but not yet stored
            }
            if let Some(item) = self.item() {
                items.push(item);
            } else {
                self.recover_item();
            }
        }
        self.expect(TokenKind::RBrace)?;
        Some(ItemKind::OnchainModule(OnchainModule { name, items }))
    } else {
        self.error_here("expected `mod` or `enum` after `onchain` ");
        None
    }
}

Sources: crates/sploosh-parser/src/lib.rs:356-378

Conclusion

The Dual-Target Compilation Engine serves as the bridge between traditional software development and blockchain protocol authorship. By enforcing a single-syntax approach with target-specific compile-time restrictions, it enables the creation of high-safety applications that can span across native, WASM, EVM, and SVM environments without requiring developers to master multiple languages or manually implement reentrancy guards and ABI scaffolding.

Sources: VISION.md:12-25, README.md:113-116