ic_xrc_types/
lib.rs

1use candid::{CandidType, Deserialize};
2
3/// The enum defining the different asset classes.
4#[derive(CandidType, Clone, Debug, Deserialize, PartialEq)]
5pub enum AssetClass {
6    /// The cryptocurrency asset class.
7    Cryptocurrency,
8    /// The fiat currency asset class.
9    FiatCurrency,
10}
11
12/// Exchange rates are derived for pairs of assets captured in this struct.
13#[derive(CandidType, Clone, Debug, Deserialize, PartialEq)]
14pub struct Asset {
15    /// The symbol/code of the asset.
16    pub symbol: String,
17    /// The asset class.
18    pub class: AssetClass,
19}
20
21/// The type the user sends when requesting a rate.
22#[derive(CandidType, Clone, Debug, Deserialize)]
23pub struct GetExchangeRateRequest {
24    /// The asset to be used as the resulting asset. For example, using
25    /// ICP/USD, ICP would be the base asset.
26    pub base_asset: Asset,
27    /// The asset to be used as the starting asset. For example, using
28    /// ICP/USD, USD would be the quote asset.
29    pub quote_asset: Asset,
30    /// An optional parameter used to find a rate at a specific time.
31    pub timestamp: Option<u64>,
32}
33
34/// Metadata information to give background on how the rate was determined.
35#[derive(CandidType, Clone, Debug, Deserialize, PartialEq)]
36pub struct ExchangeRateMetadata {
37    /// The scaling factor for the exchange rate and the standard deviation.
38    pub decimals: u32,
39    /// The number of queried exchanges for the base asset.
40    pub base_asset_num_queried_sources: usize,
41    /// The number of rates successfully received from the queried sources for the base asset.
42    pub base_asset_num_received_rates: usize,
43    /// The number of queried exchanges for the quote asset.
44    pub quote_asset_num_queried_sources: usize,
45    /// The number of rates successfully received from the queried sources for the quote asset.
46    pub quote_asset_num_received_rates: usize,
47    /// The standard deviation of the received rates, scaled by the factor `10^decimals`.
48    pub standard_deviation: u64,
49    /// The timestamp of the beginning of the day for which the forex rates were retrieved, if any.
50    pub forex_timestamp: Option<u64>,
51}
52
53/// When a rate is determined, this struct is used to present the information
54/// to the user.
55#[derive(CandidType, Clone, Debug, Deserialize, PartialEq)]
56pub struct ExchangeRate {
57    /// The base asset.
58    pub base_asset: Asset,
59    /// The quote asset.
60    pub quote_asset: Asset,
61    /// The timestamp associated with the returned rate.
62    pub timestamp: u64,
63    /// The median rate from the received rates, scaled by the factor `10^decimals` in the metadata.
64    pub rate: u64,
65    /// Metadata providing additional information about the exchange rate calculation.
66    pub metadata: ExchangeRateMetadata,
67}
68
69/// Returned to the user when something goes wrong retrieving the exchange rate.
70#[derive(CandidType, Clone, Debug, Deserialize)]
71pub enum ExchangeRateError {
72    /// Returned when the canister receives a call from the anonymous principal.
73    AnonymousPrincipalNotAllowed,
74    /// Returned when the canister is in process of retrieving a rate from an exchange.
75    Pending,
76    /// Returned when the base asset rates are not found from the exchanges HTTP outcalls.
77    CryptoBaseAssetNotFound,
78    /// Returned when the quote asset rates are not found from the exchanges HTTP outcalls.
79    CryptoQuoteAssetNotFound,
80    /// Returned when the stablecoin rates are not found from the exchanges HTTP outcalls needed for computing a crypto/fiat pair.
81    StablecoinRateNotFound,
82    /// Returned when there are not enough stablecoin rates to determine the forex/USDT rate.
83    StablecoinRateTooFewRates,
84    /// Returned when the stablecoin rate is zero.
85    StablecoinRateZeroRate,
86    /// Returned when a rate for the provided forex asset could not be found at the provided timestamp.
87    ForexInvalidTimestamp,
88    /// Returned when the forex base asset is found.
89    ForexBaseAssetNotFound,
90    /// Returned when the forex quote asset is found.
91    ForexQuoteAssetNotFound,
92    /// Returned when neither forex asset is found.
93    ForexAssetsNotFound,
94    /// Returned when the caller is not the CMC and there are too many active requests.
95    RateLimited,
96    /// Returned when the caller does not send enough cycles to make a request.
97    NotEnoughCycles,
98    /// Returned if too many collected rates deviate substantially.
99    InconsistentRatesReceived,
100    /// Until candid bug is fixed, new errors after launch will be placed here.
101    Other(OtherError),
102}
103
104/// Used to provide details for the [ExchangeRateError::Other] variant field.
105#[derive(CandidType, Clone, Debug, Deserialize)]
106pub struct OtherError {
107    /// The identifier for the error that occurred.
108    pub code: u32,
109    /// A description of the error that occurred.
110    pub description: String,
111}
112
113/// Short-hand for returning the result of a `get_exchange_rate` request.
114pub type GetExchangeRateResult = Result<ExchangeRate, ExchangeRateError>;
ic_xrc_types/lib.rs

ic_xrc_types/
lib.rs
