Skip to content

Add Band Oracle docs #1509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Add Band Oracle docs #1509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
0fdddb2
Add band page
chasefleming Oct 10, 2025
f1af65a
Add table links
chasefleming Oct 10, 2025
1ab1f21
Add docs
chasefleming Oct 10, 2025
4f60eef
Remove
chasefleming Oct 10, 2025
fee6e12
Fix links
chasefleming Oct 10, 2025
9fabe14
Change link
chasefleming Oct 10, 2025
cd79bcc
CHange heading
chasefleming Oct 10, 2025
425a4da
Add DM link
chasefleming Oct 10, 2025
54a29b9
Add increment fi docs
chasefleming Oct 10, 2025
24e75b2
Add KP docs
chasefleming Oct 10, 2025
8f7c3d5
Update docs/ecosystem/defi-liquidity/band-oracle.md
chasefleming Oct 10, 2025
fed27f5
Update docs/ecosystem/defi-liquidity/band-oracle.md
chasefleming Oct 10, 2025
7e52ad0
Update
chasefleming Oct 10, 2025
0149489
Merge branch 'cf/band-docs' of https://github.com/onflow/docs into cf…
chasefleming Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 283 additions & 0 deletions docs/ecosystem/defi-liquidity/band-oracle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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` | <CopyButton text="flow dependencies install testnet://0x9fb6606c300b5051.BandOracle" title="Copy install command (testnet)" /> | [View Contract](https://testnet.flowscan.io/contract/A.9fb6606c300b5051.BandOracle) |
| Mainnet | `0x6801a6222ebf784a` | <CopyButton text="flow dependencies install mainnet://0x6801a6222ebf784a.BandOracle" title="Copy install command (mainnet)" /> | [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<auth(FungibleToken.Withdraw) &FlowToken.Vault>(
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.
57 changes: 30 additions & 27 deletions docs/ecosystem/defi-liquidity/defi-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` | <CopyButton text="flow dependencies install mainnet://0xb063c16cac85dbd1.SwapFactory" title="Copy install command (mainnet)" /> |
| [SwapPair (IncrementFi)][23] | `0xecbda466e7f191c7` | <CopyButton text="flow dependencies install mainnet://0xecbda466e7f191c7.SwapPair" title="Copy install command (mainnet)" /> |
| [SwapError (IncrementFi)][24] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapError" title="Copy install command (mainnet)" /> |
| [SwapInterfaces (IncrementFi)][25] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapInterfaces" title="Copy install command (mainnet)" /> |
| [SwapConfig (IncrementFi)][26] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapConfig" title="Copy install command (mainnet)" /> |
| [SwapRouter (IncrementFi)][27] | `0xa6850776a94e6551` | <CopyButton text="flow dependencies install mainnet://0xa6850776a94e6551.SwapRouter" title="Copy install command (mainnet)" /> |
| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs |
| ----------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| [SwapFactory.cdc (IncrementFi)][22] | `0xb063c16cac85dbd1` | <CopyButton text="flow dependencies install mainnet://0xb063c16cac85dbd1.SwapFactory" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [SwapPair (IncrementFi)][23] | `0xecbda466e7f191c7` | <CopyButton text="flow dependencies install mainnet://0xecbda466e7f191c7.SwapPair" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [SwapError (IncrementFi)][24] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapError" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [SwapInterfaces (IncrementFi)][25] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapInterfaces" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [SwapConfig (IncrementFi)][26] | `0xb78ef7afa52ff906` | <CopyButton text="flow dependencies install mainnet://0xb78ef7afa52ff906.SwapConfig" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [SwapRouter (IncrementFi)][27] | `0xa6850776a94e6551` | <CopyButton text="flow dependencies install mainnet://0xa6850776a94e6551.SwapRouter" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |

## Bridges & Cross-Chain Messaging

Expand Down Expand Up @@ -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` | <CopyButton text="flow dependencies install testnet://0x8232ce4a3aff4e94.PublicPriceOracle" title="Copy install command (testnet)" /> |
| [BandOracle.cdc (Band)][32] | `0x9fb6606c300b5051` | <CopyButton text="flow dependencies install testnet://0x9fb6606c300b5051.BandOracle" title="Copy install command (testnet)" /> |
| Contract Name | Flow Cadence Testnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs |
| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| [PublicPriceOracle.cdc (IncrementFi)][31] | `0x8232ce4a3aff4e94` | <CopyButton text="flow dependencies install testnet://0x8232ce4a3aff4e94.PublicPriceOracle" title="Copy install command (testnet)" /> | [Docs][incrementfi-doc] |
| [BandOracle.cdc (Band)][32] | `0x9fb6606c300b5051` | <CopyButton text="flow dependencies install testnet://0x9fb6606c300b5051.BandOracle" title="Copy install command (testnet)" /> | [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` | <CopyButton text="flow dependencies install mainnet://0xec67451f8a58216a.PublicPriceOracle" title="Copy install command (mainnet)" /> |
| [BandOracle.cdc (Band) Protocol][33] | `0x6801a6222ebf784a` | <CopyButton text="flow dependencies install mainnet://0x6801a6222ebf784a.BandOracle" title="Copy install command (mainnet)" /> |
| Contract Name | Flow Cadence Mainnet Address | [CLI](https://developers.flow.com/build/tools/flow-cli/dependency-manager) | Docs |
| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| [PublicPriceOracle.cdc (IncrementFi)][19] | `0xec67451f8a58216a` | <CopyButton text="flow dependencies install mainnet://0xec67451f8a58216a.PublicPriceOracle" title="Copy install command (mainnet)" /> | [Docs][incrementfi-doc] |
| [BandOracle.cdc (Band) Protocol][33] | `0x6801a6222ebf784a` | <CopyButton text="flow dependencies install mainnet://0x6801a6222ebf784a.BandOracle" title="Copy install command (mainnet)" /> | [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 |
| ------------------------------------------------------- | -------------------------------------------- |
Expand Down Expand Up @@ -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