Walrus Storage reference

Shapes and identifiers behind the Walrus Storage app. Conceptual here; the exhaustive, always-current API is auto-generated from the @meddleware/walrus-storage-client SDK — see SDK API.

Blob lifetime

Walrus measures storage in epochs. The client exposes protocol-bounded constants (e.g. a long-term default and a maximum single reservation) that reflect Walrus's max_epochs_ahead. You choose a duration at upload time and can extend later; extension must happen before expiry.

Upload result

An upload returns the stable blob ID and the on-chain blob object ID:

type UploadResult = {
  blobId: string        // Walrus content-addressed blob ID: the stable handle used to read the blob back
  blobObjectId: string  // the on-chain Walrus Blob object ID
}

Owned blob

My Blobs lists the blobs your address owns:

type OwnedBlob = {
  objectId: string   // the on-chain Blob object ID
  blobId: string     // aggregator-URL-compatible blob ID
  size: number       // bytes
  startEpoch: number
  endEpoch: number   // storage expires at this epoch
  certified: boolean
  deletable: boolean // blobs are registered permanent by default
}

Storage cost estimate

Before confirming, the app estimates cost from the chosen duration:

type StorageCost = {
  storageCost: bigint // per-epoch storage cost × epochs, in MIST (what an extension pays)
  writeCost: bigint   // one-time write cost, in MIST (paid on registration, not on extend)
  totalCost: bigint   // storageCost + writeCost
}

Gated relay: access-proof wire format

When uploading through the gated relay, the client proves NFT ownership with a signed proof. The wire format is shared with the Access Gate gateway:

• Personal message signed by the wallet (v2, audience-bound): access-gate-gateway:access:v3 followed by the gateway origin, gate id, network, nonce and (single-use gates only) the consume digest, one key:value line each. The gateway rebuilds it from its own origin, gate and network, so a signature is useless at any other relay, gate or network. The exact text is in the personalMessage reference.
• Proof token (sent as Authorization: Bearer …): base64 of

{ "address": "0x…", "nonce": "…", "signature": "…", "consumeDigest": "…" }

The relay verifies the signature and on-chain pass ownership, then accepts the upload. See the Access Gate reference for the full protocol.

SDK API

The full @meddleware/walrus-storage-client API — client factory, upload flows, lifetime management, owned-blob queries, and relay access helpers — is generated here:

• Walrus client API

Using the SDK in your own app?

See the Walrus Storage integration guide on the developer site — SDK setup, upload/read patterns, relay self-host, and Vue composables.