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
| Topic | Skill | Load when |
|---|---|---|
| CLI | walrus-cli |
Using the walrus binary |
| HTTP API | walrus-http-api |
Storing/reading via REST |
| TypeScript SDK | walrus-ts-sdk |
Programmatic access from TypeScript |
| Move integration | walrus-move-integration |
Wrapping blobs in Move contracts |
| Storage costs | walrus-storage-costs |
Pricing, estimation, cost optimization |
| Blob lifecycle | walrus-blob-lifecycle |
Extending, deleting, sharing blobs |
| Sites | walrus-sites |
Deploying static websites |
| Quilts | walrus-quilts |
Batching many small blobs |
| Confidentiality | walrus-data-security |
Encrypting before storing; Walrus guarantees availability and integrity, not confidentiality |
| Troubleshooting | walrus-troubleshooting |
Common errors and fixes |
Routing guide
| Task | Load |
|---|---|
| "What is Walrus?" / "How does it work?" | Skill Content below |
| "Which tool should I use?" | Decision tree below |
| "What is a blob / blob ID / object ID?" | Terminology below |
| Store a file | walrus-cli or walrus-http-api or walrus-ts-sdk |
| Estimate costs | walrus-storage-costs |
| Deploy a website | walrus-sites |
| Encrypt data | walrus-data-security |
| Fix an error | walrus-troubleshooting |
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
-
Client layer. Your code (CLI, SDK, or HTTP requests) encodes blobs, distributes fragments to storage nodes, and interacts with Sui for registration and certification.
-
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.
-
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
- The client encodes the blob using RedStuff erasure coding, producing slivers distributed across all shards (~4.5x storage overhead).
- The client registers the blob on Sui, paying WAL for storage and SUI for gas.
- Slivers are sent in parallel to storage nodes. Each node verifies and signs a receipt.
- Once 2/3 of nodes confirm, signatures are aggregated into an availability certificate submitted to Sui.
- The Point of Availability (PoA) marks when Walrus guarantees the blob is available for its full storage duration.
How reading works
- The client requests slivers from storage nodes.
- Once it collects slivers from more than 1/3 of nodes, it reconstructs the original blob.
- Alternatively, an aggregator does this on your behalf and serves the blob over HTTP.
Core terminology
| Term | Definition |
|---|---|
| Blob | Any binary data stored on Walrus (file, image, JSON, video, etc.). Max ~13.6 GiB. |
| Blob ID | URL-safe base64 string identifying blob content. Content-addressed: same content = same ID. Used for reading. |
| Sui object ID | 0x... hex string identifying the on-chain Blob Sui object. Different for each upload, even with same content. Used for lifecycle ops (extend, delete, share). |
| Epoch | A time period. 14 days on mainnet. Storage duration is measured in epochs. |
| Sliver | A fragment of an erasure-coded blob, stored on a single shard. |
| Shard | A partition of the storage space, assigned to a storage node for each epoch. |
| Publisher | An HTTP service that accepts blob data (PUT) and handles encoding, distribution, and on-chain registration with its own funded wallet. Walrus runs no public unauthenticated publisher on Mainnet and has no plans to; run your own behind authentication. Public Testnet publishers exist. |
| Aggregator | An HTTP service that reads blobs (GET) by fetching slivers from storage nodes. Many public aggregators exist on both networks, free to use. |
| Upload relay | A third-party service that handles encoding and sliver distribution on behalf of bandwidth-limited clients (for example, browsers). May charge a tip. |
| WAL | The Walrus token, used to pay for storage. |
| SUI | The Sui token, used to pay for on-chain gas fees. |
| Point of Availability (PoA) | The moment an availability certificate is posted on-chain, after which Walrus guarantees the blob is available. |
| Deletable blob | A blob whose owner can remove before expiry (default). |
| Permanent blob | A blob that cannot be deleted before expiry, even by the uploader. |
| Quilt | A single storage unit containing multiple blobs, reducing per-blob overhead. |
| Shared blob | A Blob wrapped in a Sui shared object so anyone can fund and extend it. The Walrus contract provides SharedBlob as a reference implementation; developers can also create custom shared wrappers. |
| Storage pool | A preview feature: one pre-paid storage reservation that many blobs share, so each store pays only the write fee and all blobs in the pool expire together. Rust SDK and Move only; not in the CLI, HTTP APIs, or TypeScript SDK yet. |
Blob ID vs Sui object ID
This is the most common point of confusion for new users:
| Blob ID | Sui Object ID | |
|---|---|---|
| Format | URL-safe base64 (for example, M4hsZGQ1oCk...) |
Hex with 0x prefix (for example, 0xe91eee8c...) |
| Derived from | Blob content (content-addressed) | Sui transaction (unique per upload) |
| Same content uploaded twice? | Same blob ID | Different object IDs |
| Used for | Reading blob content | Lifecycle operations (extend, delete, share, burn) |
| Where you get it | Store response (blobId field) |
Store response (blobObject.id field) |
Decision tree: which tool to use
| You want to... | Use | Skill |
|---|---|---|
| Upload a file from the terminal | walrus store CLI |
walrus-cli |
| Script uploads in a CI/CD pipeline | walrus json CLI (JSON mode) |
walrus-cli |
| Store/read from any language over HTTP | Publisher/aggregator REST API | walrus-http-api |
| Build a TypeScript/JavaScript app | @mysten/walrus SDK |
walrus-ts-sdk |
| Upload from a browser | TypeScript SDK + upload relay | walrus-ts-sdk |
| Reference blobs in a Move contract | Walrus Move dependency | walrus-move-integration |
| Deploy a static website | site-builder CLI |
walrus-sites |
| Store many small files cheaply | Quilts (CLI or HTTP) | walrus-quilts |
| Store sensitive/private data | Encrypt on the client (for example with Seal), then store | walrus-data-security |
| Let users upload without holding SUI or WAL | Backend publisher (sponsored, walletless), upload relay, or SDK with a backend signer | walrus-http-api |
| Confirm a blob is durably stored before depending on it | walrus blob-status / getBlobObject |
walrus-blob-lifecycle |
Walrus vs traditional storage
| Walrus | AWS S3 / Cloud Storage | |
|---|---|---|
| Control | No single operator controls data | Provider controls everything |
| Trust model | Cryptographic verification | Platform trust |
| Fault tolerance | Survives 2/3 node failures | Provider SLA |
| Privacy | All data public by default | Private by default |
| Cost model | WAL + SUI tokens, per-epoch | USD, per-month |
| Duration | Max ~2 years per purchase, renewable | Indefinite |
| Structure | Flat blob storage (no directories) | Directories/buckets |
| Verifiability | Cryptographic blob IDs, on-chain certificates | None |
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.
Pick a service
Match the constraint you actually have:
- Your caller reads blobs: use an aggregator.
- Your caller cannot hold SUI or WAL: use a publisher, and on Mainnet run and authenticate your own.
- Your caller holds a wallet but runs in a browser or on mobile: use an upload relay.
- Your caller runs server-side with a funded wallet: write through the TypeScript SDK, which talks to storage nodes directly.
Rules
- All blobs are public. Encrypt before uploading if you need privacy.
- Storage is time-limited. Plan for renewals. Maximum is 53 epochs (~2 years on mainnet).
- You need both WAL and SUI. WAL pays for storage, SUI pays for gas.
- No public mainnet publisher. Use the upload relay, TypeScript SDK, CLI, or run your own publisher.
- Small blobs are expensive individually. Use quilts for batches of small files.
- Blob ID is not object ID. Content hash (for reading) vs on-chain object (for management). Do not confuse them.