Managing Blobs

Use the Walrus client to manage blobs and their metadata.

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"