Storage Overview

Net Storage is an onchain key-value storage system built on top of the Net Protocol. It provides immutable, versioned storage for any data you want to store permanently on the blockchain.

What is Storage?

Net Storage enables you to store key-value pairs onchain with complete version history. You can continue to create new data for any given key, and all previous versions are automatically preserved. Unlike traditional databases, Storage data is:

• Immutable: Once stored, data cannot be modified
• Versioned: Complete history of all changes preserved
• Transparent: All data is publicly verifiable
• Decentralized: No central servers or databases required
• Permissionless: Anyone can read stored data

Storage Types

Net provides three storage systems for different file sizes:

Regular Storage

Best for: Small data (under 20KB)
How it works: Stores data directly as Net messages using the core Net Protocol

Why it exists: Simple key-value storage with automatic version history. Every update creates a new Net message, preserving complete history without additional complexity.

ChunkedStorage

Best for: Medium files (20KB to 80KB)
How it works:

1. Compresses data with gzip
2. Splits compressed data into 20KB chunks
3. Stores each chunk separately in Storage.sol
4. Maximum 255 chunks
   • Theoretically ChunkedStorage can store much larger files
   • Many RPC providers limit transaction size, resulting in practical limit around 80KB

Note: Gzip compression is performed on the Net website before sending data to the blockchain, not on-chain.

Why it exists: We efficiently use SSTORE2 to store data for relatively low gas costs. Due to limitations with how much data can be stored in a single SSTORE2 call, ChunkedStorage allows storing larger amounts of data in a single transaction by breaking it into multiple SSTORE2 operations.

XML Storage

Best for: Large files (over 80KB)
How it works: Frontend pattern that splits large files into 80KB pieces, stores each piece using ChunkedStorage, and maintains references as XML metadata.

Why it exists: ChunkedStorage has a practical limit of ~80KB. XML Storage breaks this limit by creating a two-level chunking system where each 80KB piece is stored as ChunkedStorage, enabling multi-megabyte files.

Key Features

• Key-Value Storage: Store any data with custom keys
• Version History: Track all changes to stored values
• Batch Operations: Store multiple values efficiently
• Efficient Retrieval: Fast access to stored data
• Onchain Verification: Cryptographically verify all data
• Automatic Compression: Large files compressed with gzip automatically
• Historical Versions: Access any previous version of stored data
• Smart Routing: StorageRouter automatically detects storage type

How Storage Works

Storage is implemented as a smart contract that uses Net Protocol for data storage:

Architecture

User → Storage Contract → Net Protocol → Blockchain

1. User calls Storage contract with key-value data
2. Storage contract formats data as Net message
3. Net Protocol stores message onchain
4. Data is retrievable by anyone with the key

Data Flow

put(key, value) → Net Message → Onchain Storage
get(key) → Query Net → Retrieve Value

Use Cases

Store digital media and content onchain:

• Onchain Websites: HTML, CSS, JavaScript files
• Images: Photos, artwork, graphics
• GIFs: Animated images and memes
• Videos: Short video clips and animations
• Blog Posts: Articles and documentation
• User Profiles: Public profile data
• Documents: Contracts, research data, scripts
• Media Metadata: Information about files

Storage vs Traditional Databases

Traditional Database

• Centralized: Single server controls data
• Mutable: Data can be modified or deleted
• Private: Only authorized users can access
• Fragile: Single point of failure
• Temporary: Data can be lost

Net Storage

• Decentralized: No central control
• Immutable: Data cannot be modified
• User-Associated: Data is tied to the address that stored it
• Public: Anyone can read stored data
• Resilient: Distributed across blockchain
• Permanent: Data stored forever

Benefits of Onchain Storage

For Users

• Ownership: You own your data
• Control: No one can censor or modify your data
• Transparency: All data is publicly verifiable
• Permanence: Data is stored permanently
• Access: Data accessible from anywhere

For Developers

• No Infrastructure Costs: No servers, databases, or hosting fees to pay
• Blockchain-Level Verification: Data integrity guaranteed by blockchain immutability
• Cross-App Data Sharing: User data stored once can be accessed by any app on any chain
• Built-in Version History: Every update creates a permanent historical record
• Multi-Chain Support: Same contract addresses work across all supported chains

Storage Contracts

Net uses multiple contracts for different storage needs:

Core Storage Contract

Purpose: Basic key-value storage with version history
Role: Foundation layer - all storage ultimately goes through this contract
Same address across all chains

ChunkedStorage Contract

Purpose: Handle files larger than gas limits allow
Role: Compression and chunking layer - splits large files then stores chunks in Storage.sol
Same address across all chains

StorageRouter Contract

Purpose: Automatically detect storage type when reading
Role: Convenience layer - tries ChunkedStorage first, falls back to regular Storage
Same address across all chains

ChunkedStorageReader Contract

Purpose: Read ChunkedStorage with historical version support
Role: Historical access layer - ChunkedStorage.sol doesn't have version functions, this adds them
Same address across all chains

Contract Addresses

All contracts deployed at the same address across all supported chains:

Contract	Address
Storage	0x00000000DB40fcB9f4466330982372e27Fd7Bbf5
ChunkedStorage	0x000000A822F09aF21b1951B65223F54ea392E6C6
StorageRouter	0x000000C0bbc2Ca04B85E77D18053e7c38bB97939
ChunkedStorageReader	0x00000005210a7532787419658f6162f771be62f8

Supported Data Types

Any data can be stored, including text, HTML, images, videos, GIFs, and more.