ic-backup 0.3.9

ic-backup is being built to help application operators save verified copies of an Internet Computer application's data on their own computer or server, then safely restore the same canisters if something goes wrong.

On the Internet Computer, applications run in programs called canisters. Canisters can hold both application code and important data. A canister snapshot captures that state so it can be restored later. ic-backup is intended to keep an independently verified recovery copy outside the running application.

Current status: This is an early-stage Rust library, not yet a working backup application. It can securely prepare, record and verify local files and recovery plans, but it does not yet connect to the Internet Computer or perform a complete canister backup or restore.

At a glance

When might it be useful?

An Internet Computer application can consist of several related canisters, each with its own state and responsibilities. Recovering them safely involves more than downloading some files: the operator must know exactly what was captured, keep related state consistent, verify every local copy and avoid repeating an operation when its result is uncertain.

The initial recovery scope is deliberately narrow: restore the same application release into the same existing canister identities. Creation of replacement canisters, relocation, cross-release migration and automatic rollback are outside that scope.

How it is intended to work

Creating a backup

1. Select the exact network, application release and canisters to protect.
2. Build a bounded backup plan for the operator to review before anything changes.
3. Check current authority and the application's consistency requirements.
4. Safely pause or fence the selected application components when required.
5. Create snapshots and download their exact files into private local staging.
6. Verify the downloaded files, then publish a durable backup bundle without overwriting conflicting evidence.
7. Record completion and retain any remote snapshots or local files still needed by unfinished work.

Restoring a backup

1. Select and verify one complete backup bundle.
2. Confirm that it belongs to the same network, release and canister identities.
3. Build and review a separate restore plan; planning alone changes nothing.
4. Recheck current control and application safety before stopping or changing a canister.
5. Upload and load the exact retained snapshots in the application's required order.
6. Verify the restored state before allowing the application to resume normal operation.

If an operation is interrupted or a response is lost, the intended workflow keeps its original plan and evidence. It inspects what actually happened instead of assuming failure and blindly repeating a potentially expensive or destructive operation.

Safety boundaries

ic-backup is intended to own the generic backup machinery:

• exact, reviewable operation plans;
• local journals that survive interruption;
• checksums and verified backup directories;
• bounded attempts and retained uncertain outcomes;
• safe local staging, publication and retention; and
• request and reply formats for supported Internet Computer operations.

The application integration still owns information that a generic backup library cannot safely guess:

• which canisters belong to the application;
• who is currently allowed to control and inspect them;
• how the application is paused or fenced consistently;
• the correct order for application-specific operations;
• whether restored application data is valid; and
• how external payments and other effects are reconciled.

A saved plan is not current permission to act, and a downloaded file is not by itself proof of a complete backup. Authority, application consistency and the actual file contents must be checked at their appropriate boundaries.

What is implemented today

The repository currently contains one Rust library at crates/ic-backup. Its implemented foundation includes:

• checksums, secure staging and durable publication of verified local files;
• bounded local records, journal locking and interruption-safe state transitions;
• retention of backup files required by unfinished restores;
• command custody that prevents cooperating processes from assuming an external operation has stopped;
• exact canister inventories, target selection and dependency graphs;
• immutable operation plans with bounded mutation and observation attempts;
• local progress derived from the original plan and retained journals;
• typed Internet Computer request and reply encoding for selected snapshot and lifecycle operations;
• bounded snapshot metadata decoding that retains exact global values, optional timer/hook values and chunk identities without claiming complete transfer;
• metadata-bound snapshot data reads with checked ranges, exact lengths and chunk hashes, plus bounded incremental coverage checks that reject missing or repeated data without claiming durable transfer;
• local streaming of admitted snapshot bytes into private verified artifacts, with durable publication, local interruption recovery through the original journal, and explicit retained metadata/extent/chunk verification;
• source-bound snapshot upload metadata and bounded byte preparation, with a single-update provider contract and passive replies under separate pending attempts; live upload is pending;
• per-guard host timing and prepared chunk-size summaries using ic-metrics, with diagnostics kept separate from retained progress, spending and completion evidence;
• contracts for exact originally reserved IC updates and bounded passive reply association, preserving pending spending without automatic settlement;
• exact reserved status/snapshot-list observation contracts that retain both attempt identities and leave lost observations pending without automatic outcomes;
• fresh verification of durable local backup files against their original plan;
• retained same-release source/safety requirements and application evidence checks before snapshot load or controlled start;
• retained original application fence obligations and exact acquisition-journal recovery, exact application update envelopes and reserved reconciliation checks across interruption;
• immutable original execution settlement checkpoints with exact journal histories for local replay;
• immutable manifests of the exact verified local download set, with local record replay that preserves original snapshot/checksum evidence;
• fresh local restore-source verification under the original requirement, exact manifest and existing selected canister IDs; and
• private operation-bound restore artifact copies, explicit durable publication and retained-copy verification that preserve partial evidence and original obligations.

These components have native regression evidence for their local filesystem, record and process behavior. They do not establish real Internet Computer backup or restore behavior.

The following product components are still missing:

• capture and restore runners;
• an authenticated Internet Computer transport;
• the standalone command-line application;
• application-specific membership, authority and consistency adapters; and
• PocketIC and real-IC qualification of complete backup and recovery journeys.

Project boundaries

The implementation began by extracting generic backup mechanisms from Canic's canic-backup crate. Generic snapshot, artifact, planning and recovery behavior belongs here. Canic continues to own its Fleet discovery, authorization and application-consistency integration. Other applications can provide their own adapters without depending on Canic.

The proposed package layout is:

Package names and availability must be checked before publication. New packages will be added only when their implementation is required.

Development

Development uses Rust 1.99.0, edition 2024 and a minimum supported Rust version of 1.91.0. The workspace owns package metadata, dependency declarations and lints. Builds stay in this repository's target/ directory.

cargo install cargo-sort --version 2.1.4 --locked
make install-hooks
make check
make test

make help lists the available development and release commands. CI runs the native library and repository-tooling gate. PocketIC qualification will accompany platform effects when they are implemented.

Documentation

License

MIT licensed, with Canic and sibling-tooling contributor attribution retained.