ic_management_canister_types/
lib.rs

1#![doc = include_str!("../README.md")]
2
3use candid::{CandidType, Nat, Principal, Reserved};
4use serde::{Deserialize, Serialize};
5
6/// # Canister ID.
7pub type CanisterId = Principal;
8
9/// # Canister ID Record
10///
11/// A record containing only a `canister_id` field.
12///
13/// The argument or result type of various Management Canister methods are aliases of this type.
14#[derive(
15    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
16)]
17pub struct CanisterIdRecord {
18    /// Canister ID.
19    pub canister_id: CanisterId,
20}
21
22/// # Chunk hash.
23#[derive(
24    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
25)]
26pub struct ChunkHash {
27    /// The hash of an uploaded chunk
28    #[serde(with = "serde_bytes")]
29    pub hash: Vec<u8>,
30}
31
32/// # Log Visibility.
33#[derive(
34    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
35)]
36pub enum LogVisibility {
37    /// Controllers.
38    #[default]
39    #[serde(rename = "controllers")]
40    Controllers,
41    /// Public.
42    #[serde(rename = "public")]
43    Public,
44    /// Allowed viewers.
45    #[serde(rename = "allowed_viewers")]
46    AllowedViewers(Vec<Principal>),
47}
48
49/// # Environment Variable.
50#[derive(
51    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
52)]
53pub struct EnvironmentVariable {
54    /// Name of the environment variable.
55    pub name: String,
56    /// Value of the environment variable.
57    pub value: String,
58}
59
60/// # Canister Settings
61///
62/// For arguments of [`create_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-create_canister),
63/// [`update_settings`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-update_settings) and
64/// [`provisional_create_canister_with_cycles`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-provisional_create_canister_with_cycles).
65///
66/// All fields are `Option` types, allowing selective settings/updates.
67#[derive(
68    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
69)]
70pub struct CanisterSettings {
71    /// A list of at most 10 principals.
72    ///
73    /// The principals in this list become the *controllers* of the canister.
74    ///
75    /// Default value: A list containing only the caller of the `create_canister` call.
76    pub controllers: Option<Vec<Principal>>,
77    /// Indicates how much compute power should be guaranteed to this canister,
78    /// expressed as a percentage of the maximum compute power that a single canister can allocate.
79    ///
80    /// If the IC cannot provide the requested allocation,
81    /// for example because it is oversubscribed, the call will be **rejected**.
82    ///
83    /// Must be a number between 0 and 100, inclusively.
84    ///
85    /// Default value: `0`
86    pub compute_allocation: Option<Nat>,
87    /// Indicates how much memory (bytes) the canister is allowed to use in total.
88    ///
89    /// If the IC cannot provide the requested allocation,
90    /// for example because it is oversubscribed, the call will be **rejected**.
91    ///
92    /// If set to 0, then memory growth of the canister will be best-effort and subject to the available memory on the IC.
93    ///
94    /// Must be a number between 0 and 2<sup>48</sup> (i.e 256TB), inclusively.
95    ///
96    /// Default value: `0`
97    pub memory_allocation: Option<Nat>,
98    /// Indicates a length of time in seconds.
99    /// A canister is considered frozen whenever the IC estimates that the canister would be depleted of cycles
100    /// before `freezing_threshold` seconds pass, given the canister's current size and the IC's current cost for storage.
101    ///
102    /// Must be a number between 0 and 2<sup>64</sup>-1, inclusively.
103    ///
104    /// Default value: `2_592_000` (approximately 30 days).
105    pub freezing_threshold: Option<Nat>,
106    /// Indicates the upper limit on [`CanisterStatusResult::reserved_cycles`] of the canister.
107    ///
108    /// Must be a number between 0 and 2<sup>128</sup>-1, inclusively.
109    ///
110    /// Default value: `5_000_000_000_000` (5 trillion cycles).
111    pub reserved_cycles_limit: Option<Nat>,
112    /// Defines who is allowed to read the canister's logs.
113    ///
114    /// Default value: [`LogVisibility::Controllers`].
115    pub log_visibility: Option<LogVisibility>,
116    /// Indicates the upper limit on the WASM heap memory (bytes) consumption of the canister.
117    ///
118    /// Must be a number between 0 and 2<sup>48</sup>-1 (i.e 256TB), inclusively.
119    ///
120    /// Default value: `3_221_225_472` (3 GiB).
121    pub wasm_memory_limit: Option<Nat>,
122    /// Indicates the threshold on the remaining wasm memory size of the canister in bytes.
123    ///
124    /// If the remaining wasm memory size of the canister is below the threshold, execution of the "on low wasm memory" hook is scheduled.
125    ///
126    /// Must be a number between 0 and 2<sup>64</sup>-1, inclusively.
127    ///
128    /// Default value: `0` (i.e., the "on low wasm memory" hook is never scheduled).
129    pub wasm_memory_threshold: Option<Nat>,
130
131    /// A list of environment variables.
132    ///
133    /// These variables are accessible to the canister during execution
134    /// and can be used to configure canister behavior without code changes.
135    /// Each key must be unique.
136    ///
137    /// Default value: `null` (i.e., no environment variables provided).
138    pub environment_variables: Option<Vec<EnvironmentVariable>>,
139}
140
141/// # Definite Canister Settings
142///
143/// Represents the actual settings in effect.
144///
145/// For return of [`canister_status`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_status).
146#[derive(
147    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
148)]
149pub struct DefiniteCanisterSettings {
150    /// Controllers of the canister.
151    pub controllers: Vec<Principal>,
152    /// Guaranteed compute allocation as a percentage of the maximum compute power that a single canister can allocate.
153    pub compute_allocation: Nat,
154    /// Total memory (bytes) the canister is allowed to use.
155    pub memory_allocation: Nat,
156    /// Time in seconds after which the canister is considered frozen.
157    pub freezing_threshold: Nat,
158    /// Upper limit on [`CanisterStatusResult::reserved_cycles`] of the canister.
159    pub reserved_cycles_limit: Nat,
160    /// Visibility of canister logs.
161    pub log_visibility: LogVisibility,
162    /// Upper limit on the WASM heap memory (bytes) consumption of the canister.
163    pub wasm_memory_limit: Nat,
164    /// Threshold on the remaining wasm memory size of the canister in bytes.
165    pub wasm_memory_threshold: Nat,
166    /// A list of environment variables.
167    pub environment_variables: Vec<EnvironmentVariable>,
168}
169
170/// # Create Canister Args
171///
172/// Argument type of [`create_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-create_canister).
173#[derive(
174    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
175)]
176pub struct CreateCanisterArgs {
177    /// Canister settings.
178    pub settings: Option<CanisterSettings>,
179    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
180    pub sender_canister_version: Option<u64>,
181}
182
183/// # Create Canister Result
184///
185/// Result type of [`create_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-create_canister).
186pub type CreateCanisterResult = CanisterIdRecord;
187
188/// # Update Settings Args
189///
190/// Argument type of [`update_settings`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-update_settings).
191#[derive(
192    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
193)]
194pub struct UpdateSettingsArgs {
195    /// Canister ID of the canister whose settings are to be updated.
196    pub canister_id: CanisterId,
197    ///Canister settings.
198    pub settings: CanisterSettings,
199    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
200    pub sender_canister_version: Option<u64>,
201}
202
203/// # Upload Chunk Args
204///
205/// Argument type of [`upload_chunk`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-upload_chunk).
206#[derive(
207    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
208)]
209pub struct UploadChunkArgs {
210    /// The canister whose chunk store the chunk will be uploaded to.
211    pub canister_id: CanisterId,
212    /// The chunk bytes (max size 1MB).
213    #[serde(with = "serde_bytes")]
214    pub chunk: Vec<u8>,
215}
216
217/// # Upload Chunk Result
218///
219/// Result type of [`upload_chunk`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-upload_chunk).
220pub type UploadChunkResult = ChunkHash;
221
222/// # Clear Chunk Store Args
223///
224/// Argument type of [`clear_chunk_store`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-clear_chunk_store).
225pub type ClearChunkStoreArgs = CanisterIdRecord;
226
227/// # Stored Chunks Args
228///
229/// Argument type of [`stored_chunks`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-stored_chunks).
230pub type StoredChunksArgs = CanisterIdRecord;
231
232/// # Stored Chunks Result
233///
234/// Result type of [`stored_chunks`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-stored_chunks).
235pub type StoredChunksResult = Vec<ChunkHash>;
236
237/// # Canister Install Mode
238///
239/// See [`InstallCodeArgs`].
240#[derive(
241    CandidType,
242    Serialize,
243    Deserialize,
244    Debug,
245    PartialEq,
246    Eq,
247    PartialOrd,
248    Ord,
249    Hash,
250    Clone,
251    Copy,
252    Default,
253)]
254pub enum CanisterInstallMode {
255    /// A fresh install of a new canister.
256    #[default]
257    #[serde(rename = "install")]
258    Install,
259    /// Reinstalling a canister that was already installed.
260    #[serde(rename = "reinstall")]
261    Reinstall,
262    /// Upgrade an existing canister.
263    #[serde(rename = "upgrade")]
264    Upgrade(Option<UpgradeFlags>),
265}
266
267/// # Upgrade Flags
268///
269/// See [`CanisterInstallMode::Upgrade`].
270#[derive(
271    CandidType,
272    Serialize,
273    Deserialize,
274    Debug,
275    PartialEq,
276    Eq,
277    PartialOrd,
278    Ord,
279    Hash,
280    Clone,
281    Copy,
282    Default,
283)]
284pub struct UpgradeFlags {
285    /// If set to `true`, the `pre_upgrade` step will be skipped during the canister upgrade.
286    pub skip_pre_upgrade: Option<bool>,
287    /// If set to [`WasmMemoryPersistence::Keep`], the WASM heap memory will be preserved instead of cleared.
288    pub wasm_memory_persistence: Option<WasmMemoryPersistence>,
289}
290
291/// # Wasm Memory Persistence
292///
293/// See [`UpgradeFlags::wasm_memory_persistence`].
294#[derive(
295    CandidType,
296    Serialize,
297    Deserialize,
298    Debug,
299    PartialEq,
300    Eq,
301    PartialOrd,
302    Ord,
303    Hash,
304    Clone,
305    Copy,
306    Default,
307)]
308pub enum WasmMemoryPersistence {
309    /// Preserve heap memory.
310    #[serde(rename = "keep")]
311    Keep,
312    /// Clear heap memory.
313    #[default]
314    #[serde(rename = "replace")]
315    Replace,
316}
317
318/// # WASM Module
319pub type WasmModule = Vec<u8>;
320
321/// # Install Code Args
322///
323/// Argument type of [`install_code`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-install_code).
324#[derive(
325    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
326)]
327pub struct InstallCodeArgs {
328    /// Canister install mode.
329    pub mode: CanisterInstallMode,
330    /// Canister ID.
331    pub canister_id: CanisterId,
332    /// Code to be installed.
333    pub wasm_module: WasmModule,
334    /// The argument to be passed to `canister_init` or `canister_post_upgrade`.
335    #[serde(with = "serde_bytes")]
336    pub arg: Vec<u8>,
337    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
338    pub sender_canister_version: Option<u64>,
339}
340
341/// # Install Chunked Code Args
342///
343/// Argument type of [`install_chunked_code`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-install_chunked_code).
344#[derive(
345    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
346)]
347pub struct InstallChunkedCodeArgs {
348    /// Canister install mode.
349    pub mode: CanisterInstallMode,
350    /// Principal of the canister being installed.
351    pub target_canister: CanisterId,
352    /// The canister in whose chunk storage the chunks are stored (defaults to `target_canister` if not specified).
353    pub store_canister: Option<CanisterId>,
354    /// The list of chunks that make up the canister wasm.
355    pub chunk_hashes_list: Vec<ChunkHash>,
356    /// The sha256 hash of the wasm.
357    #[serde(with = "serde_bytes")]
358    pub wasm_module_hash: Vec<u8>,
359    /// The argument to be passed to `canister_init` or `canister_post_upgrade`.
360    #[serde(with = "serde_bytes")]
361    pub arg: Vec<u8>,
362    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
363    pub sender_canister_version: Option<u64>,
364}
365
366/// # Uninstall Code Args
367///
368/// Argument type of [`uninstall_code`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-uninstall_code).
369#[derive(
370    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
371)]
372pub struct UninstallCodeArgs {
373    /// Canister ID.
374    pub canister_id: CanisterId,
375    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
376    pub sender_canister_version: Option<u64>,
377}
378
379/// # Start Canister Args
380///
381/// Argument type of [`start_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-start_canister).
382pub type StartCanisterArgs = CanisterIdRecord;
383
384/// # Stop Canister Args
385///
386/// Argument type of [`stop_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-stop_canister).
387pub type StopCanisterArgs = CanisterIdRecord;
388
389/// # Canister Status Args
390///
391/// Argument type of [`canister_status`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_status).
392pub type CanisterStatusArgs = CanisterIdRecord;
393
394/// # Canister Status Result
395///
396/// Result type of [`canister_status`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_status).
397#[derive(
398    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
399)]
400pub struct CanisterStatusResult {
401    /// Status of the canister.
402    pub status: CanisterStatusType,
403    /// Indicates whether a stopped canister is ready to be migrated to another subnet
404    /// (i.e., whether it has empty queues and flushed streams).
405    pub ready_for_migration: bool,
406    /// The canister version.
407    pub version: u64,
408    /// Canister settings in effect.
409    pub settings: DefiniteCanisterSettings,
410    /// A SHA256 hash of the module installed on the canister. This is null if the canister is empty.
411    pub module_hash: Option<Vec<u8>>,
412    /// The memory size taken by the canister.
413    pub memory_size: Nat,
414    /// The detailed metrics on the memory consumption of the canister.
415    pub memory_metrics: MemoryMetrics,
416    /// The cycle balance of the canister.
417    pub cycles: Nat,
418    /// The reserved cycles balance of the canister.
419    ///
420    /// These are cycles that are reserved by the resource reservation mechanism on storage allocation.
421    /// See also the [`CanisterSettings::reserved_cycles_limit`] parameter in canister settings.
422    pub reserved_cycles: Nat,
423    /// Amount of cycles burned per day.
424    pub idle_cycles_burned_per_day: Nat,
425    /// Query statistics.
426    pub query_stats: QueryStats,
427}
428
429/// # Canister Status Type
430///
431/// Status of a canister.
432///
433/// See [`CanisterStatusResult::status`].
434#[derive(
435    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy,
436)]
437pub enum CanisterStatusType {
438    /// The canister is running.
439    #[serde(rename = "running")]
440    Running,
441    /// The canister is stopping.
442    #[serde(rename = "stopping")]
443    Stopping,
444    /// The canister is stopped.
445    #[serde(rename = "stopped")]
446    Stopped,
447}
448
449/// # Memory Metrics
450///
451/// Memory metrics of a canister.
452///
453/// See [`CanisterStatusResult::memory_metrics`].
454#[derive(
455    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
456)]
457pub struct MemoryMetrics {
458    /// Represents the Wasm memory usage of the canister, i.e. the heap memory used by the canister's WebAssembly code.
459    pub wasm_memory_size: Nat,
460    /// Represents the stable memory usage of the canister.
461    pub stable_memory_size: Nat,
462    /// Represents the memory usage of the global variables that the canister is using.
463    pub global_memory_size: Nat,
464    /// Represents the memory occupied by the Wasm binary that is currently installed on the canister.
465    pub wasm_binary_size: Nat,
466    /// Represents the memory used by custom sections defined by the canister.
467    pub custom_sections_size: Nat,
468    /// Represents the memory used for storing the canister's history.
469    pub canister_history_size: Nat,
470    /// Represents the memory used by the Wasm chunk store of the canister.
471    pub wasm_chunk_store_size: Nat,
472    /// Represents the memory consumed by all snapshots that belong to this canister.
473    pub snapshots_size: Nat,
474}
475
476/// # Query Stats
477///
478/// Query statistics.
479///
480/// See [`CanisterStatusResult::query_stats`].
481#[derive(
482    CandidType, Clone, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize,
483)]
484pub struct QueryStats {
485    /// Total number of query calls.
486    pub num_calls_total: Nat,
487    /// Total number of instructions executed by query calls.
488    pub num_instructions_total: Nat,
489    /// Total number of payload bytes use for query call requests.
490    pub request_payload_bytes_total: Nat,
491    /// Total number of payload bytes use for query call responses.
492    pub response_payload_bytes_total: Nat,
493}
494
495/// # Canister Info Args
496///
497/// Argument type of [`canister_info`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_info).
498#[derive(
499    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
500)]
501pub struct CanisterInfoArgs {
502    /// Canister ID.
503    pub canister_id: Principal,
504    /// Number of most recent changes requested to be retrieved from canister history.
505    /// No changes are retrieved if this field is null.
506    pub num_requested_changes: Option<u64>,
507}
508
509/// # Canister Info Result
510///
511/// Result type of [`canister_info`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_info).
512#[derive(
513    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
514)]
515pub struct CanisterInfoResult {
516    /// Total number of changes ever recorded in canister history.
517    ///
518    /// This might be higher than the number of canister changes in `recent_changes`
519    /// because the IC might drop old canister changes from its history
520    /// (with `20` most recent canister changes to always remain in the list).
521    pub total_num_changes: u64,
522    /// The canister changes stored in the order from the oldest to the most recent.
523    pub recent_changes: Vec<Change>,
524    /// A SHA256 hash of the module installed on the canister. This is null if the canister is empty.
525    pub module_hash: Option<Vec<u8>>,
526    /// Controllers of the canister.
527    pub controllers: Vec<Principal>,
528}
529
530/// # Canister Metadata Args
531///
532/// Argument type of [`canister_metadata`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_metadata).
533#[derive(
534    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
535)]
536pub struct CanisterMetadataArgs {
537    /// Canister ID.
538    pub canister_id: Principal,
539    /// Identifies canister's metadata contained in a custom section whose name has the form
540    /// `icp:public <name>` or `icp:private <name>`.
541    pub name: String,
542}
543
544/// # Canister Metadata Result
545///
546/// Result type of [`canister_metadata`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-canister_metadata).
547#[derive(
548    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
549)]
550pub struct CanisterMetadataResult {
551    /// The content of canister's metadata identified by the given `name`.
552    #[serde(with = "serde_bytes")]
553    pub value: Vec<u8>,
554}
555
556/// # From User Record
557///
558/// Details about a canister change initiated by a user.
559///
560/// See [`ChangeOrigin::FromUser`].
561#[derive(
562    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
563)]
564pub struct FromUserRecord {
565    /// Principal of the user.
566    pub user_id: Principal,
567}
568
569/// # From Canister Record
570///
571/// Details about a canister change initiated by a canister (called _originator_).
572///
573/// See [`ChangeOrigin::FromCanister`].
574#[derive(
575    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
576)]
577pub struct FromCanisterRecord {
578    /// Canister ID of the _originator_.
579    pub canister_id: Principal,
580    /// Canister version of the _originator_ when the _originator_ initiated the change.
581    ///
582    /// This is null if the original does not include its canister version
583    /// in the field `sender_canister_version` of the management canister payload.
584    pub canister_version: Option<u64>,
585}
586
587/// # Change Origin
588///
589/// Provides details on who initiated a canister change.
590///
591/// See [`Change::origin`].
592#[derive(
593    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
594)]
595pub enum ChangeOrigin {
596    /// The change was initiated by a user.
597    #[serde(rename = "from_user")]
598    FromUser(FromUserRecord),
599    /// The change was initiated by a canister.
600    #[serde(rename = "from_canister")]
601    FromCanister(FromCanisterRecord),
602}
603
604/// # Creation Record
605///
606/// Details about a canister creation.
607///
608/// See [`ChangeDetails::Creation`].
609#[derive(
610    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
611)]
612pub struct CreationRecord {
613    /// Initial set of canister controllers.
614    pub controllers: Vec<Principal>,
615    /// Hash of the environment variables.
616    pub environment_variables_hash: Option<Vec<u8>>,
617}
618
619/// # Code Deployment Mode
620///
621/// The mode with which a canister is installed.
622///
623/// See [`CodeDeploymentRecord::mode`].
624#[derive(
625    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy,
626)]
627pub enum CodeDeploymentMode {
628    /// A fresh install of a new canister.
629    #[serde(rename = "install")]
630    Install,
631    /// Reinstalling a canister that was already installed.
632    #[serde(rename = "reinstall")]
633    Reinstall,
634    /// Upgrade an existing canister.
635    #[serde(rename = "upgrade")]
636    Upgrade,
637}
638
639/// # Code Deployment Record
640///
641/// Details about a canister code deployment.
642///
643/// See [`ChangeDetails::CodeDeployment`].
644#[derive(
645    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
646)]
647pub struct CodeDeploymentRecord {
648    /// Deployment mode.
649    pub mode: CodeDeploymentMode,
650    /// A SHA256 hash of the new module installed on the canister.
651    #[serde(with = "serde_bytes")]
652    pub module_hash: Vec<u8>,
653}
654
655/// # Load Snapshot Record
656///
657/// Details about loading canister snapshot.
658///
659/// See [`ChangeDetails::LoadSnapshot`].
660#[derive(
661    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
662)]
663pub struct LoadSnapshotRecord {
664    /// The canister ID of the canister from which the snapshot was loaded
665    /// (if that canister ID is different than the canister ID onto which the snapshot is loaded).
666    pub from_canister_id: Option<Principal>,
667    /// The ID of the snapshot that was loaded.
668    pub snapshot_id: SnapshotId,
669    /// The version of the canister at the time that the snapshot was taken.
670    pub canister_version: u64,
671    /// The timestamp at which the snapshot was taken.
672    pub taken_at_timestamp: u64,
673    /// The source from which the snapshot was taken.
674    pub source: SnapshotSource,
675}
676
677/// # Rename To Record
678///
679/// Details about the new canister ID in a rename operation.
680///
681/// Contains the canister ID, version, and total number of changes of the new canister ID.
682/// After renaming, the total number of canister changes reported by the IC method `canister_info`
683/// is overridden to this value.
684///
685/// See [`RenameCanisterRecord::rename_to`].
686#[derive(
687    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
688)]
689pub struct RenameToRecord {
690    /// The new canister ID.
691    pub canister_id: Principal,
692    /// The version of the new canister.
693    pub version: u64,
694    /// The total number of changes in the new canister's history.
695    /// This value overrides the total reported by `canister_info` after renaming.
696    pub total_num_changes: u64,
697}
698
699/// # Rename Canister Record
700///
701/// Details about a canister rename operation.
702///
703/// Canister renaming is described by the canister ID and the total number of canister changes
704/// before renaming as well as the canister ID, version, and total number of changes of the new
705/// canister ID. Because only a dedicated NNS canister can perform canister renaming, the actual
706/// principal who requested canister renaming is recorded in the [`requested_by`](Self::requested_by) field.
707///
708/// After renaming, the total number of canister changes reported by the IC method `canister_info`
709/// is overridden to the total number of canister changes of the new canister ID. Canister changes
710/// referring to the canister ID before renaming are preserved.
711///
712/// See [`ChangeDetails::RenameCanister`].
713#[derive(
714    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
715)]
716pub struct RenameCanisterRecord {
717    /// The canister ID before renaming.
718    pub canister_id: Principal,
719    /// The total number of changes in the canister's history before renaming.
720    pub total_num_changes: u64,
721    /// Details about the new canister ID after renaming.
722    pub rename_to: RenameToRecord,
723    /// The principal that requested the rename operation.
724    ///
725    /// Because only a dedicated NNS canister can perform canister renaming,
726    /// this field records the actual principal who requested it.
727    pub requested_by: Principal,
728}
729
730/// # Controllers Change Record
731///
732/// Details about updating canister controllers.
733///
734/// See [`ChangeDetails::ControllersChange`].
735#[derive(
736    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
737)]
738pub struct ControllersChangeRecord {
739    /// The complete new set of canister controllers.
740    pub controllers: Vec<Principal>,
741}
742
743/// # Change Details
744///
745/// Provides details on the respective canister change.
746///
747/// See [`Change::details`].
748#[derive(
749    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
750)]
751pub enum ChangeDetails {
752    /// The change was canister creation.
753    #[serde(rename = "creation")]
754    Creation(CreationRecord),
755    /// The change was canister uninstallation.
756    #[serde(rename = "code_uninstall")]
757    CodeUninstall,
758    /// The change was canister code deployment.
759    #[serde(rename = "code_deployment")]
760    CodeDeployment(CodeDeploymentRecord),
761    /// The change was loading a canister snapshot.
762    #[serde(rename = "load_snapshot")]
763    LoadSnapshot(LoadSnapshotRecord),
764    /// The change was updating canister controllers.
765    #[serde(rename = "controllers_change")]
766    ControllersChange(ControllersChangeRecord),
767    /// The change was renaming a canister.
768    #[serde(rename = "rename_canister")]
769    RenameCanister(RenameCanisterRecord),
770}
771
772/// # Change
773///
774/// Represents a canister change as stored in the canister history.
775#[derive(
776    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
777)]
778pub struct Change {
779    /// The system timestamp (in nanoseconds since Unix Epoch) at which the change was performed.
780    pub timestamp_nanos: u64,
781    /// The canister version after performing the change.
782    pub canister_version: u64,
783    /// The change's origin (a user or a canister).
784    pub origin: ChangeOrigin,
785    /// The change's details.
786    pub details: Option<ChangeDetails>,
787}
788
789/// # Delete Canister Args
790///
791/// Argument type of [`delete_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-delete_canister).
792pub type DeleteCanisterArgs = CanisterIdRecord;
793
794/// # Deposit Cycles Args
795///
796/// Argument type of [`deposit_cycles`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-deposit_cycles).
797pub type DepositCyclesArgs = CanisterIdRecord;
798
799/// # Raw Rand Result
800///
801/// Result type of [`raw_rand`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-raw_rand).
802pub type RawRandResult = Vec<u8>;
803
804/// # HTTP Request Args
805///
806/// Argument type of [`http_request`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-http_request).
807#[derive(CandidType, Deserialize, Debug, PartialEq, Eq, Clone, Default)]
808pub struct HttpRequestArgs {
809    /// The requested URL.
810    pub url: String,
811    /// The maximal size of the response in bytes.
812    ///
813    /// If None, 2MB will be the limit.
814    /// This value affects the cost of the http request and it is highly recommended
815    /// to set it as low as possible to avoid unnecessary extra costs.
816    ///
817    /// See also the [pricing section of HTTP outcalls documentation](https://internetcomputer.org/docs/current/references/https-outcalls-how-it-works#pricing).
818    pub max_response_bytes: Option<u64>,
819    /// The method of HTTP request.
820    pub method: HttpMethod,
821    /// List of HTTP request headers and their corresponding values.
822    pub headers: Vec<HttpHeader>,
823    /// Optionally provide request body.
824    pub body: Option<Vec<u8>>,
825    /// Name of the transform function which is `func (transform_args) -> (http_response) query`.
826    pub transform: Option<TransformContext>,
827    /// If `Some(false)`, the HTTP request will be made by single replica instead of all nodes in the subnet.
828    pub is_replicated: Option<bool>,
829}
830
831/// # HTTP Request Result
832///
833/// Result type of [`http_request`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-http_request).
834#[derive(
835    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
836)]
837pub struct HttpRequestResult {
838    /// The response status (e.g. 200, 404).
839    pub status: candid::Nat,
840    /// List of HTTP response headers and their corresponding values.
841    pub headers: Vec<HttpHeader>,
842    /// The response’s body.
843    #[serde(with = "serde_bytes")]
844    pub body: Vec<u8>,
845}
846
847/// # HTTP Method.
848///
849/// Represents a HTTP method.
850///
851/// See [`HttpRequestArgs::method`].
852#[derive(
853    CandidType,
854    Serialize,
855    Deserialize,
856    Debug,
857    PartialEq,
858    Eq,
859    PartialOrd,
860    Ord,
861    Hash,
862    Clone,
863    Copy,
864    Default,
865)]
866pub enum HttpMethod {
867    /// GET
868    #[default]
869    #[serde(rename = "get")]
870    GET,
871    /// POST
872    #[serde(rename = "post")]
873    POST,
874    /// HEAD
875    #[serde(rename = "head")]
876    HEAD,
877}
878
879/// # HTTP Header.
880///
881/// Represents a HTTP header.
882///
883/// See [`HttpRequestArgs::headers`] and [`HttpRequestResult::headers`].
884#[derive(
885    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
886)]
887pub struct HttpHeader {
888    /// Name of the header.
889    pub name: String,
890    /// Value of the header.
891    pub value: String,
892}
893
894/// # Transform Context.
895///
896/// ```text
897/// record {
898///     function : func(record { response : http_request_result; context : blob }) -> (http_request_result) query;
899///     context : blob;
900/// };
901/// ```
902///
903/// See [`HttpRequestArgs::transform`].
904#[derive(CandidType, Clone, Debug, Deserialize, PartialEq, Eq)]
905pub struct TransformContext {
906    /// `func(record { response : http_request_result; context : blob }) -> (http_request_result) query;`.
907    pub function: TransformFunc,
908
909    /// Context to be passed to `transform` function to transform HTTP response for consensus
910    #[serde(with = "serde_bytes")]
911    pub context: Vec<u8>,
912}
913
914mod transform_func {
915    #![allow(missing_docs)]
916    use super::{HttpRequestResult, TransformArgs};
917    candid::define_function!(pub TransformFunc : (TransformArgs) -> (HttpRequestResult) query);
918}
919
920/// # Transform Function.
921///
922/// The "transform" function of type:
923/// ```text
924/// func(record { response : http_request_result; context : blob }) -> (http_request_result) query
925/// ```
926#[doc(inline)]
927pub use transform_func::TransformFunc;
928
929/// # Transform Args.
930///
931/// ```text
932/// record {
933///     response : http_response;
934///     context : blob;
935/// }
936/// ```
937///
938/// See [`TransformContext`].
939#[derive(CandidType, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
940pub struct TransformArgs {
941    /// Raw response from remote service, to be transformed
942    pub response: HttpRequestResult,
943
944    /// Context for response transformation
945    #[serde(with = "serde_bytes")]
946    pub context: Vec<u8>,
947}
948
949/// # ECDSA Key ID.
950///
951/// See [`EcdsaPublicKeyArgs::key_id`] and [`SignWithEcdsaArgs::key_id`].
952#[derive(
953    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
954)]
955pub struct EcdsaKeyId {
956    /// Curve of the key.
957    pub curve: EcdsaCurve,
958    /// Name of the key.
959    pub name: String,
960}
961
962/// # ECDSA Curve.
963#[derive(
964    CandidType,
965    Serialize,
966    Deserialize,
967    Debug,
968    PartialEq,
969    Eq,
970    PartialOrd,
971    Ord,
972    Hash,
973    Clone,
974    Copy,
975    Default,
976)]
977pub enum EcdsaCurve {
978    /// secp256k1
979    #[default]
980    #[serde(rename = "secp256k1")]
981    Secp256k1,
982}
983
984impl From<EcdsaCurve> for u32 {
985    fn from(val: EcdsaCurve) -> Self {
986        match val {
987            EcdsaCurve::Secp256k1 => 0,
988        }
989    }
990}
991
992/// # ECDSA Public Key Args.
993///
994/// Argument type of [`ecdsa_public_key`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-ecdsa_public_key).
995#[derive(
996    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
997)]
998pub struct EcdsaPublicKeyArgs {
999    /// Canister id, default to the canister id of the caller if `None`.
1000    pub canister_id: Option<CanisterId>,
1001    /// A vector of variable length byte strings.
1002    pub derivation_path: Vec<Vec<u8>>,
1003    /// The key ID.
1004    pub key_id: EcdsaKeyId,
1005}
1006
1007/// # ECDSA Public Key Result.
1008///
1009/// Result type of [`ecdsa_public_key`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-ecdsa_public_key).
1010#[derive(
1011    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1012)]
1013pub struct EcdsaPublicKeyResult {
1014    /// An ECDSA public key encoded in SEC1 compressed form.
1015    #[serde(with = "serde_bytes")]
1016    pub public_key: Vec<u8>,
1017    /// Can be used to deterministically derive child keys of the [`public_key`](Self::public_key).
1018    #[serde(with = "serde_bytes")]
1019    pub chain_code: Vec<u8>,
1020}
1021
1022/// # Sign With ECDSA Args.
1023///
1024/// Argument type of [`sign_with_ecdsa`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_ecdsa).
1025#[derive(
1026    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1027)]
1028pub struct SignWithEcdsaArgs {
1029    /// Hash of the message with length of 32 bytes.
1030    #[serde(with = "serde_bytes")]
1031    pub message_hash: Vec<u8>,
1032    /// A vector of variable length byte strings.
1033    pub derivation_path: Vec<Vec<u8>>,
1034    /// The key ID.
1035    pub key_id: EcdsaKeyId,
1036}
1037
1038/// # Sign With ECDSA Result.
1039///
1040/// Result type of [`sign_with_ecdsa`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_ecdsa).
1041#[derive(
1042    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1043)]
1044pub struct SignWithEcdsaResult {
1045    /// Encoded as the concatenation of the SEC1 encodings of the two values `r` and `s`.
1046    #[serde(with = "serde_bytes")]
1047    pub signature: Vec<u8>,
1048}
1049
1050/// # Schnorr Key ID.
1051#[derive(
1052    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1053)]
1054pub struct SchnorrKeyId {
1055    /// Algorithm of the key.
1056    pub algorithm: SchnorrAlgorithm,
1057    /// Name of the key.
1058    pub name: String,
1059}
1060
1061/// # Schnorr Algorithm.
1062///
1063/// See [`SchnorrKeyId::algorithm`].
1064#[derive(
1065    CandidType,
1066    Serialize,
1067    Deserialize,
1068    Debug,
1069    PartialEq,
1070    Eq,
1071    PartialOrd,
1072    Ord,
1073    Hash,
1074    Clone,
1075    Copy,
1076    Default,
1077)]
1078pub enum SchnorrAlgorithm {
1079    /// BIP-340 secp256k1.
1080    #[serde(rename = "bip340secp256k1")]
1081    #[default]
1082    Bip340secp256k1,
1083    /// ed25519.
1084    #[serde(rename = "ed25519")]
1085    Ed25519,
1086}
1087
1088impl From<SchnorrAlgorithm> for u32 {
1089    fn from(val: SchnorrAlgorithm) -> Self {
1090        match val {
1091            SchnorrAlgorithm::Bip340secp256k1 => 0,
1092            SchnorrAlgorithm::Ed25519 => 1,
1093        }
1094    }
1095}
1096
1097/// # Schnorr Public Key Args.
1098///
1099/// Argument type of [`schnorr_public_key`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-schnorr_public_key).
1100#[derive(
1101    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1102)]
1103pub struct SchnorrPublicKeyArgs {
1104    /// Canister id, default to the canister id of the caller if `None`.
1105    pub canister_id: Option<CanisterId>,
1106    /// A vector of variable length byte strings.
1107    pub derivation_path: Vec<Vec<u8>>,
1108    /// The key ID.
1109    pub key_id: SchnorrKeyId,
1110}
1111
1112/// # Schnorr Public Key Result.
1113///
1114/// Result type of [`schnorr_public_key`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-schnorr_public_key).
1115#[derive(
1116    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1117)]
1118pub struct SchnorrPublicKeyResult {
1119    /// An Schnorr public key encoded in SEC1 compressed form.
1120    #[serde(with = "serde_bytes")]
1121    pub public_key: Vec<u8>,
1122    /// Can be used to deterministically derive child keys of the `public_key`.
1123    #[serde(with = "serde_bytes")]
1124    pub chain_code: Vec<u8>,
1125}
1126
1127/// # Schnorr Aux.
1128#[derive(
1129    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1130)]
1131pub enum SchnorrAux {
1132    #[serde(rename = "bip341")]
1133    Bip341(Bip341),
1134}
1135
1136/// # Bip341 variant of Schnorr Aux.
1137#[derive(
1138    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1139)]
1140pub struct Bip341 {
1141    /// Merkle tree root hash.
1142    pub merkle_root_hash: Vec<u8>,
1143}
1144
1145/// # Sign With Schnorr Args.
1146///
1147/// Argument type of [`sign_with_schnorr`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_schnorr).
1148#[derive(
1149    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1150)]
1151pub struct SignWithSchnorrArgs {
1152    /// Message to be signed.
1153    #[serde(with = "serde_bytes")]
1154    pub message: Vec<u8>,
1155    /// A vector of variable length byte strings.
1156    pub derivation_path: Vec<Vec<u8>>,
1157    /// The key ID.
1158    pub key_id: SchnorrKeyId,
1159    /// Schnorr auxiliary inputs.
1160    pub aux: Option<SchnorrAux>,
1161}
1162
1163/// # Sign With Schnorr Result.
1164///
1165/// Result type of [`sign_with_schnorr`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_schnorr).
1166#[derive(
1167    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1168)]
1169pub struct SignWithSchnorrResult {
1170    /// The signature.
1171    ///
1172    /// The encoding of the signature depends on the key ID's algorithm.
1173    /// See [`sign_with_schnorr`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-sign_with_schnorr) for more details.
1174    #[serde(with = "serde_bytes")]
1175    pub signature: Vec<u8>,
1176}
1177
1178/// # The curve used for key derivation.
1179#[derive(
1180    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy,
1181)]
1182pub enum VetKDCurve {
1183    /// BLS12-381 G2
1184    #[serde(rename = "bls12_381_g2")]
1185    #[allow(non_camel_case_types)]
1186    Bls12_381_G2,
1187}
1188
1189impl From<VetKDCurve> for u32 {
1190    fn from(val: VetKDCurve) -> Self {
1191        match val {
1192            VetKDCurve::Bls12_381_G2 => 0,
1193        }
1194    }
1195}
1196
1197#[derive(
1198    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1199)]
1200pub struct VetKDKeyId {
1201    /// The curve used for key derivation.
1202    pub curve: VetKDCurve,
1203    /// The name of the key.
1204    pub name: String,
1205}
1206
1207/// # VetKD public key request.
1208#[derive(
1209    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1210)]
1211pub struct VetKDPublicKeyArgs {
1212    /// Canister id, defaults to the canister id of the caller if `None`.
1213    pub canister_id: Option<CanisterId>,
1214    /// The context of the key derivation.
1215    pub context: Vec<u8>,
1216    /// The key id.
1217    pub key_id: VetKDKeyId,
1218}
1219
1220/// # VetKD public key reply.
1221#[derive(
1222    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1223)]
1224pub struct VetKDPublicKeyResult {
1225    /// The public key.
1226    pub public_key: Vec<u8>,
1227}
1228
1229/// # VetKD derive key request.
1230#[derive(
1231    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1232)]
1233pub struct VetKDDeriveKeyArgs {
1234    /// The input of the key derivation.
1235    pub input: Vec<u8>,
1236    /// The context of the key derivation.
1237    pub context: Vec<u8>,
1238    /// The transport public key used to encrypt the derived key.
1239    pub transport_public_key: Vec<u8>,
1240    /// The id of the key deployed on the Internet Computer.
1241    pub key_id: VetKDKeyId,
1242}
1243
1244/// # VetKD derive key reply.
1245#[derive(
1246    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1247)]
1248pub struct VetKDDeriveKeyResult {
1249    /// The derived key encrypted with the transport public key.
1250    pub encrypted_key: Vec<u8>,
1251}
1252
1253/// # Node Metrics History Args.
1254///
1255/// Argument type of [`node_metrics_history`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-node_metrics_history).
1256#[derive(
1257    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1258)]
1259pub struct NodeMetricsHistoryArgs {
1260    /// Subnet ID.
1261    pub subnet_id: Principal,
1262    /// The returned time series will start at this timestamp.
1263    pub start_at_timestamp_nanos: u64,
1264}
1265
1266/// # Node Metrics History Result.
1267///
1268/// Result type of [`node_metrics_history`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-node_metrics_history).
1269pub type NodeMetricsHistoryResult = Vec<NodeMetricsHistoryRecord>;
1270
1271/// # Node Metrics History Record.
1272///
1273/// A record in [`NodeMetricsHistoryResult`].
1274#[derive(
1275    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1276)]
1277pub struct NodeMetricsHistoryRecord {
1278    /// Timestamp of the record.
1279    pub timestamp_nanos: u64,
1280    /// Metrics of the nodes.
1281    pub node_metrics: Vec<NodeMetrics>,
1282}
1283
1284/// # Node Metrics.
1285///
1286/// See [`NodeMetricsHistoryRecord::node_metrics`].
1287#[derive(
1288    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1289)]
1290pub struct NodeMetrics {
1291    /// Node ID.
1292    pub node_id: Principal,
1293    /// Number of blocks proposed by this node.
1294    pub num_blocks_proposed_total: u64,
1295    /// Number of failed block proposals by this node.
1296    pub num_block_failures_total: u64,
1297}
1298
1299/// # Subnet Info Args.
1300///
1301/// Argument type of [`subnet_info`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-subnet_info).
1302#[derive(
1303    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1304)]
1305pub struct SubnetInfoArgs {
1306    /// Subnet ID.
1307    pub subnet_id: Principal,
1308}
1309
1310/// # Subnet Info Result.
1311///
1312/// Result type of [`subnet_info`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-subnet_info).
1313#[derive(
1314    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1315)]
1316pub struct SubnetInfoResult {
1317    /// Replica version of the subnet.
1318    pub replica_version: String,
1319    /// Registry version of the subnet.
1320    pub registry_version: u64,
1321}
1322
1323/// # Provisional Create Canister With Cycles Args.
1324///
1325/// Argument type of [`provisional_create_canister_with_cycles`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-provisional_create_canister_with_cycles).
1326#[derive(
1327    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1328)]
1329pub struct ProvisionalCreateCanisterWithCyclesArgs {
1330    /// The created canister will have this amount of cycles.
1331    pub amount: Option<Nat>,
1332    /// Canister settings.
1333    pub settings: Option<CanisterSettings>,
1334    /// If set, the canister will be created under this id.
1335    pub specified_id: Option<CanisterId>,
1336    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
1337    pub sender_canister_version: Option<u64>,
1338}
1339
1340/// # Provisional Create Canister With Cycles Result.
1341///
1342/// Result type of [`provisional_create_canister_with_cycles`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-provisional_create_canister_with_cycles).
1343pub type ProvisionalCreateCanisterWithCyclesResult = CanisterIdRecord;
1344
1345/// # Provisional Top Up Canister Args.
1346///
1347/// Argument type of [`provisional_top_up_canister`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-provisional_top_up_canister).
1348#[derive(
1349    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1350)]
1351pub struct ProvisionalTopUpCanisterArgs {
1352    /// Canister ID.
1353    pub canister_id: CanisterId,
1354    /// Amount of cycles to be added.
1355    pub amount: Nat,
1356}
1357
1358/// # Snapshot ID.
1359///
1360/// See [`Snapshot::id`].
1361pub type SnapshotId = Vec<u8>;
1362
1363/// # Snapshot.
1364///
1365/// A snapshot of the canister's state at a given point in time.
1366#[derive(
1367    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Default,
1368)]
1369pub struct Snapshot {
1370    /// Snapshot ID.
1371    pub id: SnapshotId,
1372    /// Timestamp at which the snapshot was taken.
1373    pub taken_at_timestamp: u64,
1374    /// Total size of the snapshot in bytes.
1375    pub total_size: u64,
1376}
1377
1378/// # Take Canister Snapshot Args.
1379///
1380/// Argument type of [`take_canister_snapshot`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-take_canister_snapshot).
1381#[derive(
1382    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1383)]
1384pub struct TakeCanisterSnapshotArgs {
1385    /// Canister ID.
1386    pub canister_id: CanisterId,
1387    /// An optional snapshot ID to be replaced by the new snapshot.
1388    ///
1389    /// The snapshot identified by the specified ID will be deleted once a new snapshot has been successfully created.
1390    pub replace_snapshot: Option<SnapshotId>,
1391    /// If true, uninstall the canister code after taking the snapshot.
1392    pub uninstall_code: Option<bool>,
1393    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
1394    pub sender_canister_version: Option<u64>,
1395}
1396
1397/// # Take Canister Snapshot Result.
1398///
1399/// Result type of [`take_canister_snapshot`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-take_canister_snapshot).
1400pub type TakeCanisterSnapshotResult = Snapshot;
1401
1402/// # Load Canister Snapshot Args.
1403///
1404/// Argument type of [`load_canister_snapshot`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-load_canister_snapshot).
1405#[derive(
1406    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1407)]
1408pub struct LoadCanisterSnapshotArgs {
1409    /// Canister ID.
1410    pub canister_id: CanisterId,
1411    /// ID of the snapshot to be loaded.
1412    pub snapshot_id: SnapshotId,
1413    /// Must match the canister's [`canister_version`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-canister-version) value when specified.
1414    pub sender_canister_version: Option<u64>,
1415}
1416
1417/// # List Canister Snapshots Args.
1418///
1419/// Argument type of [`list_canister_snapshots`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-list_canister_snapshots).
1420pub type ListCanisterSnapshotsArgs = CanisterIdRecord;
1421
1422/// # List Canister Snapshots Result.
1423///
1424/// Result type of [`list_canister_snapshots`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-list_canister_snapshots).
1425pub type ListCanisterSnapshotsResult = Vec<Snapshot>;
1426
1427/// # Delete Canister Snapshot Args.
1428///
1429/// Argument type of [`delete_canister_snapshot`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-delete_canister_snapshot).
1430#[derive(
1431    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1432)]
1433pub struct DeleteCanisterSnapshotArgs {
1434    /// Canister ID.
1435    pub canister_id: CanisterId,
1436    /// ID of the snapshot to be deleted.
1437    pub snapshot_id: SnapshotId,
1438}
1439
1440/// # Read Canister Snapshot Metadata Args.
1441#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1442pub struct ReadCanisterSnapshotMetadataArgs {
1443    /// Canister ID.
1444    pub canister_id: CanisterId,
1445    /// ID of the snapshot to be read.
1446    pub snapshot_id: SnapshotId,
1447}
1448
1449/// # Read Canister Snapshot Metadata Result.
1450#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1451pub struct ReadCanisterSnapshotMetadataResult {
1452    /// The source of the snapshot.
1453    pub source: Option<SnapshotSource>,
1454    /// The Unix nanosecond timestamp the snapshot was taken at.
1455    pub taken_at_timestamp: u64,
1456    /// The size of the Wasm module.
1457    pub wasm_module_size: u64,
1458    /// The globals.
1459    pub globals: Vec<Option<SnapshotMetadataGlobal>>,
1460    /// The size of the Wasm memory.
1461    pub wasm_memory_size: u64,
1462    /// The size of the stable memory.
1463    pub stable_memory_size: u64,
1464    /// The chunk store of the Wasm module.
1465    pub wasm_chunk_store: StoredChunksResult,
1466    /// The version of the canister.
1467    pub canister_version: u64,
1468    /// The certified data.
1469    #[serde(with = "serde_bytes")]
1470    pub certified_data: Vec<u8>,
1471    /// The status of the global timer.
1472    pub global_timer: Option<CanisterTimer>,
1473    /// The status of the low wasm memory hook.
1474    pub on_low_wasm_memory_hook_status: Option<OnLowWasmMemoryHookStatus>,
1475}
1476
1477/// # The source of a snapshot.
1478#[derive(
1479    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1480)]
1481pub enum SnapshotSource {
1482    /// The snapshot was taken from a canister.
1483    #[serde(rename = "taken_from_canister")]
1484    TakenFromCanister(Reserved),
1485    /// The snapshot was created by uploading metadata.
1486    #[serde(rename = "metadata_upload")]
1487    MetadataUpload(Reserved),
1488}
1489
1490/// # An exported global variable.
1491#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1492pub enum SnapshotMetadataGlobal {
1493    /// A 32-bit integer.
1494    #[serde(rename = "i32")]
1495    I32(i32),
1496    /// A 64-bit integer.
1497    #[serde(rename = "i64")]
1498    I64(i64),
1499    /// A 32-bit floating point number.
1500    #[serde(rename = "f32")]
1501    F32(f32),
1502    /// A 64-bit floating point number.
1503    #[serde(rename = "f64")]
1504    F64(f64),
1505    /// A 128-bit integer.
1506    #[serde(rename = "v128")]
1507    V128(Nat),
1508}
1509
1510/// # The status of a global timer.
1511#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1512pub enum CanisterTimer {
1513    /// The global timer is inactive.
1514    #[serde(rename = "inactive")]
1515    Inactive,
1516    /// The global timer is active.
1517    #[serde(rename = "active")]
1518    Active(u64),
1519}
1520
1521/// # The status of a low wasm memory hook.
1522#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1523pub enum OnLowWasmMemoryHookStatus {
1524    /// The condition for the  low wasm memory hook is not satisfied.
1525    #[serde(rename = "condition_not_satisfied")]
1526    ConditionNotSatisfied,
1527    /// The low wasm memory hook is ready to be executed.
1528    #[serde(rename = "ready")]
1529    Ready,
1530    /// The low wasm memory hook has been executed.
1531    #[serde(rename = "executed")]
1532    Executed,
1533}
1534
1535/// # Read Canister Snapshot Data Args.
1536#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1537pub struct ReadCanisterSnapshotDataArgs {
1538    /// Canister ID.
1539    pub canister_id: CanisterId,
1540    /// ID of the snapshot.
1541    pub snapshot_id: SnapshotId,
1542    /// The kind of data to be read.
1543    pub kind: SnapshotDataKind,
1544}
1545
1546/// # Snapshot data kind.
1547#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1548pub enum SnapshotDataKind {
1549    /// Wasm module.
1550    #[serde(rename = "wasm_module")]
1551    WasmModule {
1552        /// Offset in bytes.
1553        offset: u64,
1554        /// Size of the data in bytes.
1555        size: u64,
1556    },
1557    /// Wasm memory.
1558    #[serde(rename = "wasm_memory")]
1559    WasmMemory {
1560        /// Offset in bytes.
1561        offset: u64,
1562        /// Size of the data in bytes.
1563        size: u64,
1564    },
1565    /// Stable memory.
1566    #[serde(rename = "stable_memory")]
1567    StableMemory {
1568        /// Offset in bytes.
1569        offset: u64,
1570        /// Size of the data in bytes.
1571        size: u64,
1572    },
1573    /// Chunk hash.
1574    #[serde(rename = "wasm_chunk")]
1575    WasmChunk {
1576        /// The hash of the chunk.
1577        #[serde(with = "serde_bytes")]
1578        hash: Vec<u8>,
1579    },
1580}
1581
1582/// # Read Canister Snapshot Data Result.
1583#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1584pub struct ReadCanisterSnapshotDataResult {
1585    /// The returned chunk of data.
1586    #[serde(with = "serde_bytes")]
1587    pub chunk: Vec<u8>,
1588}
1589
1590/// # Upload Canister Snapshot Metadata Args.
1591#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1592pub struct UploadCanisterSnapshotMetadataArgs {
1593    /// Canister ID.
1594    pub canister_id: CanisterId,
1595    /// An optional snapshot ID to be replaced by the new snapshot.
1596    ///
1597    /// The snapshot identified by the specified ID will be deleted once a new snapshot has been successfully created.
1598    pub replace_snapshot: Option<SnapshotId>,
1599    /// The size of the Wasm module.
1600    pub wasm_module_size: u64,
1601    /// The globals.
1602    pub globals: Vec<SnapshotMetadataGlobal>,
1603    /// The size of the Wasm memory.
1604    pub wasm_memory_size: u64,
1605    /// The size of the stable memory.
1606    pub stable_memory_size: u64,
1607    /// The certified data.
1608    pub certified_data: Vec<u8>,
1609    /// The status of the global timer.
1610    pub global_timer: Option<CanisterTimer>,
1611    /// The status of the low wasm memory hook.
1612    pub on_low_wasm_memory_hook_status: Option<OnLowWasmMemoryHookStatus>,
1613}
1614
1615/// # Upload Canister Snapshot Metadata Result.
1616#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1617pub struct UploadCanisterSnapshotMetadataResult {
1618    /// The ID of the snapshot.
1619    pub snapshot_id: SnapshotId,
1620}
1621
1622/// # Upload Canister Snapshot Data Args.
1623#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1624pub struct UploadCanisterSnapshotDataArgs {
1625    /// Canister ID.
1626    pub canister_id: CanisterId,
1627    /// ID of the snapshot.
1628    pub snapshot_id: SnapshotId,
1629    /// The kind of data to be uploaded.
1630    pub kind: SnapshotDataOffset,
1631    /// The chunk of data to be uploaded.
1632    pub chunk: Vec<u8>,
1633}
1634
1635/// # Snapshot data offset.
1636#[derive(CandidType, Serialize, Deserialize, Debug, Clone)]
1637pub enum SnapshotDataOffset {
1638    /// Wasm module.
1639    #[serde(rename = "wasm_module")]
1640    WasmModule {
1641        /// Offset in bytes.
1642        offset: u64,
1643    },
1644    /// Wasm memory.
1645    #[serde(rename = "wasm_memory")]
1646    WasmMemory {
1647        /// Offset in bytes.
1648        offset: u64,
1649    },
1650    /// Stable memory.
1651    #[serde(rename = "stable_memory")]
1652    StableMemory {
1653        /// Offset in bytes.
1654        offset: u64,
1655    },
1656    /// Wasm chunk.
1657    #[serde(rename = "wasm_chunk")]
1658    WasmChunk,
1659}
1660
1661/// # Fetch Canister Logs Args.
1662///
1663/// Argument type of [`fetch_canister_logs`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-fetch_canister_logs).
1664pub type FetchCanisterLogsArgs = CanisterIdRecord;
1665
1666/// # Canister Log Record
1667///
1668/// See [`FetchCanisterLogsResult::canister_log_records`].
1669#[derive(
1670    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1671)]
1672pub struct CanisterLogRecord {
1673    /// The index of the log record.
1674    pub idx: u64,
1675    /// The timestamp of the log record.
1676    pub timestamp_nanos: u64,
1677    /// The content of the log record.
1678    #[serde(with = "serde_bytes")]
1679    pub content: Vec<u8>,
1680}
1681
1682/// # Fetch Canister Logs Result.
1683///
1684/// Result type of [`fetch_canister_logs`](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-fetch_canister_logs).
1685#[derive(
1686    CandidType, Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone,
1687)]
1688pub struct FetchCanisterLogsResult {
1689    /// The logs of the canister.
1690    pub canister_log_records: Vec<CanisterLogRecord>,
1691}
ic_management_canister_types/lib.rs

ic_management_canister_types/
lib.rs
