Skip to main content

Basic Architecture and Security Assumptions

The Walrus architecture is built on the following key actors:

  • Users: Clients that store and retrieve data blobs.
  • Storage nodes: Distributed storage nodes that hold erasure-coded data.
  • Blockchain coordination: Sui blockchain that manages payments, metadata, and system orchestration.

Users​

Users interact with Walrus through clients to store and read blobs, which are identified by their blob ID. Users engage with the system in two primary ways:

Users might also exhibit malicious behavior, including:

  • Refusing to pay for services
  • Attempting to prove availability of unavailable blobs
  • Modifying or deleting blobs without authorization
  • Exhausting storage node resources

Storage nodes​

Storage nodes manage the actual data storage on Walrus. Each storage node holds one or more shards during a storage epoch. Each blob undergoes erasure encoding, which splits it into many slivers. These slivers from each stored blob become distributed across all shards in the system. At any given storage epoch, a storage node associates with one or more shards. The node stores all slivers belonging to its assigned shards and serves them upon request.

Blockchain coordination​

All clients and storage nodes run a Sui blockchain client, which provides the coordination layer for the entire system. The Sui network manages several operations, including:

  • Payments: Processing storage fees and service payments.
  • Resource management: Allocating and tracking storage capacity.
  • Shard assignment: Mapping shards to storage nodes.
  • Metadata management: Storing blob certificates and system state.

Users interact with the Sui network to acquire storage resources and submit certificates for stored blobs. Storage nodes monitor blockchain events to coordinate their operations and respond to system changes.

Byzantine fault tolerance​

A Sui smart contract controls how shards are assigned to storage nodes. These assignments occur within storage epochs, which last 2 weeks on Mainnet.

Walrus assumes that more than 2/3 of shards are managed by correct storage nodes within each storage epoch. The system tolerates up to 1/3 of shards being controlled by Byzantine (malicious or faulty) storage nodes. This tolerance level applies both within individual storage epochs and across transitions between epochs.

Optional infrastructure​

Walrus supports any additional number of optional infrastructure actors that can operate in a permissionless way.

Aggregators​

Aggregators are clients that reconstruct complete blobs from individual slivers and serve them to users over traditional Web2 technologies like HTTP. They are optional because end users can reconstruct blobs directly from storage nodes or run a local aggregator to perform reads over Web2 protocols.

Caches​

Caches are aggregators with additional caching functionality to decrease latency and reduce load on storage nodes. Cache infrastructures can also act as CDNs, split the cost of blob reconstruction over many requests, and provide better network connectivity. A client can always verify that reads from cache infrastructures are correct.

Publishers​

Publishers are clients that help end users store blobs through Web2 technologies while using less bandwidth and offering custom logic. Publishers streamline the storage process by:

  1. Receiving the blob over traditional Web2 protocols (like HTTP)
  2. Encoding the blob into slivers
  3. Distributing slivers to storage nodes
  4. Collecting storage node signatures
  5. Aggregating signatures into a certificate
  6. Performing all required on-chain actions

Publishers are optional because users can directly interact with Sui and storage nodes to store blobs. An end user can always verify that a publisher performed their duties correctly by checking that an event associated with the point of availability for the blob exists on-chain, and then either performing a read to see if Walrus returns the blob, or encoding the blob and comparing the result to the blob ID in the certificate.

Aggregators, publishers, and end users are not considered trusted system components, and they might arbitrarily deviate from protocol. However, some of the security properties of Walrus only hold for honest end users that use honest intermediaries (caches and publishers). Walrus provides a means for end users to audit the correct operation of both caches and publishers.