docs: add a storage pools concept and usage guide - #3648
Open
halfprice wants to merge 4 commits into
Open
Conversation
Contributor
|
Contributor
📋 afdocs check resultsURL: https://MystenLabs.github.io/walrus/pr-preview/pr-3648/ |
Contributor
Style Guide AuditAudited 1 file(s) against the Sui Documentation Style Guide. 6 violation(s) found. All must be fixed before merge.
|
Collaborator
Author
Addressed |
halfprice
force-pushed
the
zhewu/storage_pool_doc
branch
from
August 17, 2026 20:22
2d222a0 to
9d84d4c
Compare
reemsabawi-mystenlabs
requested changes
Aug 19, 2026
|
|
||
| ## How storage pools work | ||
|
|
||
| A storage pool is a Sui object that wraps a storage resource with a fixed encoded capacity and a lifetime spanning a start epoch up to, but not including, an end epoch. The pool tracks three things: its reserved encoded capacity, the encoded bytes currently in use, and the number of registered blobs. Blobs stored in a pool are represented by `PooledBlob` objects that live inside the pool rather than as independently owned `Blob` objects. |
Contributor
There was a problem hiding this comment.
Passive: "Blobs stored in a pool are represented by PooledBlob objects that live inside the pool rather than as independently owned Blob objects." I recommend changing to: "The pool represents each blob as a PooledBlob object that lives inside the pool rather than as an independently owned Blob object."
Collaborator
Author
There was a problem hiding this comment.
Done, applied the suggested wording.
| .await?; | ||
| ``` | ||
|
|
||
| When sizing the capacity, remember that it is consumed by *encoded* blob sizes. You can compute a blob's exact encoded size with `walrus_core::encoding::encoded_blob_length_for_n_shards`, or check it for a sample file with `walrus store --dry-run`. The pool's lifetime is bounded by the system's maximum blob lifetime, currently 53 epochs, the same limit that applies to [regular blob lifetimes](/docs/walrus-client/managing-blobs). |
Contributor
There was a problem hiding this comment.
Passive: "remember that it is consumed by encoded blob sizes." I recommend changing to: "remember that blobs consume it at their encoded size."
Collaborator
Author
There was a problem hiding this comment.
Done, applied the suggested wording.
|
|
||
| ## Common pitfalls | ||
|
|
||
| - **Sizing the pool in raw bytes.** Reserved capacity is consumed by encoded sizes, about 4.5x the raw size plus roughly 64 MB of metadata per blob. A pool sized to the sum of your raw file sizes runs out of capacity almost immediately. |
Contributor
There was a problem hiding this comment.
Passive: "Reserved capacity is consumed by encoded sizes, about 4.5x the raw size..." I recommend changing to: "Blobs consume reserved capacity at their encoded size, about 4.5x the raw size plus roughly 64 MB of metadata per blob."
Collaborator
Author
There was a problem hiding this comment.
Done, applied the suggested wording.
Documents the storage pool preview feature: what a pool is, its shared lifetime and reusable-capacity model, cost structure, when to prefer it over individual blobs or Quilt, the pool operation surface, and how to use it through the Rust SDK and the Move contracts.
Adds an at-a-glance comparison with regular blobs, a pool state table, a per-operation fee breakdown, a decision guide, expanded Rust SDK examples covering the full lifecycle, the Move entry-point signatures, an events reference for indexers, and common pitfalls. Also adds storage pool and pooled blob glossary entries so the terms auto-link site-wide.
Addresses the style guide audit on the storage pools page, which disallows em dashes; the empty fee cells in the costs and operations tables now say None.
Applies review suggestions to use active voice for how pooled blobs are represented and how blobs consume reserved capacity.
halfprice
force-pushed
the
zhewu/storage_pool_doc
branch
from
August 19, 2026 20:31
3e014ba to
f3f62db
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a documentation page for the storage pool preview feature, which currently has no coverage in the docs beyond release-note mentions.
The new page (
docs/content/system-overview/storage-pools.mdx, added to the Concepts sidebar next to Quilt) covers:reserve_and_store_blobs_in_storage_poolwith result handling, inspect withstorage_pool_statusandlist_pooled_blob_ids, delete, extend, and increase capacity — including the SDK's documented caveats (no automatic lifetime extension, no automatic epoch-change retry, automatic capacity increase,PostStoreAction::Keeponly, deletable by default).walrus::systementry-point signatures, Move-only capabilities (pool creation from an existingStorage, capacity decrease, burn and destroy, pooled-blob metadata), theblob_bucketwrapper, and a danger admonition about sharing a rawStoragePool.Also adds "storage pool" and "pooled blob" entries to the glossary so the terms auto-link site-wide.
The page is marked with a warning that the feature is a preview available only through the Rust SDK and Move contracts, with no CLI, HTTP API, or TypeScript SDK support yet.
Test plan
node src/scripts/audit-docs.mjs: the new page passes all frontmatter, link, code-fence, and goal checks.pnpm buildindocs/site: succeeds; no broken links or anchors introduced by the new page.crates/walrus-sdk(StoreBlobsInStoragePoolApi,PooledBlobStoreResult,StoreArgsdefaults) and the e2e tests incrates/walrus-e2e-tests/tests/test_client.rs.