Using Walrus with Move
Every Walrus blob has a corresponding Blob object on Sui. In Move, the type of that object is Blob, defined in the walrus::blob module of the Walrus package. It has the key and store abilities, so your own Move packages can hold blobs in custom structs, transfer them between addresses, and manage their lifecycle onchain. Add the Walrus package as a dependency to read blob properties, wrap blobs in your own object types, and call the system functions that extend or delete blobs.
Add the Walrus dependency
Declare the Walrus package as a git dependency in your package's Move.toml:
docs/examples/move/walrus_dep/Move.toml. You probably need to run `pnpm prebuild` and restart the site.The contracts/walrus subdirectory contains the development sources. The Walrus repository also tracks the sources deployed on each network in the mainnet-contracts and testnet-contracts directories, and the Network Reference lists the deployed package and object IDs.
Wrap a blob object
Because Blob has the store ability, you can embed it in your own object types. The following example module accepts a Blob by value and escrows it inside a WrappedBlob:
docs/examples/move/walrus_dep/sources/wrapped_blob.move. You probably need to run `pnpm prebuild` and restart the site.After wrapping, only the functions of the wrapping module can reach the blob again, which gives your package full control over where the blob can be transferred next and who can manage it. A marketplace escrow, a vault, or an app-specific asset type all follow this pattern.
Read blob properties
The walrus::blob module exposes accessors for every Blob field:
| Accessor | Returns | Description |
|---|---|---|
object_id | ID | The Sui object ID of the Blob object. |
blob_id | u256 | The blob ID that identifies the data on Walrus. |
size | u64 | The unencoded blob size in bytes. |
encoding_type | u8 | The blob's erasure encoding. |
registered_epoch | u32 | The Walrus epoch of the blob's registration. |
certified_epoch | &Option<u32> | The epoch of first certification, or none for an uncertified blob. |
storage | &Storage | The storage resource that backs the blob. |
end_epoch | u32 | The end epoch of the blob's storage resource (exclusive). |
is_deletable | bool | Whether the owner can delete the blob before expiry. |
encoded_size | u64 | The encoded size in bytes for a given number of shards. |
To check whether a blob is still live, read certified_epoch, which stays none until Walrus certifies the blob, and compare end_epoch against the current epoch from the shared system object with system.epoch().
Manage the blob lifecycle
The walrus::system module exposes lifecycle functions on the shared System object:
extend_blob(system, blob, extended_epochs, payment)extends the blob's storage byextended_epochsepochs and draws the storage fee from aCoin<WAL>.extend_blob_with_resource(system, blob, extension)extends the blob with aStorageresource you already own; the resource must match the blob's storage size and last longer.delete_blob(system, blob)consumes a deletable blob and returns itsStorageresource, which you can reuse for another blob.
The walrus::blob module additionally provides burn(blob), which destroys the Blob object without deleting the data from Walrus and without refunding storage, and metadata functions such as insert_or_update_metadata_pair and remove_metadata_pair to manage key-value metadata on a blob you hold. The Managing Blobs page describes the CLI equivalents.
Share a blob
The walrus::shared_blob module wraps a Blob in a SharedBlob, a shared object that acts as a tip jar: anyone can add WAL to it, and anyone can spend the stored funds to extend the wrapped blob's lifetime.
new(blob, ctx)shares the blob as aSharedBlobwith zero funds.new_funded(blob, funds, ctx)shares the blob together with an initialCoin<WAL>balance.fund(shared_blob, coin)adds WAL to the stored funds.extend(shared_blob, system, extended_epochs, ctx)extends the wrapped blob using the stored funds.
The CLI offers the same capability through walrus share --blob-obj-id <SUI_OBJ_ID>; see Shared blobs.
Build, test, and publish
The complete example package lives in the docs/examples/move/walrus_dep directory of the Walrus repository. From that directory, run:
sui move build
sui move test
sui client publish --skip-dependency-verification