Walrus Explained: What It Is and When to Use It

Every object in Walrus is referenced solely by a content-addressed blob_id generated from the file hash at upload. Blob_id is the only canonical reference—no mutable pointers, no secondary keys. This design eliminates ambiguity: if you don’t have the blob_id, you can’t fetch the object, and there’s no way to “rename” or “move” blobs within the system.

Persisted metadata is strictly limited to size_bytes, content_type, and created_at. There’s no support for custom fields or arbitrary key-value tags. This keeps the storage layer lean, but means any application-level metadata or indexing must be handled externally.

Blob verification is performed by re-hashing content and matching the blob_id. This ensures end-to-end integrity: if the content doesn’t match the hash, the upload is rejected or the retrieval fails. There’s no way to “update” a blob in place—immutability is enforced at the protocol level.

RedStuff erasure coding provides durability with a typical 4.5× storage overhead. This means a 10 MB file will consume roughly 45 MB across the cluster, trading raw capacity for fault tolerance. Erasure coding parameters (data/parity shards) are tunable per deployment or workload, allowing operators to balance cost and resilience as needed source.

Upload relay is mandatory for production to ensure reliability, retries, and idempotency. The relay abstracts node failures and guarantees the same blob_id always maps to the same content, regardless of transient errors or network splits source. Relay introduces extra latency but is essential for high-throughput and operational stability. Direct browser-to-node uploads are discouraged for reliability reasons.

Walrus does not support querying, filtering, or indexing—external DB or indexer required for discovery. If you need to look up blobs by anything other than blob_id, you’ll need to maintain your own mapping layer. This is a deliberate constraint: Walrus is for durable, verifiable storage, not for search or rich metadata queries.

Sui integration: blob_id must be certified and point-of-availability established before on-chain reference. Certification ensures blob availability from the Walrus network before smart contract use, preventing broken links or missing data on-chain source.

The TypeScript SDK supports full relay flow and Sui integration, including retries and duplicate avoidance. Builders can rely on the SDK to handle edge cases like partial uploads, network retries, and ensuring that duplicate uploads are rejected source.

Strict blob size limit (currently 128 MiB) and error handling—partial/duplicate uploads are rejected. This is enforced both at the relay and node level. Large files must be chunked and managed at the application layer.

Relay guarantees that the same blob_id always maps to the same content, making uploads idempotent even under failure or retry conditions. This property is critical for distributed workflows, where duplicate or partial uploads would otherwise cause ambiguity or data loss.

Blob verification is not optional—every retrieval or certification step re-hashes the content to confirm the blob_id, enforcing strong integrity guarantees. This is a hard requirement for Sui integration, where on-chain references must never point to unavailable or tampered data.

The operational cost of RedStuff erasure coding is non-trivial, with a typical 4.5× storage overhead, but this is the tradeoff for high durability in adversarial or unreliable environments. Operators can tune data/parity shard ratios, but reducing overhead comes at the expense of fault tolerance.

Builders should choose Walrus for durability and verifiability, not for search or rich metadata queries. If your use case is about storing immutable, content-addressed blobs with strong integrity and operational guarantees, Walrus is a fit. For anything requiring flexible queries, secondary keys, or mutable objects, look elsewhere.