canic_core/dto/pool_import/
mod.rs

1//! Passive authority and progress contracts for reviewed Root capacity import.
2
3use candid::{CandidType, Principal};
4use serde::{Deserialize, Serialize};
5
6/// Initialization hold for supplied capacity awaiting reviewed clearing and publication.
7/// The host review binds this declaration; only its exact import may release allocation.
8#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
9#[serde(deny_unknown_fields)]
10pub struct PoolImportBootstrap {
11    pub review_sha256: [u8; 32],
12    pub operator: Principal,
13    pub sources: Vec<Principal>,
14}
15
16/// Exact source identity and destructive disposition frozen before controller handoff.
17#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
18pub struct PoolImportSource {
19    pub canister_id: Principal,
20    /// Actual source custody before any optional operator handoff.
21    pub controllers: Vec<Principal>,
22    #[serde(deserialize_with = "crate::cdk::serialize::required_option")]
23    pub module_sha256: Option<[u8; 32]>,
24    pub canister_version: u64,
25    pub stopped: bool,
26    pub disposition_sha256: [u8; 32],
27    pub observed_cycles: u128,
28    pub observed_reserved_cycles: u128,
29    pub minimum_ready_cycles: u128,
30    pub maximum_debit_cycles: u128,
31}
32
33/// Exact current-Root reservation; sequence prevents replay after a later import.
34#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
35pub struct PoolImportReservation {
36    pub sequence: u64,
37    pub plan_sha256: [u8; 32],
38    pub root_authority_sha256: [u8; 32],
39    pub root: Principal,
40    pub operator: Principal,
41    pub subnet: Principal,
42    pub transitional_controllers: Vec<Principal>,
43    pub final_controllers: Vec<Principal>,
44    pub sources: Vec<PoolImportSource>,
45    pub observed_root_cycles: u128,
46    pub observed_root_reserved_cycles: u128,
47    pub minimum_root_cycles: u128,
48    pub maximum_root_debit_cycles: u128,
49    pub maximum_paid_calls: u32,
50}
51
52/// Identifies one exact retained reservation without allowing changed bounds.
53#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
54pub struct PoolImportIdentity {
55    pub sequence: u64,
56    pub plan_sha256: [u8; 32],
57}
58
59/// Exact protected evidence retained before releasing imported assets to allocation.
60#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
61pub struct PoolImportSourceReceipt {
62    pub root_sender_canister_version: u64,
63    pub canister_id: Principal,
64    pub canister_version: u64,
65    pub before_uninstall_canister_version: u64,
66    pub retained_cycles: u128,
67    pub retained_reserved_cycles: u128,
68    pub observed_debit_cycles: u128,
69}
70
71/// Protected progress for a source; issued work is reconciled, never blindly repeated.
72#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
73pub enum PoolImportSourceProgress {
74    AwaitingHandoff,
75    ControllersIssued,
76    ControllersConfirmed,
77    StopIssued,
78    Stopped,
79    UninstallIssued,
80    Ready(PoolImportSourceReceipt),
81}
82
83/// Root retains Ready evidence until the host confirms durable local publication.
84#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
85pub enum PoolImportPhase {
86    Reserved,
87    Ready,
88    Released { publication_sha256: [u8; 32] },
89}
90
91/// Controller-visible evidence for one bounded import, including original debit limits.
92#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
93pub struct PoolImportStatus {
94    pub reserved_at_ns: u64,
95    pub reservation: PoolImportReservation,
96    pub progress: Vec<PoolImportSourceProgress>,
97    pub phase: PoolImportPhase,
98    pub paid_calls: u32,
99    pub reserved_debit_cycles: u128,
100    pub last_root_cycles: u128,
101    #[serde(deserialize_with = "crate::cdk::serialize::required_option")]
102    pub root_receipt: Option<PoolImportRootReceipt>,
103}
104
105/// Protected current placement, authority and next import number used during host review.
106#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
107pub struct PoolImportContext {
108    /// Effect-free upper quote for any supported import call on this Root.
109    pub maximum_call_debit_cycles: u128,
110    pub bootstrap: Option<PoolImportBootstrap>,
111    pub binding: crate::ids::FleetSubnetRootBinding,
112    pub root_authority_sha256: [u8; 32],
113    pub next_sequence: u64,
114    pub active_import: Option<PoolImportIdentity>,
115}
116
117/// Root balance boundary observed after all source effects and paid reconciliation.
118#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
119pub struct PoolImportRootReceipt {
120    pub retained_cycles: u128,
121    pub retained_reserved_cycles: u128,
122    pub observed_debit_cycles: u128,
123}
124
125/// Authenticated operator actions for one reviewed import into the current Root.
126#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
127pub enum PoolImportCommand {
128    Advance {
129        identity: PoolImportIdentity,
130        canister_id: Principal,
131    },
132    Release {
133        identity: PoolImportIdentity,
134        publication_sha256: [u8; 32],
135    },
136    Reserve(Box<PoolImportReservation>),
137    Settle(PoolImportIdentity),
138}
canic_core/dto/pool_import/mod.rs

canic_core/dto/pool_import/
mod.rs
