canic_core/dto/
rpc.rs

1use crate::dto::prelude::*;
2
3//
4// Request
5//
6// Root orchestration request.
7//
8
9#[derive(CandidType, Clone, Debug, Deserialize)]
10pub enum Request {
11    AcknowledgePlacementReceipt(AcknowledgePlacementReceiptRequest),
12    AllocatePlacementChild(CreateCanisterRequest),
13    CreateCanister(CreateCanisterRequest),
14    UpgradeCanister(UpgradeCanisterRequest),
15    RecycleCanister(RecycleCanisterRequest),
16    Cycles(CyclesRequest),
17}
18
19impl Request {
20    // acknowledge_placement_receipt
21    //
22    // Build a root request that releases one durably consumed placement receipt.
23    #[must_use]
24    pub const fn acknowledge_placement_receipt(
25        request: AcknowledgePlacementReceiptRequest,
26    ) -> Self {
27        Self::AcknowledgePlacementReceipt(request)
28    }
29
30    // allocate_placement_child
31    //
32    // Build a retained root request for receipt-backed placement allocation.
33    #[must_use]
34    pub const fn allocate_placement_child(request: CreateCanisterRequest) -> Self {
35        Self::AllocatePlacementChild(request)
36    }
37
38    // create_canister
39    //
40    // Build a root request for canister provisioning.
41    #[must_use]
42    pub const fn create_canister(request: CreateCanisterRequest) -> Self {
43        Self::CreateCanister(request)
44    }
45
46    // upgrade_canister
47    //
48    // Build a root request for upgrading an existing canister.
49    #[must_use]
50    pub const fn upgrade_canister(request: UpgradeCanisterRequest) -> Self {
51        Self::UpgradeCanister(request)
52    }
53
54    // recycle_canister
55    //
56    // Build a root request for recycling one child canister back into the pool.
57    #[must_use]
58    pub const fn recycle_canister(request: RecycleCanisterRequest) -> Self {
59        Self::RecycleCanister(request)
60    }
61
62    // cycles
63    //
64    // Build a root request for requesting/transferring cycles.
65    #[must_use]
66    pub const fn cycles(request: CyclesRequest) -> Self {
67        Self::Cycles(request)
68    }
69}
70
71//
72// AcknowledgePlacementReceiptRequest
73//
74// Placement-receipt acknowledgement payload.
75//
76
77#[derive(CandidType, Clone, Debug, Deserialize)]
78pub struct AcknowledgePlacementReceiptRequest {
79    pub operation_id: [u8; 32],
80    pub metadata: Option<RootRequestMetadata>,
81}
82
83//
84// RootRequestMetadata
85//
86// Replay metadata.
87//
88
89#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
90pub struct RootRequestMetadata {
91    pub request_id: [u8; 32],
92    pub ttl_ns: u64,
93}
94
95//
96// CreateCanisterRequest
97//
98// Create-canister payload.
99//
100
101#[derive(CandidType, Clone, Debug, Deserialize)]
102pub struct CreateCanisterRequest {
103    pub canister_role: CanisterRole,
104    pub parent: CreateCanisterParent,
105    pub extra_arg: Option<Vec<u8>>,
106    pub metadata: Option<RootRequestMetadata>,
107}
108
109//
110// CreateCanisterParent
111//
112// Parent selection.
113//
114
115#[derive(CandidType, Clone, Debug, Deserialize)]
116pub enum CreateCanisterParent {
117    Root,
118    // Use the requesting canister.
119    ThisCanister,
120    // Use the caller's parent.
121    Parent,
122    Canister(Principal),
123    Index(CanisterRole),
124}
125
126//
127// UpgradeCanisterRequest
128//
129// Upgrade-canister payload.
130//
131
132#[derive(CandidType, Clone, Debug, Deserialize)]
133pub struct UpgradeCanisterRequest {
134    pub canister_pid: Principal,
135    pub metadata: Option<RootRequestMetadata>,
136}
137
138//
139// RecycleCanisterRequest
140//
141// Recycle-one-child payload.
142//
143
144#[derive(CandidType, Clone, Debug, Deserialize)]
145pub struct RecycleCanisterRequest {
146    pub canister_pid: Principal,
147    pub metadata: Option<RootRequestMetadata>,
148}
149
150//
151// CyclesRequest
152//
153// Cycles payload.
154//
155
156#[derive(CandidType, Clone, Debug, Deserialize)]
157pub struct CyclesRequest {
158    pub cycles: u128,
159    pub metadata: Option<RootRequestMetadata>,
160}
161
162//
163// Response
164//
165// Root response payload.
166//
167
168#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
169pub enum Response {
170    AcknowledgePlacementReceipt,
171    CreateCanister(CreateCanisterResponse),
172    UpgradeCanister,
173    RecycleCanister,
174    Cycles(CyclesResponse),
175}
176
177//
178// CreateCanisterResponse
179// Result of creating and installing a new canister.
180//
181
182#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
183pub struct CreateCanisterResponse {
184    pub new_canister_pid: Principal,
185}
186
187//
188// CyclesResponse
189// Result of transferring cycles to a child canister
190//
191
192#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
193pub struct CyclesResponse {
194    pub cycles_transferred: u128,
195}
canic_core/dto/rpc.rs

canic_core/dto/
rpc.rs
