canic_core/dto/
rpc.rs

1use crate::dto::{
2    auth::{
3        DelegationProvisionResponse, DelegationRequest, RoleAttestationRequest,
4        SignedRoleAttestation,
5    },
6    prelude::*,
7};
8
9///
10/// Request
11/// Root-directed orchestration commands.
12///
13
14#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
15pub enum Request {
16    CreateCanister(CreateCanisterRequest),
17    UpgradeCanister(UpgradeCanisterRequest),
18    Cycles(CyclesRequest),
19    IssueDelegation(DelegationRequest),
20    IssueRoleAttestation(RoleAttestationRequest),
21}
22
23///
24/// RootCapabilityRequest
25/// DTO-facing capability envelope used by root dispatch internals.
26///
27
28#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
29pub enum RootCapabilityRequest {
30    ProvisionCanister(CreateCanisterRequest),
31    UpgradeCanister(UpgradeCanisterRequest),
32    MintCycles(CyclesRequest),
33    IssueDelegation(DelegationRequest),
34    IssueRoleAttestation(RoleAttestationRequest),
35}
36
37impl From<Request> for RootCapabilityRequest {
38    fn from(value: Request) -> Self {
39        match value {
40            Request::CreateCanister(req) => Self::ProvisionCanister(req),
41            Request::UpgradeCanister(req) => Self::UpgradeCanister(req),
42            Request::Cycles(req) => Self::MintCycles(req),
43            Request::IssueDelegation(req) => Self::IssueDelegation(req),
44            Request::IssueRoleAttestation(req) => Self::IssueRoleAttestation(req),
45        }
46    }
47}
48
49///
50/// RootRequestMetadata
51/// Replay and idempotency metadata for mutating root requests.
52///
53
54#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
55pub struct RootRequestMetadata {
56    pub request_id: [u8; 32],
57    pub ttl_seconds: u64,
58}
59
60///
61/// CreateCanisterRequest
62/// Payload for [`Request::CreateCanister`]
63///
64
65#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
66pub struct CreateCanisterRequest {
67    pub canister_role: CanisterRole,
68    pub parent: CreateCanisterParent,
69    pub extra_arg: Option<Vec<u8>>,
70    #[serde(default)]
71    pub metadata: Option<RootRequestMetadata>,
72}
73
74///
75/// CreateCanisterParent
76/// Parent-location choices for a new canister
77///
78
79#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
80pub enum CreateCanisterParent {
81    Root,
82    /// Use the requesting canister as parent.
83    ThisCanister,
84    /// Use the requesting canister's parent (creates a sibling).
85    Parent,
86    Canister(Principal),
87    Directory(CanisterRole),
88}
89
90///
91/// UpgradeCanisterRequest
92/// Payload for [`Request::UpgradeCanister`]
93///
94
95#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
96pub struct UpgradeCanisterRequest {
97    pub canister_pid: Principal,
98    #[serde(default)]
99    pub metadata: Option<RootRequestMetadata>,
100}
101
102///
103/// CyclesRequest
104/// Payload for [`Request::Cycles`]
105///
106
107#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
108pub struct CyclesRequest {
109    pub cycles: u128,
110    #[serde(default)]
111    pub metadata: Option<RootRequestMetadata>,
112}
113
114///
115/// Response
116/// Response payloads produced by root for orchestration requests.
117///
118
119#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
120pub enum Response {
121    CreateCanister(CreateCanisterResponse),
122    UpgradeCanister(UpgradeCanisterResponse),
123    Cycles(CyclesResponse),
124    DelegationIssued(DelegationProvisionResponse),
125    RoleAttestationIssued(SignedRoleAttestation),
126}
127
128///
129/// CreateCanisterResponse
130/// Result of creating and installing a new canister.
131///
132
133#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
134pub struct CreateCanisterResponse {
135    pub new_canister_pid: Principal,
136}
137
138///
139/// UpgradeCanisterResponse
140/// Result of an upgrade request (currently empty, reserved for metadata)
141///
142
143#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
144pub struct UpgradeCanisterResponse {}
145
146///
147/// CyclesResponse
148/// Result of transferring cycles to a child canister
149///
150
151#[derive(CandidType, Clone, Debug, Deserialize, Serialize)]
152pub struct CyclesResponse {
153    pub cycles_transferred: u128,
154}
canic_core/dto/rpc.rs

canic_core/dto/
rpc.rs
