Introduction to Sploosh

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-ast/src/lib.rs
• crates/sploosh-lexer/src/lib.rs
• crates/sploosh-parser/src/lib.rs

Sploosh is an AI-native programming language designed specifically to enable Large Language Models (LLMs) to generate correct code on the first attempt. It combines Rust-grade memory safety, Elixir-style actor concurrency, and a dual-target compilation strategy that supports both web2 (Native and WASM) and web3 (EVM and Solana SBF) environments. The project follows a spec-first philosophy, where the language definition is the authoritative source of truth, and the compiler is developed to match this specification exactly.

The core thesis of Sploosh is to provide a language with one canonical way to express every operation using a familiar vocabulary drawn from the most-trained tokens in existing languages. This design ensures that LLM completions converge on correct code with minimal context, supported by a prompt-loadable core specification that fits within standard LLM attention windows.

Sources: README.md:3-12, VISION.md:3-10, VISION.md:35-43

Core Design Principles

Sploosh is governed by seven foundational principles that prioritize predictability for both humans and AI agents.

Principle	Description
One way to do everything	Eliminates syntactic synonyms and ambiguity.
Familiar vocabulary	Uses keywords like fn, let, and match from highly-trained languages.
Explicit over implicit	No hidden control flow, operator overloading, or implicit conversions.
Errors are values	Fallible operations return Result<T, E>; no exceptions or panics in safe code.
Structural Concurrency	Uses actor-based isolation and message passing; no shared mutable state.
Dual-target design	Single syntax for native (LLVM), WASM, EVM, and SVM (Solana).
Prompt-loadable spec	Core spec is CI-enforced to stay under 5,600 tokens.

Sources: README.md:46-54, VISION.md:46-56, VISION.md:60-65

System Architecture

The Sploosh compiler bootstrap is implemented in Rust and currently consists of three primary crates that handle the frontend of the language pipeline.

Compiler Pipeline Flow

The following diagram illustrates the flow from source code to the generated Abstract Syntax Tree (AST):

The compiler currently implements a recursive-descent parser targeting the EBNF grammar defined in the specification.
Sources: README.md:63-71, crates/AGENTS.md:12-16, crates/sploosh-parser/src/lib.rs:7-12

Compiler Crates Description

1. sploosh-lexer: A UTF-8 tokenizer that recognizes 45 keywords (36 reserved and 9 contextual) and classifies literals, identifiers, and operators.
2. sploosh-ast: Defines the typed Abstract Syntax Tree nodes, preserving source spans and operator enums.
3. sploosh-parser: A recursive-descent parser that transforms tokens into the AST. It supports items like actor, fn, struct, enum, and onchain mod.

Sources: README.md:63-71, crates/AGENTS.md:12-16, crates/sploosh-ast/src/lib.rs:1-10

Language Features

Concurrency and Actors

Concurrency in Sploosh is achieved through actors, which are isolated units of execution with private state. Communication occurs via message passing using Handle<T>.

Web3 and On-chain Development

Sploosh provides a first-class onchain mod for blockchain development. These modules are subject to strict prohibitions: no floating-point math, no actors, and no host IO (filesystem/network).

• Reentrancy: Guarded by default; developers must explicitly opt-in using @reentrant.
• Storage: Designed to be Solidity-compatible for easy migration of ERC-20 and ERC-721 contracts.
• Payable: Functions must use the @payable attribute to receive native value.

Sources: VISION.md:15-18, VISION.md:79-82, README.md:40-44

Data Handling and Safety

The language enforces safety through a strict type system and structural rules:

• Ownership: Borrow checking and ownership rules (parsed but not yet fully preserved in bootstrap crates).
• Error Handling: Uses the pipe operator |> with error propagation ?.
• Immutability: Shared data must be wrapped in Shared<T> for refcounted immutability.

Sources: VISION.md:89-91, README.md:38-39, crates/sploosh-ast/src/lib.rs:320-330

Project Status and Roadmap

Sploosh is currently in the spec-first pre-1.0 phase. The language definition (v0.5.14-draft) is complete, and the frontend compiler work is active.

Phase	Description	Status
Phase 1	Frontend: Lexer & Parser (§2, §16)	Active
Phase 2	Name Resolution & Modules (§10)	Planned
Phase 3	Type Checking & Inference (§3)	Planned
Phase 6	Code Generation (LLVM/WASM/EVM/SVM)	Planned

Sources: README.md:57-61, README.md:73-83

Conclusion

Sploosh represents a shift toward AI-centric software architecture. By restricting the language to a single, unambiguous way of performing operations and keeping the entire core specification small enough for LLM context windows, it aims to drastically improve the reliability of AI-generated code across native, web, and blockchain platforms.

Sources: VISION.md:3-10, README.md:14-23