Storage Layout & Solidity Compatibility

Relevant source files

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

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

Sploosh is designed as an AI-native language that provides a dual-target compilation strategy for both web2 and web3 environments. A core pillar of its web3 integration is the ability to maintain compatibility with Solidity's storage layout. This allows developers to port existing Ethereum-based protocols, such as ERC-20 and ERC-721 contracts, to Sploosh without altering their underlying data structures or state locations on-chain.

Sources: VISION.md:7-13, README.md:103-107, SECURITY.md:83-85

The On-chain Module Model

The primary vehicle for Solidity-compatible code in Sploosh is the onchain mod. This specialized module type is strictly governed by the compiler to ensure it only contains deterministic operations suitable for blockchain execution environments like the EVM.

Storage Blocks

Within an onchain mod, state is declared inside a dedicated storage block. The parser is designed to identify these blocks, which contain the persistent state variables of the contract. Although the current bootstrap compiler (v0.1.0) identifies and consumes these blocks for validation, they represent the foundational data model for Solidity-compatible storage.

Sources: crates/sploosh-parser/src/lib.rs:364-370, README.md:52-57, VISION.md:71-72

Mapping and Address Types

To achieve parity with Solidity, Sploosh implements specific types like Address and Map<K, V>. These types map directly to their Ethereum counterparts (address and mapping), ensuring that the resulting bytecode interacts with the state tree in a manner identical to Solidity.

Sources: README.md:54-55, crates/sploosh-parser/src/lib.rs:1133-1135

Architectural Relationship

The following diagram illustrates how onchain mod structures relate to the storage layout and external contract calls.

Key Features for Solidity Authors

Sploosh provides several mechanisms to ease the transition for Solidity developers while improving safety and ergonomics.

Feature	Sploosh Implementation	Solidity Equivalent
Storage Definition	storage { ... } block	Top-level state variables
Address Type	Address	address
Large Integers	u256	uint256
Key-Value Store	Map<Address, u256>	mapping(address => uint256)
Cross-Contract Call	chain::call	address.call() / Interface calls
Event Emission	emit EventName { ... }	emit EventName(...)
Caller Context	ctx::caller()	msg.sender

Sources: README.md:52-69, VISION.md:80-82, crates/sploosh-parser/src/lib.rs:1133-1135

Safety and Reentrancy

A significant departure from Solidity's default behavior is Sploosh's approach to reentrancy. While maintaining storage compatibility, Sploosh enhances security by making all public on-chain functions non-reentrant by default.

Reentrancy Guard Implementation

• Default State: A per-contract boolean flag is set on entry to any pub on-chain function.
• Opt-out Mechanism: Developers must explicitly use the @reentrant attribute to allow a function to be called recursively.
• Payable Functions: Functions capable of receiving native value must be marked with @payable.

Sources: VISION.md:83-86, SECURITY.md:83-85

Syntax and Attributes

The parser supports attributes that govern on-chain behavior. These attributes are preserved in the AST (Abstract Syntax Tree) to be used by later stages of the compiler for generating the appropriate protection logic.

onchain mod token {
    storage {
        balances: Map<Address, u256>,
    }

    @payable
    pub fn deposit() -> Result<(), Error> {
        // Automatically protected against reentrancy
        Ok(())
    }

    @reentrant
    pub fn legacy_callback() {
        // Explicitly opted out of protection
    }
}

Sources: README.md:52-69, crates/sploosh-parser/src/lib.rs:125-145, VISION.md:83-86

On-chain Prohibitions

To maintain compatibility and determinism, the Sploosh compiler enforces strict prohibitions within onchain mod contexts. The parser and semantic analyzer reject the following:

• Floating Point Math: Methods involving f32 or f64 are prohibited to prevent non-determinism across nodes.
• Actor Concurrency: The Actor model (private state/mailboxes) is replaced by the global state model of the blockchain.
• Host IO: No filesystem (fs), networking (net), or environment (env) access is permitted.

Sources: VISION.md:71-73, AGENTS.md:143-144, crates/AGENTS.md:38-40

Conclusion

The storage layout in Sploosh is designed to be a direct mirror of Solidity's storage slots, facilitating seamless migration of web3 protocols. By combining this compatibility with Rust-grade safety features—such as mandatory reentrancy guards and the elimination of non-deterministic operations—Sploosh provides a safer yet familiar environment for smart contract development.

Sources: VISION.md:118-121, README.md:103-107