Skip to content

Commit 439dea0

Browse files
acenolazaacenolaza
committed
Adds user guide to README
1 parent 932714c commit 439dea0

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎README.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
Api3 delivers reliable, first-party oracle data via dAPIs (continuously updated data feeds). However, dApps often require this data in formats or derivations not directly provided by a base dAPI, such as inverted prices (e.g., USD/ETH from ETH/USD), scaled values, or new feeds derived from combining multiple dAPIs (e.g., BTC/ETH from BTC/USD and ETH/USD). Data Feed Proxy Combinators address this as (soon-to-be) audited, standardized, and reusable smart contracts. These combinators operate on top of existing `IApi3ReaderProxy` contracts, enabling developers to combine them or transform their output to read data in different formats or derive new data feeds on-chain. This approach avoids repetitive, error-prone, and gas-intensive custom logic within individual dApps and the impracticality of deploying new oracles for minor data variations, thereby enhancing code reuse and reliability.
88
Being documented, easily usable, and officially recommended by Api3, they offer a trusted and straightforward way for developers to implement these common data transformations.
99

10+
It's important to note that these combinator proxies are designed as lightweight wrappers. They do not perform additional validation on the data (e.g., value sanity checks or timestamp verification) returned by the underlying dAPIs or external feeds. The responsibility for data quality and timeliness rests with the source oracle or feed provider. Furthermore, these contracts are provided "as is" without any warranty, and there is no financial coverage or insurance associated with their use.
11+
1012
### Core Capabilities
1113

1214
Data Feed Proxy Combinators provide modular and composable smart contracts for on-chain data feed adaptation. They typically take the address(es) of underlying feed(s) and operational parameters (like scaling factors) in their constructors. Key contract implementations include:
@@ -18,6 +20,183 @@ Data Feed Proxy Combinators provide modular and composable smart contracts for o
1820

1921
These combinators either consume and expose the Api3 `IApi3ReaderProxy` interface or act as adapters to/from other interfaces like Chainlink's `AggregatorV3Interface`. This facilitates integration within the Api3 ecosystem or when bridging with other oracle systems. The output of one combinator can often serve as input for another, enabling complex data transformation pipelines.
2022

23+
## Deployment Guide
24+
25+
This guide provides step-by-step instructions for dApp developers who need to deploy and use these Data Feed Proxy Combinator contracts.
26+
27+
### 1. Prerequisites
28+
29+
- **Clone the Repository**:
30+
```bash
31+
git clone https://github.com/api3dao/data-feed-proxy-combinators.git
32+
cd data-feed-proxy-combinators
33+
```
34+
- **Install Dependencies**: This project uses `pnpm` as the package manager.
35+
```bash
36+
pnpm install
37+
```
38+
39+
### 2. Environment Setup (.env file)
40+
41+
You'll need to set up a `.env` file in the root of the project to store a mnemonic, RPC provider URLs, and API keys for block explorers.
42+
43+
- Create a `.env` file by copying the example:
44+
45+
```bash
46+
cp .env.example .env
47+
```
48+
49+
Or create a `.env` file manually with the following content:
50+
51+
```env
52+
# Mnemonic of the account you want to use for deployment
53+
# IMPORTANT: Never commit this file to version control.
54+
MNEMONIC="your twelve word mnemonic phrase here"
55+
56+
# RPC Provider URLs. Only add these if you want to override the defaults provided
57+
# by @api3/contracts or for networks that require a specific URL.
58+
# The environment variable name must follow the pattern:
59+
# HARDHAT_HTTP_RPC_URL_<NETWORK_NAME_UPPERCASE_WITH_UNDERSCORES>
60+
# where <NETWORK_NAME_UPPERCASE_WITH_UNDERSCORES> corresponds to a network
61+
# name defined in @api3/contracts (e.g., ETHEREUM_SEPOLIA_TESTNET, ARBITRUM_MAINNET).
62+
63+
# Example for Sepolia testnet (replace with your actual provider URL):
64+
HARDHAT_HTTP_RPC_URL_ETHEREUM_SEPOLIA_TESTNET=https://sepolia.infura.io/v3/your_infura_project_id
65+
# Example for Arbitrum Mainnet (replace with your actual provider URL if needed):
66+
# HARDHAT_HTTP_RPC_URL_ARBITRUM_MAINNET=https://arb1.arbitrum.io/rpc
67+
68+
# API keys for block explorers. The @api3/contracts package configures Hardhat
69+
# to use these for contract verification on various networks (including those using
70+
# explorers like Polygonscan, Arbiscan, etc., not just Etherscan.io).
71+
# The environment variable name must follow the pattern:
72+
# ETHERSCAN_API_KEY_<NETWORK_NAME_UPPERCASE_WITH_UNDERSCORES>
73+
# where <NETWORK_NAME_UPPERCASE_WITH_UNDERSCORES> corresponds to a network
74+
# name defined in @api3/contracts (e.g., ETHEREUM_SEPOLIA_TESTNET, POLYGON_MAINNET).
75+
76+
# Example for Sepolia testnet:
77+
ETHERSCAN_API_KEY_ETHEREUM_SEPOLIA_TESTNET=your_etherscan_api_key_for_sepolia
78+
# Example for Polygon Mainnet:
79+
# ETHERSCAN_API_KEY_POLYGON_MAINNET=your_polygonscan_api_key
80+
# Example for Arbitrum Mainnet:
81+
# ETHERSCAN_API_KEY_ARBITRUM_MAINNET=your_arbiscan_api_key
82+
```
83+
84+
_Note: This repository uses Hardhat. The `hardhat.config.ts` file relies on these environment variables for proper configuration. Specifically, the `networks` and `etherscan` properties are automatically configured using helper functions from the [`@api3/contracts`](https://github.com/api3dao/contracts/blob/main/src/hardhat-config.ts) package._
85+
86+
### 3. Deploying Contracts
87+
88+
This repository uses `hardhat-deploy` for managing deployments. Each combinator contract has a corresponding deployment script.
89+
90+
To deploy a specific contract, you need to set the `NETWORK` environment variable and any contract-specific environment variables required by its deployment script. Then, use the corresponding `pnpm deploy:<ContractName>` script.
91+
92+
The `NETWORK` variable should be set to a chain name as defined by `@api3/contracts` (e.g., `ethereum-sepolia-testnet`, `polygon-mainnet`, `base-mainnet`). You can find a list of available chain names [here](https://github.com/api3dao/contracts/blob/main/src/generated/chains.ts).
93+
94+
**Required Environment Variables per Contract:**
95+
96+
- **`InverseApi3ReaderProxyV1`**:
97+
98+
- `NETWORK`: Target network name.
99+
- `PROXY`: Address of the underlying `IApi3ReaderProxy` contract (e.g., an ETH/USD dAPI proxy).
100+
- Example:
101+
```bash
102+
NETWORK=ethereum-sepolia-testnet PROXY=0xUnderlyingProxyAddress pnpm deploy:InverseApi3ReaderProxyV1
103+
```
104+
105+
- **`NormalizedApi3ReaderProxyV1`**:
106+
107+
- `NETWORK`: Target network name.
108+
- `FEED`: Address of the external data feed (e.g., a Chainlink `AggregatorV3Interface` compatible feed).
109+
- Example:
110+
```bash
111+
NETWORK=polygon-mainnet FEED=0xExternalFeedAddress pnpm deploy:NormalizedApi3ReaderProxyV1
112+
```
113+
114+
- **`ProductApi3ReaderProxyV1`**:
115+
116+
- `NETWORK`: Target network name.
117+
- `PROXY1`: Address of the first `IApi3ReaderProxy` contract.
118+
- `PROXY2`: Address of the second `IApi3ReaderProxy` contract.
119+
- Example:
120+
```bash
121+
NETWORK=arbitrum-mainnet PROXY1=0xProxy1Address PROXY2=0xProxy2Address pnpm deploy:ProductApi3ReaderProxyV1
122+
```
123+
124+
- **`ScaledApi3FeedProxyV1`**:
125+
- `NETWORK`: Target network name.
126+
- `PROXY`: Address of the underlying `IApi3ReaderProxy` contract.
127+
- `DECIMALS`: The desired number of decimals for the scaled output.
128+
- Example:
129+
```bash
130+
NETWORK=base-mainnet PROXY=0xUnderlyingProxyAddress DECIMALS=8 pnpm deploy:ScaledApi3FeedProxyV1
131+
```
132+
133+
_Note: The specific `pnpm deploy:<ContractName>` scripts for each combinator are defined in the `package.json` file._
134+
135+
**Deployment Artifacts**: After deployment, contract artifacts (including ABI and deployed address) are saved in the `deployments/<network_name>/` directory.
136+
For example, deploying `InverseApi3ReaderProxyV1` to the `ethereum-sepolia-testnet` network would create an artifact file like `deployments/ethereum-sepolia-testnet/InverseApi3ReaderProxyV1_SomeHash.json`. The `_SomeHash` part is derived from the constructor arguments, allowing multiple instances of the same contract with different configurations to be deployed and tracked.
137+
These artifact files contain the deployed contract address, ABI, and the constructor arguments used for deployment (look for the `"args"` array in the JSON file). This information is crucial for integration and manual verification if needed.
138+
139+
**Contract Verification**:
140+
The deployment scripts automatically attempt to verify the contract on the appropriate block explorer (e.g., Etherscan for Ethereum networks, Polygonscan for Polygon) after a successful deployment. This process uses the API keys (e.g., `ETHERSCAN_API_KEY_ETHEREUM_SEPOLIA_TESTNET`, `ETHERSCAN_API_KEY_POLYGON_MAINNET`) configured in your `.env` file, as described in "### 2. Environment Setup".
141+
If verification fails during the deployment (e.g., due to network latency or an explorer API issue), you can simply re-run the exact same deployment command. `hardhat-deploy` is idempotent; it will detect that the contract is already deployed with the same arguments and bytecode, skip the deployment step, and only re-attempt the verification.
142+
143+
### 4. Combining Contracts (Advanced Usage)
144+
145+
The true power of these combinators is realized when they are chained together. The deployed address of one combinator contract can serve as an input (a constructor argument, typically an `IApi3ReaderProxy` or `AggregatorV3Interface` address) for another. This allows you to build sophisticated data transformation pipelines tailored to your dApp's specific needs.
146+
147+
Below are some common scenarios illustrating how you can combine these proxies:
148+
149+
**Scenario 1: Inverting and Scaling a dAPI**
150+
151+
Imagine your dApp requires a USD/ETH price feed with 8 decimal places, but the available API3 dAPI provides ETH/USD with 18 decimals.
152+
153+
1. **Deploy `InverseApi3ReaderProxyV1`**:
154+
155+
- Input `PROXY`: Address of the ETH/USD `IApi3ReaderProxy` dAPI.
156+
- Output: An `IApi3ReaderProxy` contract (`InverseProxy_ETHUSD`) that reads USD/ETH.
157+
- Example command: `NETWORK=your_network PROXY=0xAddressOfEthUsdDapi pnpm deploy:InverseApi3ReaderProxyV1`
158+
159+
2. **Deploy `ScaledApi3FeedProxyV1`**:
160+
- Input `PROXY`: Address of `InverseProxy_ETHUSD` (from step 1).
161+
- Input `DECIMALS`: `8`.
162+
- Output: An `AggregatorV3Interface` contract that reads USD/ETH scaled to 8 decimals.
163+
- Example command: `NETWORK=your_network PROXY=0xAddressOfInverseProxyEthUsd DECIMALS=8 pnpm deploy:ScaledApi3FeedProxyV1`
164+
165+
**Scenario 2: Creating a Cross-Currency Pair (e.g., BTC/ETH) and Adapting its Interface**
166+
167+
Suppose your dApp needs a BTC/ETH price feed, and you have access to BTC/USD and ETH/USD dAPIs. You also want the final feed to be Chainlink-compatible.
168+
169+
1. **Deploy `InverseApi3ReaderProxyV1` for ETH/USD**:
170+
171+
- Input `PROXY`: Address of the ETH/USD `IApi3ReaderProxy` dAPI.
172+
- Output: An `IApi3ReaderProxy` contract (`InverseProxy_ETHUSD`) that reads USD/ETH.
173+
174+
2. **Deploy `ProductApi3ReaderProxyV1`**:
175+
176+
- Input `PROXY1`: Address of the BTC/USD `IApi3ReaderProxy` dAPI.
177+
- Input `PROXY2`: Address of `InverseProxy_ETHUSD` (from step 1).
178+
- Output: An `IApi3ReaderProxy` contract (`ProductProxy_BTCETH`) that reads BTC/ETH (calculated as BTC/USD \* USD/ETH).
179+
180+
3. **Deploy `ScaledApi3FeedProxyV1` (Optional, for interface adaptation and scaling)**:
181+
- Input `PROXY`: Address of `ProductProxy_BTCETH` (from step 2).
182+
- Input `DECIMALS`: Desired decimals (e.g., `8` or `18`).
183+
- Output: An `AggregatorV3Interface` contract providing the BTC/ETH price, compatible with systems expecting a Chainlink feed.
184+
185+
**Scenario 3: Normalizing an External Feed and Then Inverting It**
186+
187+
Your dApp wants to use an external (e.g., Chainlink) EUR/USD feed but requires it as USD/EUR and prefers to interact with it via the API3 `IApi3ReaderProxy` interface.
188+
189+
1. **Deploy `NormalizedApi3ReaderProxyV1`**:
190+
191+
- Input `FEED`: Address of the external EUR/USD `AggregatorV3Interface` feed.
192+
- Output: An `IApi3ReaderProxy` contract (`NormalizedProxy_EURUSD`) that reads EUR/USD.
193+
194+
2. **Deploy `InverseApi3ReaderProxyV1`**:
195+
- Input `PROXY`: Address of `NormalizedProxy_EURUSD` (from step 1).
196+
- Output: An `IApi3ReaderProxy` contract that reads USD/EUR.
197+
198+
When deploying a combinator that depends on another already deployed combinator, you will need the address of the prerequisite contract. You can find this address in the deployment artifact file (e.g., `deployments/<network_name>/<ContractName>_SomeHash.json`) generated in the previous step.
199+
21200
## Further Information
22201
23202
For detailed specifications of each combinator, including constructor arguments, public methods, and Natspec documentation, please consult the contract source code within this repository. Familiarity with the `IApi3ReaderProxy` interface from the `@api3/contracts` repository is also highly recommended for effective integration.

0 commit comments

Comments
 (0)