canic-core 0.110.43

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Passive authority and progress contracts for reviewed Root capacity import.

use candid::{CandidType, Principal};
use serde::{Deserialize, Serialize};

/// Initialization hold for supplied capacity that Root does not yet control.
/// The host review binds this declaration; only its exact import may release allocation.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PoolImportBootstrap {
    pub review_sha256: [u8; 32],
    pub operator: Principal,
    pub sources: Vec<Principal>,
}

/// Exact source identity and destructive disposition frozen before controller handoff.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportSource {
    pub canister_id: Principal,
    #[serde(deserialize_with = "crate::cdk::serialize::required_option")]
    pub module_sha256: Option<[u8; 32]>,
    pub canister_version: u64,
    pub stopped: bool,
    pub disposition_sha256: [u8; 32],
    pub observed_cycles: u128,
    pub observed_reserved_cycles: u128,
    pub minimum_ready_cycles: u128,
    pub maximum_debit_cycles: u128,
}

/// Exact current-Root reservation; sequence prevents replay after a later import.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportReservation {
    pub sequence: u64,
    pub plan_sha256: [u8; 32],
    pub root_authority_sha256: [u8; 32],
    pub root: Principal,
    pub operator: Principal,
    pub subnet: Principal,
    pub transitional_controllers: Vec<Principal>,
    pub final_controllers: Vec<Principal>,
    pub sources: Vec<PoolImportSource>,
    pub observed_root_cycles: u128,
    pub observed_root_reserved_cycles: u128,
    pub minimum_root_cycles: u128,
    pub maximum_root_debit_cycles: u128,
    pub maximum_paid_calls: u32,
}

/// Identifies one exact retained reservation without allowing changed bounds.
#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportIdentity {
    pub sequence: u64,
    pub plan_sha256: [u8; 32],
}

/// Exact protected evidence retained before releasing imported assets to allocation.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportSourceReceipt {
    pub root_sender_canister_version: u64,
    pub canister_id: Principal,
    pub canister_version: u64,
    pub retained_cycles: u128,
    pub retained_reserved_cycles: u128,
    pub observed_debit_cycles: u128,
}

/// Protected progress for a source; issued work is reconciled, never blindly repeated.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub enum PoolImportSourceProgress {
    AwaitingHandoff,
    ControllersIssued,
    ControllersConfirmed,
    UninstallIssued,
    Ready(PoolImportSourceReceipt),
}

/// Root retains Ready evidence until the host confirms durable local publication.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub enum PoolImportPhase {
    Reserved,
    Ready,
    Released { publication_sha256: [u8; 32] },
}

/// Controller-visible evidence for one bounded import, including original debit limits.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportStatus {
    pub reserved_at_ns: u64,
    pub reservation: PoolImportReservation,
    pub progress: Vec<PoolImportSourceProgress>,
    pub phase: PoolImportPhase,
    pub paid_calls: u32,
    pub reserved_debit_cycles: u128,
    pub last_root_cycles: u128,
    #[serde(deserialize_with = "crate::cdk::serialize::required_option")]
    pub root_receipt: Option<PoolImportRootReceipt>,
}

/// Protected current placement, authority and next import number used during host review.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub struct PoolImportContext {
    pub bootstrap: Option<PoolImportBootstrap>,
    pub binding: crate::ids::FleetSubnetRootBinding,
    pub root_authority_sha256: [u8; 32],
    pub next_sequence: u64,
    pub active_import: Option<PoolImportIdentity>,
}

/// Root balance boundary observed after all source effects and paid reconciliation.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PoolImportRootReceipt {
    pub retained_cycles: u128,
    pub retained_reserved_cycles: u128,
    pub observed_debit_cycles: u128,
}

/// Authenticated operator actions for one reviewed import into the current Root.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub enum PoolImportCommand {
    Advance {
        identity: PoolImportIdentity,
        canister_id: Principal,
    },
    Release {
        identity: PoolImportIdentity,
        publication_sha256: [u8; 32],
    },
    Reserve(Box<PoolImportReservation>),
    Settle(PoolImportIdentity),
}