Managing Blobs

Using an agent? Try this prompt

I stored a blob 40 epochs ago and it expires in two. Extend it another 20 epochs, set content-type to application/pdf on it, then convert it to something anyone can top up when it runs low again.

Use the Walrus client to manage blobs and their metadata.

Check a blob's status and expiry

Before you extend or depend on a blob, check that it is still stored and see when it expires. Use the blob ID:

$ walrus blob-status --blob-id <BLOB_ID>

This reports whether the blob is stored and its availability period. Read the current epoch with walrus info, then compare it against the blob's end epoch to see how much time remains. A blob expires at the beginning of its end epoch, so renew it before the current epoch reaches that value.

To check programmatically, read the blob's Blob object from Sui and compare the current epoch against storage.end_epoch. See Verify blob availability before acting for the object fields and a TypeScript check.

tip

Check status on a schedule rather than waiting for a read to fail. Looking well before the end epoch gives you time to extend and avoids surprise expiry.

Extend the lifetime of a blob

You can extend Walrus blob lifetimes using the following command:

$ walrus extend --blob-obj-id <BLOB_OBJECT_ID>

The blob cannot be expired when you run this command. Both address-owned blobs and shared blobs can have their lifetime extended. Anyone can extend shared blobs, but only the owner can extend owned blobs. When extending a shared blob, supply the --shared flag to inform the command that the blob is shared.

You need the blob's object ID to extend it. The blob ID is not needed. Run walrus extend --help for more information on blob extension.

Delete blobs

You can delete a blob that was set as deletable upon creation before its expiry, but only the owner of the Sui object corresponding to the blob can do so. Deletable blobs are indicated as such in the Sui events that certify them, and other users should not rely on them for availability.

Delete a blob with the following command:

$ walrus delete --blob-id <BLOB_ID>

You can also invoke the delete command by specifying a --file <PATH> option to derive the blob ID from a file, or by using --object-id <SUI_ID>. Before deleting a blob, the walrus delete command asks for confirmation unless you specify the --yes option.

The delete command reclaims the storage object associated with the deleted blob, which is reused to store new blobs automatically. The delete operation provides flexibility around managing storage costs and reusing storage.

The delete operation has limited utility for privacy. It only deletes slivers from the current epoch storage nodes and subsequent epoch storage nodes if no other user has uploaded a copy of the same blob. If another copy of the same blob exists in Walrus, the delete operation does not make the blob unavailable for download, and walrus read invocations still download it. After the deletion finishes, the CLI checks the updated status of the blob to see if it is still accessible in Walrus, unless you specified the --no-status-check option. However, even if the blob is not accessible, copies of the public blob might be cached or downloaded by users, and those copies are not deleted.

danger

All blobs stored in Walrus are public and discoverable by all. The delete command does not delete slivers if other copies of the blob are stored on Walrus, possibly by other users. It does not delete blobs from caches, slivers from past storage nodes, or copies that users might have made before the blob was deleted.

Burn blobs

Burn a blob to remove the blob's corresponding object on Sui without deleting the data from Walrus and without refunding the storage. Burning a blob's corresponding Sui object forfeits control of that blob and the data it represents. After burning, you cannot extend permanent blobs and you cannot extend or delete deletable blobs.

You can only burn blobs owned by the current wallet.

To burn a blob, provide its Sui object ID:

$ walrus burn-blobs --object-ids <BLOB_OBJECT_ID>

Use the --all flag to burn all blob objects owned by the current wallet. Use the --all-expired flag to burn all expired blob objects owned by the current wallet.

Shared blobs

Shared blobs are shared Sui objects wrapping standard Blob objects that anyone can fund and extend. See the shared blob contracts for further details.

Create a shared blob from an existing Blob object you own with the walrus share command:

$ walrus share --blob-obj-id <SUI_OBJ_ID>

You can directly fund the resulting shared blob by adding --amount, or fund an existing shared blob with the walrus fund-shared-blob command. You can also immediately share a newly created blob by adding the --share option to the walrus store command.

Shared blobs can only contain permanent blobs and cannot be deleted before their expiry.

Set blob attributes

Set attributes for a blob using the following command:

$ walrus set-blob-attribute <BLOB_OBJECT_ID> --attr "key" "value"

Attributes are key-value pairs. You can specify multiple pairs by repeating the flag: --attr "key1" "value1" --attr "key2" "value2".

Get blob attributes

Get a blob's attributes using the following command:

$ walrus get-blob-attribute <BLOB_OBJECT_ID>

Remove blob attributes

Remove all attributes from a blob using the following command:

$ walrus remove-blob-attribute <BLOB_OBJECT_ID>

Remove a specific key-value pair from a blob's attributes using the following command:

$ walrus remove-blob-attribute-fields <BLOB_OBJECT_ID> --keys "key1"

Example: manage a blob's lifecycle

This example walks through the full lifecycle of a blob: store it for a chosen period, confirm it is stored, extend it before it expires, and delete it to reclaim storage.

1. Store the blob for a set number of epochs. Choose --permanent when the data must remain for the full period, or keep the default deletable blob when you want the option to delete and reclaim storage early. See Blob lifetimes and Blob permanence.

$ walrus store <FILE> --epochs <EPOCHS>

2. Confirm the blob is stored and note its end epoch.

$ walrus blob-status --blob-id <BLOB_ID>

3. Before the blob reaches its end epoch, extend its lifetime so the data stays available. You need the blob's object ID, not the blob ID. See Extend the lifetime of a blob.

$ walrus extend --blob-obj-id <BLOB_OBJECT_ID>

4. When you no longer need a deletable blob, delete it to release its storage object for reuse, which helps manage storage costs.

$ walrus delete --blob-id <BLOB_ID>

note

You can extend a blob only before it expires, so monitor the end epoch and renew in time. Permanent blobs cannot be deleted before expiry, so choose permanence at store time based on how long the data must live.