Walrus Overview

Source constraint: All information in this skill is sourced from the Walrus documentation and the Walrus whitepaper. When extending this skill, only pull from these sources.

Walrus is a decentralized storage protocol built on the Sui blockchain. It stores arbitrary binary data ("blobs") across a network of independent storage nodes using erasure coding. Sui smart contracts manage blob registration, certification, payments, and metadata.

This skill provides the entry point for understanding Walrus. It covers architecture, core terminology, and how to choose the right tool for your use case. For specific tool usage, load the corresponding skill.

Related skills

Routing guide

Skill Content

What is Walrus?

Walrus is a decentralized blob storage protocol. You upload a file, Walrus encodes it into fragments distributed across independent storage nodes, and the Sui blockchain tracks ownership and availability. The result is storage that survives node failures, has no single point of control, and provides cryptographic proof that data has not been tampered with.

Key properties:

• Public by default. All blobs are readable by anyone with the blob ID. Encrypt before uploading if you need privacy (see walrus-data-security).
• Content-addressed. The same file content always produces the same blob ID.
• Time-limited. Storage lasts a fixed number of epochs (max ~2 years). Blobs must be extended or re-uploaded to persist longer.
• Fault-tolerant. Data remains available even if up to 2/3 of storage nodes fail.

Three-layer architecture

1. Client layer. Your code (CLI, SDK, or HTTP requests) encodes blobs, distributes fragments to storage nodes, and interacts with Sui for registration and certification.
2. Storage node layer. Independent operators run storage nodes that hold erasure-coded fragments ("slivers") of blobs. Each node holds one or more shards. Nodes verify slivers, sign receipts, and participate in epoch transitions. Over 60 operators run nodes on mainnet.
3. Sui blockchain layer. Smart contracts on Sui manage payments (WAL token), storage resource allocation, shard-to-node assignments, blob registration/certification, and metadata. The blockchain is the coordination layer, not the data layer.

How storing works

1. The client encodes the blob using RedStuff erasure coding, producing slivers distributed across all shards (~4.5x storage overhead).
2. The client registers the blob on Sui, paying WAL for storage and SUI for gas.
3. Slivers are sent in parallel to storage nodes. Each node verifies and signs a receipt.
4. Once 2/3 of nodes confirm, signatures are aggregated into an availability certificate submitted to Sui.
5. The Point of Availability (PoA) marks when Walrus guarantees the blob is available for its full storage duration.

How reading works

1. The client requests slivers from storage nodes.
2. Once it collects slivers from more than 1/3 of nodes, it reconstructs the original blob.
3. Alternatively, an aggregator does this on your behalf and serves the blob over HTTP.

Core terminology

Blob ID vs Sui object ID

This is the most common point of confusion for new users:

Decision tree: which tool to use

Walrus vs traditional storage

Walrus is strongest for use cases that need censorship resistance, verifiability, decentralized availability, or programmable access control. It is not a drop-in replacement for all cloud storage — only the object/blob storage part.

Rules

1. All blobs are public. Encrypt before uploading if you need privacy.
2. Storage is time-limited. Plan for renewals. Maximum is 53 epochs (~2 years on mainnet).
3. You need both WAL and SUI. WAL pays for storage, SUI pays for gas.
4. No public mainnet publisher. Use the upload relay, TypeScript SDK, CLI, or run your own publisher.
5. Small blobs are expensive individually. Use quilts for batches of small files.
6. Blob ID is not object ID. Content hash (for reading) vs on-chain object (for management). Do not confuse them.