{"id":13523835,"url":"https://github.com/levifeldman/canister-tools","last_synced_at":"2025-04-01T01:33:35.206Z","repository":{"id":182976470,"uuid":"656503813","full_name":"levifeldman/canister-tools","owner":"levifeldman","description":"Canister tools for the internet-computer canisters.","archived":false,"fork":false,"pushed_at":"2024-05-28T17:36:50.000Z","size":928,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-05T19:48:48.599Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/levifeldman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-21T04:51:00.000Z","updated_at":"2024-06-18T23:51:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"c990d99f-cd58-4172-9349-b4f0f7afb8ba","html_url":"https://github.com/levifeldman/canister-tools","commit_stats":null,"previous_names":["levifeldman/canister-tools"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levifeldman%2Fcanister-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levifeldman%2Fcanister-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levifeldman%2Fcanister-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levifeldman%2Fcanister-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/levifeldman","download_url":"https://codeload.github.com/levifeldman/canister-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222693040,"owners_count":17024034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:04.180Z","updated_at":"2024-11-02T08:31:00.073Z","avatar_url":"https://github.com/levifeldman.png","language":"Rust","funding_links":[],"categories":["Developer Tooling"],"sub_categories":["Moonbit"],"readme":"#  canister-tools\n\n### A Rust library for canisters on the [internet-computer](https://internetcomputer.org).\n\nFeatures\n* Easy simple upgrade strategy.\n* Canister data safety features.\n* Canister methods for the manual download and upload of the global variables in the heap or stable-memory.\n* Take and serialize snapshots of the canister's global variables in the heap, and then download the snapshots.\n* Upload a snapshot of a canister's global variable and load it onto the canister's global variable.\n\nThe 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. \nThis 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. \n\n\n#### Upgrade Strategy\n```rust\nthread_local! {\n    // canister global data\n    static DATA: RefCell\u003cData\u003e = RefCell::new(Data::default());\n}\n  \n// set a memory-id for the global variable \nconst DATA_UPGRADE_MEMORY_ID: MemoryId = MemoryId::new(0);\n  \n#[init]\nfn init() {\n    // register the global variable with the memory-id\n    canister_tools::init(\u0026DATA, DATA_UPGRADE_MEMORY_ID);\n}  \n  \n#[pre_upgrade]\nfn pre_upgrade() {\n    // serialize and store the global variables into their memory-ids for the upgrade. \n    canister_tools::pre_upgrade();\n}\n\n#[post_upgrade]\nfn post_upgrade() {\n    // load the data in the memory-id onto the global variable.\n    canister_tools::post_upgrade(\u0026DATA, DATA_UPGRADE_MEMORY_ID, None::\u003cfn(OldData) -\u003e Data\u003e);\n}\n\n  \n  \n  \n```\n\n\n\n#### Download snapshots of the canister global variables, and upload snapshots onto the global variables. \nThis library creates the following canister methods for the state-snapshot management and stable-memory management. \n```candid    \ntype MemoryId = nat8;\ntype Offset = nat64;\ntype Length = nat64;\ntype StateSnapshotLength = nat64;\ntype WasmPages = nat64;\n\nservice : {\n    // Takes a snapshot of the data structure registered at the given MemoryId.\n    controller_create_state_snapshot : (MemoryId) -\u003e (StateSnapshotLength);\n    \n    // Download the snapshot of the data corresponding to the given MemoryId.\n    // Download the data in chunks.\n    controller_download_state_snapshot : (MemoryId, Offset, Length) -\u003e (blob) query;\n    \n    // Clears the snapshot of the data corresponding to the given MemoryId.\n    // When uploading data onto the data structure, call this method first to clear\n    // the snapshot before uploading a customized snapshot.\n    controller_clear_state_snapshot : (MemoryId) -\u003e ();\n    \n    // Upload the serialized data structure for the given MemoryId in chunks that can then be deserialized and loaded onto the canister global variable.   \n    controller_append_state_snapshot : (MemoryId, blob) -\u003e ();\n    \n    // Deserializes the snapshot for the data structure corresponding to the given MemoryId\n    // and loads it onto the canister's global variable.\n    controller_load_state_snapshot : (MemoryId) -\u003e ();\n\n    // Common stable memory functions as canister methods.\n    // Useful when using a custom stable-memory strategy for one or some of the MemoryIds. \n    controller_stable_memory_read : (MemoryId, Offset, Length) -\u003e (blob) query;\n    controller_stable_memory_write : (MemoryId, Offset, blob) -\u003e ();\n    controller_stable_memory_size : (MemoryId) -\u003e (nat64) query;\n    controller_stable_memory_grow : (MemoryId, WasmPages) -\u003e (int64);\n}\n```\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevifeldman%2Fcanister-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevifeldman%2Fcanister-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevifeldman%2Fcanister-tools/lists"}