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

canic_core/dto/
rpc.rs
