diff --git a/docs/ecosystem/defi-liquidity/band-oracle.md b/docs/ecosystem/defi-liquidity/band-oracle.md new file mode 100644 index 0000000000..08f3a6eb2b --- /dev/null +++ b/docs/ecosystem/defi-liquidity/band-oracle.md @@ -0,0 +1,283 @@ +--- +id: band-oracle +title: Band Oracle on Flow +description: Band Protocol provides decentralized oracle services on Flow, delivering real-time price feeds and data for DeFi applications. +keywords: + - Band Oracle + - Band Protocol + - oracle + - price feeds + - data feeds + - DeFi + - Flow blockchain + - Flow Cadence + - smart contracts +sidebar_position: 6 +sidebar_label: Band Oracle +--- + +import CopyButton from '@site/src/components/CopyButton'; + +# Band Oracle with Cadence + +The Band Protocol Oracle contract enables Flow blockchain applications to access real-time price data from the [Band Protocol Oracle network](https://faq.bandprotocol.com/). The oracle provides a comprehensive set of cryptocurrency and fiat currency price quotes from the Band Standard Dataset, making them available to any Cadence application, contract, or transaction. + +## Contract Addresses + +| Network | Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Explorer | +|---------|---------|----------|----------| +| Testnet | `0x9fb6606c300b5051` | | [View Contract](https://testnet.flowscan.io/contract/A.9fb6606c300b5051.BandOracle) | +| Mainnet | `0x6801a6222ebf784a` | | [View Contract](https://flowscan.io/contract/A.6801a6222ebf784a.BandOracle) | + +## Supported Symbols + +### Cryptocurrency Pairs (against USD) +- **Major**: ETH, FLOW, USDC, USDT, WBTC, BNB, XRP, ADA, DOGE, POL (MATIC) +- **Layer 1**: SOL, DOT, AVAX, ATOM, XLM, TRX, SUI +- **DeFi**: AAVE, LINK, CRV, OP, UNI, SUSHI, CAKE, DYDX, 1INCH, BAT +- **Others**: LTC, SHIB, DAI, FTM + +### Fiat Currency Pairs (against USD) +- **Asian**: KRW, INR, HKD, TWD, THB, JPY, MYR, PHP, CNY, SGD +- **European**: PLN, CZK, EUR, GBP, CHF, RUB, SEK, TRY +- **Americas**: BRL, CAD +- **Oceanic**: AUD, NZD + +## How It Works + +### Architecture + +The Band Oracle contract maintains a decentralized price feed system with three key components: + +1. **Data Storage**: Price data is stored in a contract-level dictionary `symbolsRefData: {String: RefData}` where each symbol maps to its latest price information. + +2. **Data Updates**: Authorized BandChain relayers continuously update price data from the Band Protocol network to keep prices current. + +3. **Data Access**: Any user or contract can query the latest price data through public functions, enabling real-time price integrations. + +### Data Structure + +Price data is stored using the `RefData` struct: + +```cadence +access(all) struct RefData { + // USD-rate, multiplied by 1e9 + access(all) var rate: UInt64 + // UNIX epoch when data was last resolved + access(all) var timestamp: UInt64 + // BandChain request identifier for this data + access(all) var requestID: UInt64 +} +``` + +When querying prices, you receive a `ReferenceData` struct: + +```cadence +access(all) struct ReferenceData { + // Rate as integer multiplied by 1e18 + access(all) var integerE18Rate: UInt256 + // Rate as a fixed-point decimal + access(all) var fixedPointRate: UFix64 + // Timestamp of base symbol data + access(all) var baseTimestamp: UInt64 + // Timestamp of quote symbol data + access(all) var quoteTimestamp: UInt64 +} +``` + +### Data Normalization + +All price data is stored with a USD conversion rate. When you query for price conversions between two non-USD symbols, the contract derives the rate from their respective USD rates. For example, to get ETH/EUR, the contract calculates: `(ETH/USD) / (EUR/USD)`. + +## Features + +### Price Queries +- Query any supported symbol pair in real-time +- Get both integer (e18 precision) and fixed-point decimal rates +- Access timestamp information to verify data freshness +- Track BandChain request IDs for transparency + +### Fee Structure +- Configurable fee system for oracle usage (currently set to zero) +- Fee collected in FLOW tokens +- Query current fee using `BandOracle.getFee()` + +### Event Monitoring +The contract emits events to notify applications of updates: + +```cadence +// Emitted when symbol prices are updated +access(all) event BandOracleSymbolsUpdated( + symbols: [String], + relayerID: UInt64, + requestID: UInt64 +) + +// Emitted when a symbol is removed +access(all) event BandOracleSymbolRemoved(symbol: String) +``` + +## Usage Guide + +### Basic Price Query (Transaction) + +To query price data from a transaction: + +```cadence +import "BandOracle" +import "FlowToken" +import "FungibleToken" + +transaction(baseSymbol: String, quoteSymbol: String) { + + let payment: @{FungibleToken.Vault} + + prepare(acct: auth(BorrowValue) &Account) { + // Borrow reference to user's FLOW vault + let vaultRef = acct.storage.borrow( + from: /storage/flowTokenVault + ) ?? panic("Cannot borrow reference to signer's FLOW vault") + + // Withdraw payment for oracle fee + self.payment <- vaultRef.withdraw(amount: BandOracle.getFee()) + } + + execute { + // Get reference data + let priceData = BandOracle.getReferenceData( + baseSymbol: baseSymbol, + quoteSymbol: quoteSymbol, + payment: <- self.payment + ) + + log("Rate (fixed-point): ".concat(priceData.fixedPointRate.toString())) + log("Rate (integer e18): ".concat(priceData.integerE18Rate.toString())) + log("Base timestamp: ".concat(priceData.baseTimestamp.toString())) + log("Quote timestamp: ".concat(priceData.quoteTimestamp.toString())) + } +} +``` + +### Example: ETH/USD Price +```cadence +// Get ETH price in USD +let priceData = BandOracle.getReferenceData( + baseSymbol: "ETH", + quoteSymbol: "USD", + payment: <- flowPayment +) +// priceData.fixedPointRate contains ETH price in USD +``` + +### Example: Cross-Currency Conversion +```cadence +// Get EUR price in JPY +let priceData = BandOracle.getReferenceData( + baseSymbol: "EUR", + quoteSymbol: "JPY", + payment: <- flowPayment +) +// priceData.fixedPointRate contains EUR/JPY exchange rate +``` + +### Contract Integration + +Here's how to integrate the oracle into your smart contract: + +```cadence +import "BandOracle" +import "FlowToken" +import "FungibleToken" + +access(all) contract MyDeFiContract { + + // Store a vault to pay for oracle fees + access(self) let oracleFeeVault: @{FungibleToken.Vault} + + access(all) fun getTokenPriceInUSD(tokenSymbol: String): UFix64 { + // Withdraw payment for oracle + let payment <- self.oracleFeeVault.withdraw( + amount: BandOracle.getFee() + ) + + // Query the oracle + let priceData = BandOracle.getReferenceData( + baseSymbol: tokenSymbol, + quoteSymbol: "USD", + payment: <- payment + ) + + return priceData.fixedPointRate + } + + access(all) fun swapTokens(amount: UFix64, maxPrice: UFix64) { + // Get current price + let currentPrice = self.getTokenPriceInUSD(tokenSymbol: "ETH") + + // Verify price is acceptable + if currentPrice > maxPrice { + panic("Price too high") + } + + // Proceed with swap logic... + } + + init() { + // Initialize vault for oracle fees + self.oracleFeeVault <- FlowToken.createEmptyVault( + vaultType: Type<@FlowToken.Vault>() + ) + } +} +``` + +## Best Practices + +### 1. Listen for Price Updates + +Monitor the `BandOracleSymbolsUpdated` event to keep your contract's stored prices up-to-date: + +```cadence +// Listen for this event in your application +access(all) event BandOracleSymbolsUpdated( + symbols: [String], + relayerID: UInt64, + requestID: UInt64 +) +``` + +When you detect an update for symbols your app uses, trigger a transaction to refresh your stored prices. + + +## Advanced Features + +### Converting Between Number Formats + +The contract provides a utility function to convert between integer and fixed-point representations: + +```cadence +// Convert e18 integer to fixed-point decimal +let fixedPoint = BandOracle.e18ToFixedPoint(rate: integerE18Rate) +``` + +### Fee Management + +For contract administrators, the oracle supports dynamic fee configuration: + +```cadence +// Query current fee +let currentFee = BandOracle.getFee() + +// Fee can be updated by the fee collector (admin only) +// feeCollector.setFee(fee: 0.001) // 0.001 FLOW per query +``` + +## Resources + +- [Band Protocol FAQ](https://faq.bandprotocol.com/) +- [Band Standard Dataset](https://data.bandprotocol.com/) +- [Cadence Language Reference](https://cadence-lang.org/) + +--- + +**Note**: The oracle currently charges no fees for usage, but this may change in the future. Always check `BandOracle.getFee()` before querying to ensure your contract has sufficient FLOW tokens allocated. diff --git a/docs/ecosystem/defi-liquidity/defi-contracts.md b/docs/ecosystem/defi-liquidity/defi-contracts.md index 34b58ced78..7084fa2cab 100644 --- a/docs/ecosystem/defi-liquidity/defi-contracts.md +++ b/docs/ecosystem/defi-liquidity/defi-contracts.md @@ -38,26 +38,26 @@ Below is a list of commonly used DeFi contracts on Flow: #### Flow EVM Mainnet -| Contract Name | Flow EVM Mainnet Address | -| -------------------------------------------- | -------------------------------------------- | -| [StableKittyFactoryNG.sol (KittyPunch)][1] | `0x4412140D52C1F5834469a061927811Abb6026dB7` | -| [TwoKittyFactory.sol (KittyPunch)][2] | `0xf0E48dC92f66E246244dd9F33b02f57b0E69fBa9` | -| [TriKittyFactory.sol (KittyPunch)][3] | `0xebd098c60b1089f362AC9cfAd9134CBD29408226` | -| [KittyRouterNgPoolsOnly.sol (KittyPunch)][4] | `0x87048a97526c4B66b71004927D24F61DEFcD6375` | -| [PunchSwapV2Router02.sol (KittyPunch)][5] | `0xf45AFe28fd5519d5f8C1d4787a4D5f724C0eFa4d` | -| [PunchSwapV2Factory.sol (KittyPunch)][6] | `0x29372c22459a4e373851798bFd6808e71EA34A71` | -| [TrenchesTokensBuyer.sol (KittyPunch)][7] | `0x6D0e081Acc28eA9ee6b7fD293eC03F97147b026d` | +| Contract Name | Flow EVM Mainnet Address | Docs | +| -------------------------------------------- | -------------------------------------------- | --------------------- | +| [StableKittyFactoryNG.sol (KittyPunch)][1] | `0x4412140D52C1F5834469a061927811Abb6026dB7` | [Docs][kittypunch-doc] | +| [TwoKittyFactory.sol (KittyPunch)][2] | `0xf0E48dC92f66E246244dd9F33b02f57b0E69fBa9` | [Docs][kittypunch-doc] | +| [TriKittyFactory.sol (KittyPunch)][3] | `0xebd098c60b1089f362AC9cfAd9134CBD29408226` | [Docs][kittypunch-doc] | +| [KittyRouterNgPoolsOnly.sol (KittyPunch)][4] | `0x87048a97526c4B66b71004927D24F61DEFcD6375` | [Docs][kittypunch-doc] | +| [PunchSwapV2Router02.sol (KittyPunch)][5] | `0xf45AFe28fd5519d5f8C1d4787a4D5f724C0eFa4d` | [Docs][kittypunch-doc] | +| [PunchSwapV2Factory.sol (KittyPunch)][6] | `0x29372c22459a4e373851798bFd6808e71EA34A71` | [Docs][kittypunch-doc] | +| [TrenchesTokensBuyer.sol (KittyPunch)][7] | `0x6D0e081Acc28eA9ee6b7fD293eC03F97147b026d` | [Docs][kittypunch-doc] | #### Flow Cadence Mainnet -| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | -| ----------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| [SwapFactory.cdc (IncrementFi)][22] | `0xb063c16cac85dbd1` | | -| [SwapPair (IncrementFi)][23] | `0xecbda466e7f191c7` | | -| [SwapError (IncrementFi)][24] | `0xb78ef7afa52ff906` | | -| [SwapInterfaces (IncrementFi)][25] | `0xb78ef7afa52ff906` | | -| [SwapConfig (IncrementFi)][26] | `0xb78ef7afa52ff906` | | -| [SwapRouter (IncrementFi)][27] | `0xa6850776a94e6551` | | +| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs | +| ----------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| [SwapFactory.cdc (IncrementFi)][22] | `0xb063c16cac85dbd1` | | [Docs][incrementfi-doc] | +| [SwapPair (IncrementFi)][23] | `0xecbda466e7f191c7` | | [Docs][incrementfi-doc] | +| [SwapError (IncrementFi)][24] | `0xb78ef7afa52ff906` | | [Docs][incrementfi-doc] | +| [SwapInterfaces (IncrementFi)][25] | `0xb78ef7afa52ff906` | | [Docs][incrementfi-doc] | +| [SwapConfig (IncrementFi)][26] | `0xb78ef7afa52ff906` | | [Docs][incrementfi-doc] | +| [SwapRouter (IncrementFi)][27] | `0xa6850776a94e6551` | | [Docs][incrementfi-doc] | ## Bridges & Cross-Chain Messaging @@ -102,30 +102,30 @@ Below is a list of commonly used DeFi contracts on Flow: #### Flow Cadence Testnet -| Contract Name | Flow Cadence Testnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | -| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| [PublicPriceOracle.cdc (IncrementFi)][31] | `0x8232ce4a3aff4e94` | | -| [BandOracle.cdc (Band)][32] | `0x9fb6606c300b5051` | | +| Contract Name | Flow Cadence Testnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs | +| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [PublicPriceOracle.cdc (IncrementFi)][31] | `0x8232ce4a3aff4e94` | | [Docs][incrementfi-doc] | +| [BandOracle.cdc (Band)][32] | `0x9fb6606c300b5051` | | [Docs][band-oracle-doc] | #### Flow Cadence Mainnet -| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | -| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| [PublicPriceOracle.cdc (IncrementFi)][19] | `0xec67451f8a58216a` | | -| [BandOracle.cdc (Band) Protocol][33] | `0x6801a6222ebf784a` | | +| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs | +| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [PublicPriceOracle.cdc (IncrementFi)][19] | `0xec67451f8a58216a` | | [Docs][incrementfi-doc] | +| [BandOracle.cdc (Band) Protocol][33] | `0x6801a6222ebf784a` | | [Docs][band-oracle-doc] | ## Ethereum Attestation Service More information can be found on the Credora docs site for [EAS on Flow](https://credora.gitbook.io/eas-for-flow). -Testnet EAS Explorer: [https://flow-testnet.easscan.credora.io] (https://flow-testnet.easscan.credora.io) +Testnet EAS Explorer: [https://flow-testnet.easscan.credora.io](https://flow-testnet.easscan.credora.io) | Contract Name | Flow EVM Testnet Address | | ------------------------------------------------------- | -------------------------------------------- | | [SchemaRegistry.sol (Ethereum Attestation Service)][29] | `0x97900F59828Da4187607Cb8F84f49e3944199d18` | | [EAS.sol (Ethereum Attestation Service)][30] | `0xBCF2dA8f82fb032A2474c92Ec5b70C95A83fc0cc` | -Mainnet EAS Explorer: [https://flow.easscan.credora.io] (https://flow.easscan.credora.io) +Mainnet EAS Explorer: [https://flow.easscan.credora.io](https://flow.easscan.credora.io) | Contract Name | Flow EVM Mainnet Address | | ------------------------------------------------------- | -------------------------------------------- | @@ -169,3 +169,6 @@ Mainnet EAS Explorer: [https://flow.easscan.credora.io] (https://flow.easscan.cr [35]: https://docs.debridge.finance/dln-the-debridge-liquidity-network-protocol/deployed-contracts [36]: https://relay.link/bridge [37]: https://docs.relay.link/resources/contract-addresses +[band-oracle-doc]: ./band-oracle +[incrementfi-doc]: https://docs.increment.fi/ +[kittypunch-doc]: https://kittypunch.gitbook.io/kittypunch-docs