ic_query/sns/report/model/reports/
swap.rs

1//! Module: sns::report::model::reports::swap
2//!
3//! Responsibility: SNS decentralization-swap report DTOs.
4//! Does not own: swap canister calls, source validation, lookup, or rendering.
5//! Boundary: preserves native swap lifecycle, sale parameters, derived state, and query gaps.
6
7use super::invocation::SnsCanisterMethod;
8use serde::Serialize;
9
10///
11/// SnsSwapComponent
12///
13/// Native swap query component represented by a report value or typed gap.
14///
15
16#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
17#[serde(rename_all = "snake_case")]
18pub enum SnsSwapComponent {
19    /// Swap lifecycle state and lifecycle timestamps.
20    Lifecycle,
21    /// Decentralization-sale parameters.
22    SaleParameters,
23    /// Participation totals and derived token rate.
24    DerivedState,
25}
26
27impl SnsSwapComponent {
28    /// Return the stable lowercase component label used in text reports.
29    #[must_use]
30    pub const fn as_str(self) -> &'static str {
31        match self {
32            Self::Lifecycle => "lifecycle",
33            Self::SaleParameters => "sale_parameters",
34            Self::DerivedState => "derived_state",
35        }
36    }
37}
38
39///
40/// SnsSwapQueryGap
41///
42/// One swap query that failed while the other bounded components were retained.
43///
44
45#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
46pub struct SnsSwapQueryGap {
47    /// Typed swap component whose query failed.
48    pub component: SnsSwapComponent,
49    /// Native query method that failed.
50    pub method: SnsCanisterMethod,
51    /// Transport, encoding, or decoding failure retained for diagnostics.
52    pub reason: String,
53}
54
55///
56/// SnsSwapLifecycle
57///
58/// Raw lifecycle code and timestamps returned by the SNS swap canister.
59///
60
61#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
62pub struct SnsSwapLifecycle {
63    /// Optional native lifecycle numeric discriminant.
64    pub lifecycle: Option<i32>,
65    /// Native lifecycle label, or `unknown` for an unrecognized numeric discriminant.
66    pub lifecycle_name: Option<String>,
67    /// Timestamp at which the decentralization sale opened, when returned.
68    pub decentralization_sale_open_timestamp_seconds: Option<u64>,
69    /// Timestamp at which the decentralization swap terminated, when returned.
70    pub decentralization_swap_termination_timestamp_seconds: Option<u64>,
71}
72
73///
74/// SnsSwapNeuronBasketConstructionParameters
75///
76/// Native neuron-basket construction parameters returned by the swap canister.
77///
78
79#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
80pub struct SnsSwapNeuronBasketConstructionParameters {
81    /// Number of neurons created in each participant basket.
82    pub count: u64,
83    /// Dissolve-delay interval between neurons in a basket, in seconds.
84    pub dissolve_delay_interval_seconds: u64,
85}
86
87///
88/// SnsSwapSaleParameters
89///
90/// Native decentralization-sale parameters returned by the swap canister.
91///
92
93#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
94pub struct SnsSwapSaleParameters {
95    /// Minimum legacy total ICP target in e8s.
96    pub min_icp_e8s: u64,
97    /// Maximum legacy total ICP target in e8s.
98    pub max_icp_e8s: u64,
99    /// Minimum direct participation target in ICP e8s, when returned.
100    pub min_direct_participation_icp_e8s: Option<u64>,
101    /// Maximum direct participation target in ICP e8s, when returned.
102    pub max_direct_participation_icp_e8s: Option<u64>,
103    /// SNS tokens offered by the sale in e8s.
104    pub sns_token_e8s: u64,
105    /// Minimum number of direct participants.
106    pub min_participants: u32,
107    /// Minimum ICP contribution per participant in e8s.
108    pub min_participant_icp_e8s: u64,
109    /// Maximum ICP contribution per participant in e8s.
110    pub max_participant_icp_e8s: u64,
111    /// Scheduled swap deadline in Unix seconds.
112    pub swap_due_timestamp_seconds: u64,
113    /// Optional delay before the sale opens, in seconds.
114    pub sale_delay_seconds: Option<u64>,
115    /// Neuron-basket construction parameters, when configured.
116    pub neuron_basket_construction_parameters: Option<SnsSwapNeuronBasketConstructionParameters>,
117}
118
119///
120/// SnsSwapDerivedState
121///
122/// Native aggregate participation values returned by the swap canister.
123///
124
125#[derive(Clone, Debug, PartialEq, Serialize)]
126pub struct SnsSwapDerivedState {
127    /// Derived SNS-token amount per ICP, when returned.
128    pub sns_tokens_per_icp: Option<f64>,
129    /// Total buyer ICP in e8s, when returned.
130    pub buyer_total_icp_e8s: Option<u64>,
131    /// Direct-participation ICP in e8s, when returned.
132    pub direct_participation_icp_e8s: Option<u64>,
133    /// Neurons' Fund participation ICP in e8s, when returned.
134    pub neurons_fund_participation_icp_e8s: Option<u64>,
135    /// Number of direct participants, when returned.
136    pub direct_participant_count: Option<u64>,
137    /// Number of Community Fund participants, when returned by older swap state.
138    pub cf_participant_count: Option<u64>,
139    /// Number of Community Fund neurons, when returned by older swap state.
140    pub cf_neuron_count: Option<u64>,
141}
142
143///
144/// SnsSwapReport
145///
146/// Bounded live report for one resolved SNS decentralization swap.
147///
148
149#[derive(Clone, Debug, PartialEq, Serialize)]
150pub struct SnsSwapReport {
151    /// Report schema version.
152    pub schema_version: u32,
153    /// Requested IC network identity.
154    pub network: String,
155    /// Mainnet SNS-W canister used to resolve the SNS.
156    pub sns_wasm_canister_id: String,
157    /// Collection timestamp in UTC.
158    pub fetched_at: String,
159    /// IC API endpoint used for SNS-W and swap calls.
160    pub source_endpoint: String,
161    /// Collector identity recorded by the source request.
162    pub fetched_by: String,
163    /// SNS-W list id assigned to this deployed SNS.
164    pub id: usize,
165    /// SNS name resolved during discovery.
166    pub name: String,
167    /// Root canister identity used to resolve this SNS.
168    pub root_canister_id: String,
169    /// Swap canister queried for lifecycle and sale state.
170    pub swap_canister_id: String,
171    /// Native method used for lifecycle state.
172    pub lifecycle_method: SnsCanisterMethod,
173    /// Native method used for sale parameters.
174    pub sale_parameters_method: SnsCanisterMethod,
175    /// Native method used for derived participation state.
176    pub derived_state_method: SnsCanisterMethod,
177    /// Whether all component values represent one authoritative point in time.
178    pub point_in_time_guaranteed: bool,
179    /// Fixed number of bounded swap component queries attempted.
180    pub component_query_count: usize,
181    /// Number of component queries that returned successfully.
182    pub successful_component_query_count: usize,
183    /// Number of typed component query gaps.
184    pub component_gap_count: usize,
185    /// Lifecycle response, absent only when its query failed.
186    pub lifecycle: Option<SnsSwapLifecycle>,
187    /// Sale parameters; `None` can also be a successful response with no configured parameters.
188    pub sale_parameters: Option<SnsSwapSaleParameters>,
189    /// Derived-state response, absent only when its query failed.
190    pub derived_state: Option<SnsSwapDerivedState>,
191    /// Canonically ordered component query failures.
192    pub gaps: Vec<SnsSwapQueryGap>,
193}
ic_query/sns/report/model/reports/swap.rs

ic_query/sns/report/model/reports/
swap.rs
