From 0c73613d8601de226330542048977ecb037b3b86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Thu, 17 Jul 2025 20:23:50 -0300 Subject: [PATCH 1/9] Adds data-feed-proxy-combinators docs --- .../data-feed-proxy-combinators.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/dapps/integration/data-feed-proxy-combinators.md diff --git a/docs/dapps/integration/data-feed-proxy-combinators.md b/docs/dapps/integration/data-feed-proxy-combinators.md new file mode 100644 index 00000000..48662dcf --- /dev/null +++ b/docs/dapps/integration/data-feed-proxy-combinators.md @@ -0,0 +1,30 @@ +--- +title: data-feed-proxy-combinators +pageHeader: dApps → Integration +--- + + + +# `data-feed-proxy-combinators` + +The [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository provides a powerful toolkit of modular smart contracts. These "combinators" allow you to create new, customized data feeds by transforming and combining existing Api3 dAPIs or even external data feeds. This is particularly useful when your dApp requires a data feed that is not directly available on the Api3 Market. + +## Core Components + +The repository offers a suite of composable proxy contracts. You can chain these together to build complex data feed pipelines. The primary contracts include: + +- **`InverseApi3ReaderProxyV1.sol`**: Computes the inverse of a data feed's value (e.g., converting ETH/USD to USD/ETH). +- **`ProductApi3ReaderProxyV1.sol`**: Multiplies the values of two data feeds to derive a new cross-rate (e.g., `(A/B) * (B/C) = A/C`). +- **`PriceCappedApi3ReaderProxyV1.sol`**: Enforces a price ceiling and/or floor on a data feed's value. +- **`NormalizedApi3ReaderProxyV1.sol`**: Adapts an external feed using the Chainlink `AggregatorV2V3Interface` interface to the Api3 `IApi3ReaderProxy` interface, normalizing its value to 18 decimals. +- **`ScaledApi3FeedProxyV1.sol`**: An adapter that changes the decimal precision of a data feed and exposes it via the standard `AggregatorV2V3Interface` interface. + +## Usage and Examples + +For comprehensive instructions on how to use and deploy these contracts, including practical use-case scenarios, please refer to the [`README.md`](https://github.com/api3dao/data-feed-proxy-combinators/blob/main/README.md) file. + +::: info ℹ️ Source of Truth + +The Solidity contracts located in the `contracts/` directory of the repository are the ultimate source of truth for implementation details. + +::: From 2163a27f67a939a4403a99f43509265e65b9872f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Thu, 17 Jul 2025 20:58:48 -0300 Subject: [PATCH 2/9] Adds data-feed-proxy-combinators sidebar link --- docs/dapps/sidebar.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/dapps/sidebar.js b/docs/dapps/sidebar.js index e20f030b..52464e1d 100644 --- a/docs/dapps/sidebar.js +++ b/docs/dapps/sidebar.js @@ -24,6 +24,10 @@ module.exports = [ text: '@api3/contracts', link: '/dapps/integration/api3-contracts', }, + { + text: 'data-feed-proxy-combinators', + link: '/dapps/integration/data-feed-proxy-combinators', + }, { text: 'Security considerations', link: '/dapps/integration/security-considerations', From 5768fc5ffe2ccc799ca4456cb7cdac7065f58aa6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Fri, 18 Jul 2025 10:36:32 -0300 Subject: [PATCH 3/9] Applies suggestions from PR --- .../integration/data-feed-proxy-combinators.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/dapps/integration/data-feed-proxy-combinators.md b/docs/dapps/integration/data-feed-proxy-combinators.md index 48662dcf..4c8c6161 100644 --- a/docs/dapps/integration/data-feed-proxy-combinators.md +++ b/docs/dapps/integration/data-feed-proxy-combinators.md @@ -7,24 +7,18 @@ pageHeader: dApps → Integration # `data-feed-proxy-combinators` -The [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository provides a powerful toolkit of modular smart contracts. These "combinators" allow you to create new, customized data feeds by transforming and combining existing Api3 dAPIs or even external data feeds. This is particularly useful when your dApp requires a data feed that is not directly available on the Api3 Market. +The [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository provides a powerful toolkit of modular smart contracts. These "combinators" allow you to create new, customized data feeds by transforming and combining existing Api3 feeds or even external data feeds. This is particularly useful when your dApp requires a data feed that is not directly available on the Api3 Market. ## Core Components -The repository offers a suite of composable proxy contracts. You can chain these together to build complex data feed pipelines. The primary contracts include: +The repository offers the following suite of composable contracts: - **`InverseApi3ReaderProxyV1.sol`**: Computes the inverse of a data feed's value (e.g., converting ETH/USD to USD/ETH). -- **`ProductApi3ReaderProxyV1.sol`**: Multiplies the values of two data feeds to derive a new cross-rate (e.g., `(A/B) * (B/C) = A/C`). +- **`ProductApi3ReaderProxyV1.sol`**: Multiplies the values of two data feeds to derive a new cross-rate (e.g., multiplying "wstETH/stETH Exchange Rate" with ETH/USD feed to get wstETH/USD). - **`PriceCappedApi3ReaderProxyV1.sol`**: Enforces a price ceiling and/or floor on a data feed's value. - **`NormalizedApi3ReaderProxyV1.sol`**: Adapts an external feed using the Chainlink `AggregatorV2V3Interface` interface to the Api3 `IApi3ReaderProxy` interface, normalizing its value to 18 decimals. - **`ScaledApi3FeedProxyV1.sol`**: An adapter that changes the decimal precision of a data feed and exposes it via the standard `AggregatorV2V3Interface` interface. ## Usage and Examples -For comprehensive instructions on how to use and deploy these contracts, including practical use-case scenarios, please refer to the [`README.md`](https://github.com/api3dao/data-feed-proxy-combinators/blob/main/README.md) file. - -::: info ℹ️ Source of Truth - -The Solidity contracts located in the `contracts/` directory of the repository are the ultimate source of truth for implementation details. - -::: +The usage and examples are documented in the [`README.md`](https://github.com/api3dao/data-feed-proxy-combinators/blob/main/README.md) of the repository. From d35d8009ff156d752c374e5535912628fbf6219d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Mon, 21 Jul 2025 10:54:51 -0300 Subject: [PATCH 4/9] Removes sidebar link to data-feed-proxy-combinators.md --- docs/dapps/integration/api3-contracts.md | 4 ++++ docs/dapps/sidebar.js | 4 ---- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/dapps/integration/api3-contracts.md b/docs/dapps/integration/api3-contracts.md index 16e052e2..330c1bfa 100644 --- a/docs/dapps/integration/api3-contracts.md +++ b/docs/dapps/integration/api3-contracts.md @@ -23,3 +23,7 @@ Additionally, `@api3/contracts` provides a CLI command for printing OEV Rewards- [AggregatorV2V3Interface](/dapps/integration/aggregatorv2v3interface.md) is not exported from this package, since contracts using this interface must have already imported it from elsewhere. ::: + +## Advanced Usage: Combining Data Feeds + +The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds, which is useful when a specific data feed is not available on the Api3 Market. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. diff --git a/docs/dapps/sidebar.js b/docs/dapps/sidebar.js index 52464e1d..e20f030b 100644 --- a/docs/dapps/sidebar.js +++ b/docs/dapps/sidebar.js @@ -24,10 +24,6 @@ module.exports = [ text: '@api3/contracts', link: '/dapps/integration/api3-contracts', }, - { - text: 'data-feed-proxy-combinators', - link: '/dapps/integration/data-feed-proxy-combinators', - }, { text: 'Security considerations', link: '/dapps/integration/security-considerations', From ef4d16005ce825685f66fd5d7db9720a00eaead3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Mon, 21 Jul 2025 17:17:16 -0300 Subject: [PATCH 5/9] Moves data-feed-proxy-combintors.md link from api3-contracts-md to contract-integration.md --- docs/dapps/integration/api3-contracts.md | 4 ---- docs/dapps/integration/contract-integration.md | 4 ++++ 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/dapps/integration/api3-contracts.md b/docs/dapps/integration/api3-contracts.md index 330c1bfa..16e052e2 100644 --- a/docs/dapps/integration/api3-contracts.md +++ b/docs/dapps/integration/api3-contracts.md @@ -23,7 +23,3 @@ Additionally, `@api3/contracts` provides a CLI command for printing OEV Rewards- [AggregatorV2V3Interface](/dapps/integration/aggregatorv2v3interface.md) is not exported from this package, since contracts using this interface must have already imported it from elsewhere. ::: - -## Advanced Usage: Combining Data Feeds - -The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds, which is useful when a specific data feed is not available on the Api3 Market. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index ab10ac66..12b900cd 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -140,6 +140,10 @@ We recommend directing them to this page. ::: +## Combining Data Feeds + +The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds, which is useful when a specific data feed is not available on the Api3 Market. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. + ## Mixed oracle design Some dApps choose to mix oracle solutions, either by refusing service if they are not in consensus, or by using one primarily and deferring to another in case of inconsistency. From f89637e48c4fd5709d03e2d2a19e7b581ef8b892 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Tue, 22 Jul 2025 09:15:24 -0300 Subject: [PATCH 6/9] Minor adjustments to Combining data feeds --- docs/dapps/integration/contract-integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index 12b900cd..fadc24f2 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -140,9 +140,9 @@ We recommend directing them to this page. ::: -## Combining Data Feeds +## Combining data feeds -The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds, which is useful when a specific data feed is not available on the Api3 Market. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. +The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. ## Mixed oracle design From bf286229243633dbfdb56fa41ca62fa0418c7e1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Tue, 22 Jul 2025 10:02:30 -0300 Subject: [PATCH 7/9] Removes data-feed-proxy-combinators.md and redirects to README.md --- .../dapps/integration/contract-integration.md | 2 +- .../data-feed-proxy-combinators.md | 24 ------------------- 2 files changed, 1 insertion(+), 25 deletions(-) delete mode 100644 docs/dapps/integration/data-feed-proxy-combinators.md diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index fadc24f2..7d7c102f 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -142,7 +142,7 @@ We recommend directing them to this page. ## Combining data feeds -The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here.](/dapps/integration/data-feed-proxy-combinators.md) for more details. +The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here](https://github.com/api3dao/data-feed-proxy-combinators/blob/0beed2baa94a48b50841f4a5ae6aeaccfe4e6b8a/README.md) for more details. ## Mixed oracle design diff --git a/docs/dapps/integration/data-feed-proxy-combinators.md b/docs/dapps/integration/data-feed-proxy-combinators.md deleted file mode 100644 index 4c8c6161..00000000 --- a/docs/dapps/integration/data-feed-proxy-combinators.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: data-feed-proxy-combinators -pageHeader: dApps → Integration ---- - - - -# `data-feed-proxy-combinators` - -The [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository provides a powerful toolkit of modular smart contracts. These "combinators" allow you to create new, customized data feeds by transforming and combining existing Api3 feeds or even external data feeds. This is particularly useful when your dApp requires a data feed that is not directly available on the Api3 Market. - -## Core Components - -The repository offers the following suite of composable contracts: - -- **`InverseApi3ReaderProxyV1.sol`**: Computes the inverse of a data feed's value (e.g., converting ETH/USD to USD/ETH). -- **`ProductApi3ReaderProxyV1.sol`**: Multiplies the values of two data feeds to derive a new cross-rate (e.g., multiplying "wstETH/stETH Exchange Rate" with ETH/USD feed to get wstETH/USD). -- **`PriceCappedApi3ReaderProxyV1.sol`**: Enforces a price ceiling and/or floor on a data feed's value. -- **`NormalizedApi3ReaderProxyV1.sol`**: Adapts an external feed using the Chainlink `AggregatorV2V3Interface` interface to the Api3 `IApi3ReaderProxy` interface, normalizing its value to 18 decimals. -- **`ScaledApi3FeedProxyV1.sol`**: An adapter that changes the decimal precision of a data feed and exposes it via the standard `AggregatorV2V3Interface` interface. - -## Usage and Examples - -The usage and examples are documented in the [`README.md`](https://github.com/api3dao/data-feed-proxy-combinators/blob/main/README.md) of the repository. From ab91f13a229d7381ceb544dc451825a16cc13b5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Wed, 23 Jul 2025 14:42:27 -0300 Subject: [PATCH 8/9] Update docs/dapps/integration/contract-integration.md Co-authored-by: Burak Benligiray --- docs/dapps/integration/contract-integration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index 7d7c102f..9f520f02 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -140,10 +140,10 @@ We recommend directing them to this page. ::: -## Combining data feeds - -The `data-feed-proxy-combinators` repository offers modular smart contracts for creating customized data feeds. These can be formed by transforming and combining existing feeds. This allows dApps to integrate highly specific or composite data requirements directly into their smart contracts. See [here](https://github.com/api3dao/data-feed-proxy-combinators/blob/0beed2baa94a48b50841f4a5ae6aeaccfe4e6b8a/README.md) for more details. +## Api3ReaderProxyV1 combinations +See the [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository for various modular contracts that you can use to create combinations out of Api3ReaderProxyV1 contracts. +For example, you can combine an `ETH/USD` Api3ReaderProxyV1 contract and a `wstETH/ETH Exchange Rate` Api3ReaderProxyV1 contract to read a `wstETH/USD` value. ## Mixed oracle design Some dApps choose to mix oracle solutions, either by refusing service if they are not in consensus, or by using one primarily and deferring to another in case of inconsistency. From 7cf84bca81f631e8330fa5de70b1799a49210cb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santiago=20Ace=C3=B1olaza?= Date: Wed, 23 Jul 2025 14:46:48 -0300 Subject: [PATCH 9/9] Format --- docs/dapps/integration/contract-integration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index 9f520f02..ffde65c0 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -144,6 +144,7 @@ We recommend directing them to this page. See the [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository for various modular contracts that you can use to create combinations out of Api3ReaderProxyV1 contracts. For example, you can combine an `ETH/USD` Api3ReaderProxyV1 contract and a `wstETH/ETH Exchange Rate` Api3ReaderProxyV1 contract to read a `wstETH/USD` value. + ## Mixed oracle design Some dApps choose to mix oracle solutions, either by refusing service if they are not in consensus, or by using one primarily and deferring to another in case of inconsistency.