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 - Opaque durable identity assigned by the directory. It grants no access.
- Backing
Identity - Identity of a physical backing allocation, shared by all of its wrappers. This is host custody metadata, not a virtual memory ID or durable record.
- 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 - Passive diagnostic entry; no lease or allocation authority is carried.
- 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 - One custodian of named allocations on a backing. Bootstrap validates namespace grants and host policy, commits bindings, then permits exclusive leases. Omitted retained names keep their allocation, but require current admission before opening. IDs are opaque u64 values, never selected by applications.
- Policy
Identity - Host-selected token binding the exact configured policy to a runtime.
- Runtime
Memory - Exclusive non-cloneable allocation lease. IO trusts custody between checked boundaries; growth commits the directory before publishing its new extent. A detached lease retains the backing claim until it is dropped.
- Sealed
Declaration Snapshot - Immutable canonical request set, with duplicate names rejected.
- Stable
Key - Canonical durable logical allocation identity.
- Stable
KeyError - Stable-key grammar validation failure.
- Storage
Config - Resource ceilings checked when creating, opening and extending the directory. Physical page accounting includes retained metadata and abandoned tails.
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 - Stable-cell payload decode failure.
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 - Host boundary for a backing whose aliases can be identified consistently.
- 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.