Skip to main content

Crate ic_storage

Crate ic_storage 

Source
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§

AllocationGrants
Canonical, non-overlapping namespace grants for a host composition.
AllocationId
Opaque durable identity assigned by the directory. It grants no access.
BackingIdentity
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.
BootstrapAdmission
Read-only recovered entries and explicit current historical admission.
GenericAllocationPolicy
Standard policy relying on Storage’s namespace admission and resource limits.
MemoryAllocation
Passive diagnostic entry; no lease or allocation authority is carried.
MemoryAuthority
Host grant for one owner and a dot-terminated namespace.
MemoryRequest
Checked request naming a store under one host-granted authority.
MemoryRuntime
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.
PolicyIdentity
Host-selected token binding the exact configured policy to a runtime.
RuntimeMemory
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.
SealedDeclarationSnapshot
Immutable canonical request set, with duplicate names rejected.
StableKey
Canonical durable logical allocation identity.
StableKeyError
Stable-key grammar validation failure.
StorageConfig
Resource ceilings checked when creating, opening and extending the directory. Physical page accounting includes retained metadata and abandoned tails.

Enums§

AdmissionError
Invalid host declarations or grants; no allocation authority has been granted.
DirectoryError
Directory validation, custody and backing failures.
RuntimeBootstrapError
Bootstrap failed before current authority could be published.
RuntimeConstructionError
Construction refuses aliased or malformed backing without resetting it.
RuntimeGrowError
Allocation growth failures before authority publication.
RuntimeOpenError
A key cannot be opened until current host admission succeeds.
StableCellPayloadError
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).
MemoryBacking
Host boundary for a backing whose aliases can be identified consistently.
RuntimeBootstrapPolicy
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§

DefaultMemoryImpl
Native default backing for fixture and host integration.
VectorMemory
A Memory that is based on a vector.