Walrus Blob Lifecycle

Walrus Blob Lifecycle

Source constraint: All information in this skill is sourced from the Walrus managing blobs documentation and the large uploads guide. When extending this skill, only pull from these sources.

Walrus blobs have finite lifetimes measured in epochs. This skill covers all post-storage operations: extending lifetimes, deleting, burning, sharing, setting attributes, and planning large data uploads.

All patterns in this skill are derived from:

• https://docs.wal.app/docs/walrus-client/managing-blobs
• https://docs.wal.app/docs/walrus-client/storing-blobs (lifetime options)
• https://docs.wal.app/docs/large-uploads

If unsure about any lifecycle operation, fetch the relevant page before answering.

Reference files

large-uploads — Large Data Upload Patterns

Path: large-uploads.md Load when: planning uploads larger than 1 GiB, estimating storage costs for large datasets, managing concurrent upload memory, or building ingestion pipelines. Covers: cost estimation, tuning for >1 GiB uploads, upload observability, pipeline state persistence, throughput management, memory overhead (4.5x blob size).

Related skills

Routing guide

Skill Content

Key concepts

• Epochs and lifetimes. Blob storage duration is measured in epochs. A Mainnet epoch is 14 days. Maximum storage is 53 epochs (approximately 2 years). A blob expires at the beginning of its end epoch. Use walrus info or GET /v1/info on an aggregator to check the current epoch and duration.

• Blob ID vs Sui object ID. A blob ID is a URL-safe base64 string derived from the blob content (content-addressed). The same content always produces the same blob ID. A Sui object ID is a 0x... hex string identifying the on-chain Blob object. Each upload creates a new object ID even for identical content. Use blob ID for reading content, object ID for lifecycle operations (extend, delete, share).

• Deletable vs permanent. Newly stored blobs are deletable by default. Deletable blobs can be removed by the Sui object owner before expiry. Permanent blobs cannot be deleted before expiry, even by the uploader.

• What happens when a blob expires. When a blob's end epoch is reached, the data becomes unavailable. There is no grace period. Storage nodes discard slivers. You must re-upload the data to make it available again. Expired blobs cannot be extended.

• Wrapping blobs in shared objects. A Blob object can be wrapped into any Sui shared object, allowing multiple parties to fund and extend it. The Walrus contract provides shared_blob::SharedBlob as one reference implementation of this pattern, but developers are free to create their own shared wrapper with custom logic (access control, metadata, etc.).

• Storage pools. A storage pool is the recommended way to manage blob storage going forward. Instead of purchasing storage resources per-blob, you fund a pool and blobs draw from it. This simplifies lifecycle management—blobs in a pool can be extended or renewed without individual storage resource tracking. Use walrus store --storage-pool <POOL_ID> to store against a pool.

• Blob attributes. Key-value metadata pairs stored on the blob's Sui object. Certain keys (content-type, content-disposition, and others) are recognized by the aggregator and returned as HTTP headers when reading by object ID.

• Per-blob storage overhead. Each blob incurs approximately 64 MB of metadata overhead regardless of size. For blobs smaller than ~10 MB, this metadata cost dominates. Use quilts for batching many small blobs to amortize this overhead.

Extend blob lifetime

# Extend by blob Sui object ID
walrus extend --blob-obj-id <BLOB_OBJECT_ID>

# Extend with a specific new end epoch
walrus extend --blob-obj-id <BLOB_OBJECT_ID> --end-epoch <EPOCH>

# Extend a shared blob (requires --shared flag)
walrus extend --blob-obj-id <BLOB_OBJECT_ID> --shared

• The blob must not be expired.
• Both owned and shared blobs can be extended.
• Only the owner can extend owned blobs. Anyone can extend shared blobs.
• You need the blob's Sui object ID (not the blob ID).

Delete blobs

# Delete by blob ID
walrus delete --blob-id <BLOB_ID>

# Delete by file (derives blob ID)
walrus delete --file <PATH>

# Delete by Sui object ID
walrus delete --object-id <SUI_ID>

# Skip confirmation prompt
walrus delete --blob-id <BLOB_ID> --yes

# Skip post-delete status check
walrus delete --blob-id <BLOB_ID> --yes --no-status-check

Important caveats:

• Only the owner of the Sui Blob object can delete a deletable blob.
• Delete reclaims the storage resource, which is reused automatically.
• Delete only removes slivers from current and future storage nodes. If another copy of the same blob exists (uploaded by someone else), the data remains accessible.
• Delete has limited utility for privacy. All blobs are public. Cached or previously downloaded copies are not affected.

Burn blobs

Burning removes the blob's Sui object without deleting data from Walrus and without refunding storage:

# Burn a specific blob by object ID
walrus burn-blobs --object-ids <BLOB_OBJECT_ID>

# Burn all blob objects owned by the current wallet
walrus burn-blobs --all

# Burn all expired blob objects
walrus burn-blobs --all-expired

After burning, you cannot extend permanent blobs or extend/delete deletable blobs. You lose all control of the blob.

Shared blobs

A blob can be wrapped into a Sui shared object so that anyone can fund and extend it. The Walrus contract provides shared_blob::SharedBlob as one reference implementation, but you can also wrap a Blob into your own custom shared object with whatever logic you need.

Using the built-in SharedBlob via the CLI:

# Share an existing blob using the built-in SharedBlob
walrus share --blob-obj-id <SUI_OBJ_ID>

# Fund an existing shared blob
walrus fund-shared-blob --blob-obj-id <SHARED_OBJ_ID> --amount <WAL_AMOUNT>

# Store and share in one step
walrus store myfile.png --epochs 10 --share

Built-in shared blobs:

• Can only contain permanent blobs
• Cannot be deleted before expiry
• Anyone can fund and extend them

For more control, consider wrapping the Blob in your own shared object (see walrus-move-integration).

Storage pools

Storage pools are the recommended way to manage blob storage. Instead of purchasing individual storage resources per blob, you fund a pool and blobs draw from it.

# Store a blob using a storage pool
walrus store myfile.png --epochs 10 --storage-pool <POOL_ID>

Benefits:

• Simplifies lifecycle management—no individual storage resource tracking
• Blobs in a pool can be extended or renewed from the pool's funds
• Multiple blobs can share a single funding source

Blob attributes

# Set attributes (multiple key-value pairs supported)
walrus set-blob-attribute <BLOB_OBJECT_ID> --attr "content-type" "image/png" --attr "creator" "myapp"

# Get attributes
walrus get-blob-attribute <BLOB_OBJECT_ID>

# Remove all attributes
walrus remove-blob-attribute <BLOB_OBJECT_ID>

# Remove specific keys
walrus remove-blob-attribute-fields <BLOB_OBJECT_ID> --keys "creator"

Recognized HTTP header attribute keys: content-disposition, content-encoding, content-language, content-location, content-type, link. These are returned as HTTP headers when reading by object ID.

Rules

1. Blobs expire at the beginning of the end epoch. A blob with end epoch 314 becomes unavailable at the start of epoch 314. Plan accordingly.
2. You cannot extend expired blobs. Extend before expiration. Monitor expiration with walrus blob-status.
3. Delete does not guarantee data removal. Other copies of the same blob might exist. Caches and past storage nodes are not affected.
4. Shared blobs must be permanent. You cannot share a deletable blob. Convert to permanent first or store as permanent with --share.
5. Burn is irreversible. Burning a blob object forfeits all control with no storage refund. Use --all-expired to clean up expired blobs safely.
6. Maximum blob size is approximately 13.6 GiB. For large uploads, see the large-uploads.md reference file.

Common mistakes

• Extending with the blob ID instead of the object ID. The extend command requires --blob-obj-id (Sui object ID), not the blob ID.
• Trying to extend an expired blob. Once expired, a blob cannot be extended. You must re-upload.
• Expecting delete to make data completely unavailable. If another user uploaded the same content, it persists. Encryption is the only reliable privacy mechanism.
• Burning blobs that still have value. Burning is permanent, forfeits storage, and provides no refund. Use delete to reclaim storage instead.
• Sharing a deletable blob. Shared blobs require permanent blobs. Store with --permanent --share or ensure the blob is permanent before sharing.
• Storing with --epochs 1 near an epoch boundary. The blob expires almost immediately. Use generous epoch counts.