Expand description
§IC Storage
Named stable-memory allocations with upstream ic-stable-structures collections.
One crate owns allocation names, namespace grants, exclusive leases and checked
reopening. DFINITY’s library owns the B-tree, set, cell, vector, heap and log engines.
The default allocation limit is 4,096. StableKey accepts up to 128 bytes of
lowercase ASCII dot-separated names ending in a nonzero .vN, for example
app.users.v1. Names remain bound to opaque IDs across ordinary IC upgrades.
Applications do not assign numeric memory IDs.
use ic_storage::{AllocationGrants, GenericAllocationPolicy, MemoryAuthority,
MemoryRequest, MemoryRuntime, SealedDeclarationSnapshot, StableKey, VectorMemory};
use ic_storage::adapter::StableBTreeMap;
let mut host = MemoryRuntime::new(VectorMemory::default()).unwrap();
let declarations = SealedDeclarationSnapshot::new(vec![
MemoryRequest::new("app", "app.users.v1").unwrap(),
]).unwrap();
let grants = AllocationGrants::new(vec![MemoryAuthority::new("app", "app.").unwrap()]).unwrap();
host.bootstrap(&declarations, &grants, &GenericAllocationPolicy).unwrap();
let memory = host.open_memory(&StableKey::parse("app.users.v1").unwrap()).unwrap();
let mut users = StableBTreeMap::<u64, String>::create(memory);
users.insert(1, "Alice".into());
assert_eq!(users.get(&1), Some("Alice".into()));On the IC, use DefaultMemoryImpl at the host integration boundary. In
post-upgrade, reconstruct the runtime and declarations, then load existing
collections. Stable memory holds the records; no whole-heap retention or save/load
pass is required. create requires empty allocation memory; load refuses
foreign data. reset explicitly replaces a collection and must be a host decision.
Each collection consumes a non-cloneable allocation lease. Drop every collection before reopening the same allocation. Raw backing aliases are infrastructure-only; applications must not bypass the runtime’s custody checks. Ordinary errors are not transactions; installed IC traps roll back the message. Native writes are not atomic. Upstream codec, growth and panic contracts apply.
This version replaces the experimental OP API. It is not stored-format compatible with OP or the 0.64 custom collection engines. The directory uses a new identity and refuses earlier backing. Existing deployments need an explicit migration or fresh storage; installing this crate does not authorize resetting application data.
Modules§
- adapter
- Governed collections over checked named allocations and upstream codecs. Supported upstream collections with governed memory and an explicit API.
- storable
Structs§
- Allocation
Grants - Canonical, non-overlapping namespace grants for a host composition.
- Allocation
Id - AllocationId
- Backing
Identity - BackingIdentity
- Bootstrap
Admission - Read-only recovered entries and explicit current historical admission.
- Generic
Allocation Policy - Standard policy relying on Storage’s namespace admission and resource limits.
- Memory
Allocation - MemoryAllocation
- Memory
Authority - Host grant for one owner and a dot-terminated namespace.
- Memory
Request - Checked request naming a store under one host-granted authority.
- Memory
Runtime - MemoryRuntime
- Policy
Identity - Host-selected token binding the exact configured policy to a runtime.
- Runtime
Memory - RuntimeMemory
- Sealed
Declaration Snapshot - Immutable canonical request set, with duplicate names rejected.
- Stable
Key - StableKey
- Stable
KeyError - StableKeyError
- Storage
Config - StorageConfig
Enums§
- Admission
Error - Invalid host declarations or grants; no allocation authority has been granted.
- Directory
Error - Directory validation, custody and backing failures.
- Runtime
Bootstrap Error - Bootstrap failed before current authority could be published.
- Runtime
Construction Error - Construction refuses aliased or malformed backing without resetting it.
- Runtime
Grow Error - Allocation growth failures before authority publication.
- Runtime
Open Error - A key cannot be opened until current host admission succeeds.
- Stable
Cell Payload Error - StableCellPayloadError
Constants§
- STABLE_
CELL_ HEADER_ SIZE - Stable-cell header byte length.
- WASM_
PAGE_ SIZE_ BYTES - WebAssembly stable-memory page size in bytes.
Traits§
- Memory
- Abstraction over a WebAssembly-style linear memory (e.g., stable memory).
- Memory
Backing - MemoryBacking
- Runtime
Bootstrap Policy - Host-specific recovered-state and key admission, before durable commitment.
Functions§
- stable_
cell_ payload_ length - Validate a stable-cell envelope and return its payload length.
Type Aliases§
- Default
Memory Impl - Native default backing for fixture and host integration.
- Vector
Memory - A
Memorythat is based on a vector.