Skip to main content

Off-Chain Operations

Walrus operations primarily occur off-chain on storage nodes, though they interact with the Sui blockchain for resource lifecycle management. This page describes the complete off-chain operations for writing, reading, and managing blobs.

Write operations​

Write paths of Walrus

Acquire storage resource​

You acquire a storage resource of appropriate size and duration on-chain, either by directly buying it from the Walrus system object or a secondary market. You can split, merge, and transfer owned storage resources.

Encode and compute blob ID​

When you want to store a blob, you first apply erasure coding to the blob, and then compute the blob ID from the encoded data. You can then perform the remaining write flow steps yourself, or use a publisher to perform the steps on your behalf.

Register blob ID​

Interact with Sui to update a storage resource and register the blob ID with the desired size and lifetime. This emits an event that the Walrus storage nodes receive. The upload continues after event confirmation.

Store slivers​

Send the blob metadata to all storage nodes. Each of the blob slivers are sent to the storage node that currently manages the corresponding shard.

Availability certificate​

A storage node managing a shard receives a sliver and checks it against the blob ID. It also checks that there is a blob resource with the blob ID that is authorized to store a blob. If correct, the storage node then signs a statement that it holds the sliver and returns it to you. Then, you can put together the signatures returned from storage nodes into an availability certificate.

Certify blob ID​

Submit an availability certificate to the chain. When the certificate is verified on-chain, an availability event for the blob ID is emitted, and all other storage nodes seek to download any missing shards for the blob ID. This event emitted by Sui is the point of availability (PoA) for the blob ID.

After the PoA, and without your involvement, storage nodes sync and recover any missing metadata and slivers.

Effects certificate proves availability​

The certificate of availability is created from 2/3 of the returned shard signatures. The erasure code rate is below 1/3, meaning that reconstruction is allowed even if only 1/3 of shards return the sliver for a read. Because at most 1/3 of the storage nodes can fail, this ensures reconstruction if you request slivers from all storage nodes. A publisher can mediate the full process by receiving a blob and driving the process to completion.

Read operations​

Reading blobs from Walrus can occur directly or through aggregators and caches. The operations are identical whether performed by end users, aggregators, or caches experiencing cache misses. In practice, most reads occur through caches for frequently accessed (hot) blobs and do not require requests to storage nodes.

The read flow consists of the following steps:

  1. Obtain the metadata for the blob ID from any storage node and authenticate it using the blob ID.
  2. Send a request to the storage nodes for the shards corresponding to the blob ID and wait for (f+1) responses. Send sufficient requests in parallel to ensure low latency for reads.
  3. Authenticate the slivers returned with the blob ID, reconstruct the blob, and decide whether the contents are valid or inconsistent.
  4. Optionally, the result is cached and can be served without reconstruction until it is evicted from the cache. Requests to the cache for the blob return the blob contents or an inconsistency proof.

Refresh availability​

Because no blob content is involved, refresh operations are conducted entirely through the Sui protocol. To extend blob availability, provide an appropriate on-chain storage resource. Upon success, storage nodes receive an emitted event to extend the storage duration for each sliver.

Inconsistency handling​

After the PoA, a correct storage node attempting to reconstruct a sliver might fail if blob encoding was incorrect. In this case, the node can extract an inconsistency proof for the blob ID. It then uses the proof to create an inconsistency certificate and uploads it on-chain.

The flow is as follows:

  1. A storage node fails to reconstruct a sliver, and instead computes an inconsistency proof.
  2. The storage node sends the blob ID and inconsistency proof to all storage nodes of the Walrus epoch. The storage nodes verify the proof and sign it.
  3. The storage node that found the inconsistency aggregates the signatures into an inconsistency certificate and sends it to the Sui smart contract, which verifies it and emits an inconsistent resource event.
  4. Upon receiving an inconsistent resource event, correct storage nodes delete sliver data for the blob ID and record in the metadata to return None for the blob during the availability period. No storage attestation challenges are issued for this blob ID.

Reading inconsistent blobs​

A blob ID marked as inconsistent always resolves to None upon reading. This occurs because the read process re-encodes the received blob to verify that the blob ID was derived from consistent encoding.

An inconsistency proof reveals only a true fact to storage nodes (which do not otherwise run decoding) and does not change read output in any case.

However, partial reads leveraging the systematic nature of the encoding might successfully return partial data for inconsistently encoded files. If consistency and availability of reads is important, perform full reads rather than partial reads.

Challenge mechanism for storage attestation​

During an epoch, a correct storage node challenges all shards to provide symbols for blob slivers past PoA:

  • The list of available blobs for the epoch is determined by the sequence of Sui events up to the past epoch. Inconsistent blobs are not challenged, and a record proving this status can be returned instead.

  • A challenge sequence is determined by providing a seed to the challenged shard. The sequence is then computed based on the seed and the content of each challenged blob ID. This creates a sequential read dependency.

  • The response to the challenge provides the sequence of shard contents for the blob IDs in a timely manner.

  • The challenger node uses thresholds to determine whether the challenge was passed, and reports the result on-chain.

  • The challenge and response communication is authenticated.

Challenges provide some reassurance that the storage node can actually recover shard data in a probabilistic manner, avoiding storage nodes getting payment without any evidence they might retrieve shard data. The sequential nature of the challenge and some reasonable timeout also ensures that the process is timely.