Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/levifeldman/canister-tools
Canister tools for the internet-computer canisters.
https://github.com/levifeldman/canister-tools
Last synced: 5 days ago
JSON representation
Canister tools for the internet-computer canisters.
- Host: GitHub
- URL: https://github.com/levifeldman/canister-tools
- Owner: levifeldman
- License: other
- Created: 2023-06-21T04:51:00.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-05-28T17:36:50.000Z (5 months ago)
- Last Synced: 2024-10-05T19:48:48.599Z (about 1 month ago)
- Language: Rust
- Size: 906 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-internet-computer - canister-tools - Take snapshots of the canister-data and download/upload snapshots. Simple upgrades. Common tools for Rust canisters. (Developer Tooling / AssemblyScript)
README
# canister-tools
### A Rust library for canisters on the [internet-computer](https://internetcomputer.org).
Features
* Easy simple upgrade strategy.
* Canister data safety features.
* Canister methods for the manual download and upload of the global variables in the heap or stable-memory.
* Take and serialize snapshots of the canister's global variables in the heap, and then download the snapshots.
* Upload a snapshot of a canister's global variable and load it onto the canister's global variable.
The libarary works with the [virtual-memories](https://docs.rs/ic-stable-structures/0.5.6/ic_stable_structures/memory_manager/index.html) feature of the [ic-stable-structures](https://docs.rs/ic-stable-structures/0.5.6/ic_stable_structures/index.html) crate.
This way, you can store some canister data directly in a virtual-stable-memory and at the same time keep a global variable on the main heap memory that persists through upgrades.
#### Upgrade Strategy
```rust
thread_local! {
// canister global data
static DATA: RefCell = RefCell::new(Data::default());
}
// set a memory-id for the global variable
const DATA_UPGRADE_MEMORY_ID: MemoryId = MemoryId::new(0);
#[init]
fn init() {
// register the global variable with the memory-id
canister_tools::init(&DATA, DATA_UPGRADE_MEMORY_ID);
}
#[pre_upgrade]
fn pre_upgrade() {
// serialize and store the global variables into their memory-ids for the upgrade.
canister_tools::pre_upgrade();
}
#[post_upgrade]
fn post_upgrade() {
// load the data in the memory-id onto the global variable.
canister_tools::post_upgrade(&DATA, DATA_UPGRADE_MEMORY_ID, None:: Data>);
}
```
#### Download snapshots of the canister global variables, and upload snapshots onto the global variables.
This library creates the following canister methods for the state-snapshot management and stable-memory management.
```candid
type MemoryId = nat8;
type Offset = nat64;
type Length = nat64;
type StateSnapshotLength = nat64;
type WasmPages = nat64;
service : {
// Takes a snapshot of the data structure registered at the given MemoryId.
controller_create_state_snapshot : (MemoryId) -> (StateSnapshotLength);
// Download the snapshot of the data corresponding to the given MemoryId.
// Download the data in chunks.
controller_download_state_snapshot : (MemoryId, Offset, Length) -> (blob) query;
// Clears the snapshot of the data corresponding to the given MemoryId.
// When uploading data onto the data structure, call this method first to clear
// the snapshot before uploading a customized snapshot.
controller_clear_state_snapshot : (MemoryId) -> ();
// Upload the serialized data structure for the given MemoryId in chunks that can then be deserialized and loaded onto the canister global variable.
controller_append_state_snapshot : (MemoryId, blob) -> ();
// Deserializes the snapshot for the data structure corresponding to the given MemoryId
// and loads it onto the canister's global variable.
controller_load_state_snapshot : (MemoryId) -> ();
// Common stable memory functions as canister methods.
// Useful when using a custom stable-memory strategy for one or some of the MemoryIds.
controller_stable_memory_read : (MemoryId, Offset, Length) -> (blob) query;
controller_stable_memory_write : (MemoryId, Offset, blob) -> ();
controller_stable_memory_size : (MemoryId) -> (nat64) query;
controller_stable_memory_grow : (MemoryId, WasmPages) -> (int64);
}
```