Difference between revisions of "Exchange rate canister"
| Line 18: | Line 18: | ||
base_asset: Asset; | base_asset: Asset; | ||
quote_asset: Asset; | quote_asset: Asset; | ||
| − | |||
timestamp: opt nat64; | timestamp: opt nat64; | ||
}; | }; | ||
| Line 25: | Line 24: | ||
type GetExchangeRateResult = variant { | type GetExchangeRateResult = variant { | ||
| − | |||
Ok: ExchangeRate; | Ok: ExchangeRate; | ||
| − | |||
Err: ExchangeRateError; | Err: ExchangeRateError; | ||
}; | }; | ||
The full candid file can be found [https://github.com/dfinity/exchange-rate-canister/blob/main/src/xrc/xrc.did here]. | The full candid file can be found [https://github.com/dfinity/exchange-rate-canister/blob/main/src/xrc/xrc.did here]. | ||
| + | |||
| + | For every request, 10B cycles need to be sent along, otherwise an <code>ExchangeRateError::NotEnoughCycles</code> error is returned. The actual cost of the call depends two factors, the requested asset types and the state of the internal exchange rate cache, as follows: | ||
| + | |||
| + | * If the request can be served from the cache, the actual cost is only 200M cycles. | ||
| + | * If both assets are fiat currencies, the cost is 200M cycles as well. | ||
| + | * If one of the assets is a fiat currency, the cost is 2.6B cycles. | ||
| + | * If both assets are cryptocurrencies, the cost is 5B cycles. | ||
| + | |||
| + | The remaining cycles are returned to the requesting canister. Note that at least 10M cycles are charged even in case of an error in order to mitigate the risk of a denial-of-service attack. | ||
| + | |||
| + | == Technical Details == | ||
| + | |||
| + | [[File:XRC.png|thumb|Overview of the exchange rate canister work flow]] | ||
Revision as of 11:23, 13 January 2023
Overview
The exchange rate canister (XRC) is a canister running on the uzr34 system subnet that provides exchange rates to requesting canisters. A request comprises a base asset, a quote asset, and an optional (UNIX epoch) timestamp. The base and quote asset can be any combination of cryptocurrency and fiat currency assets, for example, BTC/ICP, ICP/USD, or USD/EUR. The timestamp parameter makes it possible to request historic rates. If no timestamp is provided in the request, the rate for the current time is returned.
The XRC constitutes an on-chain oracle for exchange rates, which is particularly useful for DeFi applications but can further add value to any application that requires exchange rate information.
The cycle minting canister of the NNS will make use of the XRC to obtain up-to-date ICP/XDR rates, which it requires for the conversion of ICP to cycles.
Usage
The canister ID of the XRC is uf6dk-hyaaa-aaaaq-qaaaq-cai.
It A request of the form
type GetExchangeRateRequest = record {
base_asset: Asset;
quote_asset: Asset;
timestamp: opt nat64;
};
can be sent to the XRC, which replies with the following result:
type GetExchangeRateResult = variant {
Ok: ExchangeRate;
Err: ExchangeRateError;
};
The full candid file can be found here.
For every request, 10B cycles need to be sent along, otherwise an ExchangeRateError::NotEnoughCycles error is returned. The actual cost of the call depends two factors, the requested asset types and the state of the internal exchange rate cache, as follows:
- If the request can be served from the cache, the actual cost is only 200M cycles.
- If both assets are fiat currencies, the cost is 200M cycles as well.
- If one of the assets is a fiat currency, the cost is 2.6B cycles.
- If both assets are cryptocurrencies, the cost is 5B cycles.
The remaining cycles are returned to the requesting canister. Note that at least 10M cycles are charged even in case of an error in order to mitigate the risk of a denial-of-service attack.
