๐ฎ
Simulations & Forks
๐งฉ
Web3 Actions
๐
Alerts
๐
Debugger
๐
Analytics
How to Build a Custom Oracle
In this tutorial, weโll show you how to build a custom Web3 oracle using Tenderlyโs Web3 Actions. An oracle gathers data from real-world systems and sends it to the blockchain. It acts as an entry point for streaming data from Web2 applications toward smart contracts.
Using oracles, we can access data from sources outside the blockchain (e.g., exchanges, traffic and weather data, gas rates, oil prices, etc) from within our smart contracts.
Project Overview
The purpose of this project is to teach you how to build a Web3 Action that fetches data from a Web2 API whenever a smart contract makes a data request through an on-chain event. This data will then be sent to the contract that requested it.
Hereโs a quick breakdown of the projectโs flow.
- Create a Consumer โ a smart contract that requests the ETH price from an Oracle Contract.
- The Oracle Contract requests a new coin price from the CoinGecko API with the
RequestCoinPriceevent. - Once the price request has been observed, the Web3 Action is called to fetch the value.
- The price value is pushed back to the Oracle Contract.
We will use a pre-made smart contract for this project. Feel free to explore the code and play around with it in the Tenderly Sandbox and check out the Sandbox Docs.
Note that the
SimpleConsumer contract accepts the coinPrice coming in only from the CoinOracle it was assigned when it got deployed. Additionally, CoinOracle accepts updates only if it is signed by the same Wallet that deployed it (owner).The Plan
Hereโs a list of steps we weโll need to take to build our oracle:
- Deploy the
CoinOracleandSimpleCoinConsumersmart contracts. - Get the API key and other information needed to use one of the Ethereum providers. Weโll store this data in the Web3 Actions Secrets (needed for interaction 5).
- Get the Private Key of the account that deployed the Oracle Contract (
owner) and store it in the Web3 Actions Secrets (needed to sign transactions in interaction 5). - Initialize Tenderlyโs Web3 Actions directory on your dev environment and add npm dependencies.
- Create a Web3 Action that will send price updates to the oracle.
1: Deploy the Smart Contracts
Both
CoinOracle and SimpleCoinConsumer contracts are stored in the same file: CoinOracle.sol. Check out the source code in our GitHub repo.The
CoinOracle contact must be deployed first, before the SimpleCoinConsumer contract, preferably using a different Wallet. Make sure to pass the CoinOracle address as the constructor parameter.For the purpose of this tutorial, weโll deploy to the Ropsten test network (ID is 3) but youโre free to use a different one.
2: Initialize Web3 Actions
For this tutorial, youโll need access to the Tenderly Dashboard. If you donโt have an account, sign up here for free (no cc required as well).
Install the Tenderly CLI (follow this installation guide). With the Tenderly CLI installed on your machine, create a new directory
tdly-actions and cd into it to initialize your Web3 Actions using the tenderly actions init command.1
$ cd tdly-actions
2
$ tenderly actions init
Copied!
When prompted, select your Tenderly projects where you want to deploy Web3 Actions. List out the contents of the directory to explore the files created by the CLI:
1
$ ls actions
2
example.ts
3
tsconfig.json
4
package.json
Copied!
The Tenderly CLI will also create an npm project which will allow your Web3 Actions to use any npm package.
Install NPM dependencies - weโll use Axios to make requests to an external API and Ethers to interact with the blockchain. Run the following command from your terminal to add these dependencies to your npm project:
1
$ cd actions && npm install --save-dev axios ethers @types/node && cd ..
Copied!
3: Create Your Web3 Action
Before moving forward, copy the
CoinOracleContract.json file to the actions directory. You can find this JSON file in Remix or this GitHub repo.All files your Web3 Action code uses and references must be placed in the
actions directory (e.g. CoinOracleContract.json).Set the
CONTRACT_ADDRESS variable to the address of your deployed Oracle:1
import {
2
ActionFn, Context,
3
Event, TransactionEvent
4
} from '@tenderly/actions'
5
โ
6
import { ethers } from 'ethers';
7
โ
8
import CoinOracleContract from "./CoinOracleContract.json";
9
โ
10
const CONTRACT_ADDRESS = '...'; // replace with contract address
11
โ
12
export const coinPrice: ActionFn = async (context: Context, event: Event) => {
13
let transactionEvent = event as TransactionEvent
14
โ
15
const ifc = new ethers.utils.Interface(CoinOracleContract.abi)
16
โ
17
const { data, topics } = transactionEvent.logs[0]
18
const priceRequest = ifc.decodeEventLog("RequestCoinPrice", data, topics)
19
const price = await getPrice()
20
โ
21
const oc = await oracleContract(context, ifc)
22
โ
23
await oc.update(priceRequest.reqId, price, {
24
gasLimit: 250000,
25
gasPrice: ethers.utils.parseUnits('100', 'gwei'),
26
})
27
console.log(`Processed: ${priceRequest.reqId} with price in cents: ${price}`)
28
}
29
โ
30
const getPrice = async (coin: string) => {
31
const coinInfo = await axios.get(
32
`https://api.coingecko.com/api/v3/coins/${coin}`
33
);
34
return coinInfo.data.market_data.current_price.usd * 100;
35
};
36
โ
37
const oracleContract = async (context: Context, contractInterface: ethers.utils.Interface) => {
38
const etherscanApiKey = await context.secrets.get("oracle.providerApiKey");
39
โ
40
const provider = ethers.getDefaultProvider(
41
ethers.providers.getNetwork(3),
42
{ etherscan: etherscanApiKey }
43
);
44
โ
45
const oracleWallet = new ethers.Wallet(
46
await context.secrets.get("oracle.addressPrivateKey"),
47
provider
48
);
49
โ
50
const contract = new ethers.Contract(
51
CONTRACT_ADDRESS,
52
contractInterface,
53
oracleWallet
54
);
55
return contract;
56
}
Copied!
Our Web3 Action will make a call to a CoinGecko API using Axios in
getPrice. The result we get from the API will be the price in cents. Weโll send this data back to our smart contract.However, before moving forward, we have to take care of some plumbing.
Off-road: Deal with Typescript. If Typescript throws an error, add the following two lines to your
tsconfig.json file, under compilerOptions. This will stop Typescript from frowning upon us for importing a JSON file as an ES module.1
"esModuleInterop": true,
2
"resolveJsonModule": true
Copied!
Plumbing: Instantiate the Ethers Interface. The
CoinOracleContract.json file creates an Interface instance that Ethers uses to encode and decode data exchanged when interacting with smart contracts. Weโre passing the abi part of the entire JSON file.Get the Event Data. Use the
Interface we just created (ifc) to decodeEventLog. We know that the first log entry (logs[0]) corresponds to the RequestCoinPrice event, so this is the one we want to decode. In more complex interactions, you may need to do this dynamically like we did here.Necessary Web3 Plumbing aka Boilerplate. To interact with our Oracle Contract, we need to do some plumbing. The contract has a restriction - updates can be sent only by the
owner. This means we need to send transactions from the address that deployed it. The plumbing is done in the oracleContract function, and hereโs the breakdown of steps.Plumbing: Configure a Provider Object. We can obtain the provider using
ethers.getDefaultProvider to work with network 3 (Ropstenโs ID). Weโre also passing a second argument โ a configuration object which contains the API key. Consult ethers docs for more information on how to configure other providers and use alternatives like JsonRpcProvider.Plumbing: Create a Wallet. You need to create a
Wallet to ensure that each transaction originating from our oracle is signed and funded by the same address that deployed the contract. Since the Walletโs private key is sensitive information, weโre reading it from Secrets:await context.secrets.get("w3_oracle.oracle_address_private_key")Plumbing: Create a Contract. This is the step where we piece together everything weโve created so far:
Contractinstance by passingCONTRACT_ADDRESS.contractInterfacefor encoding data we want to send to the network.oracleWlletto sign the transaction.
๐ Send Data Back to the Oracle Contract. With the plumbing completed, the last line invokes the function
receiveWeatherUpdate and sends the prediction our oracle has come up with. This bit issues a transaction to our smart contract.4: Specify When Your Web3 Action Gets Executed
We want execute the transaction every time the
RequestCoinPrice event is fired by the OracleContract on the Ropsten network. We want to do this only after the transaction has been mined.Replace
YOUR_USERNAME and YOUR_PROJECT_SLUG with your Tenderly username and the slug of your project. You can copy those from the Dashboard URL: https://dashboard.tenderly.co/{YOUR_USERNAME}/{YOUR_PROJECT_SLUG}/transactionsAlso, replace
CONTRACT_ADDRESS with the address of your deployed Oracle Contract:1
account_id: ""
2
actions:
3
YOUR_USERNAME/YOUR_PROJECT_SLUG:
4
runtime: v1
5
sources: actions
6
specs:
7
coinOracle:
8
description: Swapit
9
function: coinOracle:coinPrice
10
trigger:
11
type: transaction
12
transaction:
13
status:
14
- mined
15
filters:
16
- network: 3
17
eventEmitted:
18
contract:
19
address: CONTRACT_ADDRESS
20
name: RequestCoinPrice
21
project_slug: ""
Copied!
5: Create Web3 Action Secrets
For Web3 Actions to perform operations on the deployed
OracleContract, we need a way to access the contract. You can choose any provider service (Infura, QuickNode, Alchemy, Etherscan, etc). Check Ethersโ Default Provider docs to find out whatโs needed to establish the access.Since weโre using Etherscan as the provider, we only need the API key. The key will be stored in Web3 Actions Secrets.
Keep all your sensitive data tucked away safely in the Web3 Actions Secrets (e.g., API keys, Wallet private keys, etc). Secrets are highly secure, so even if you try to
console.log the values, they will remain hidden.Secrets. Head over to your Tenderly Dashboard to place the private key you copied in Web3 Actions Secrets. From the sidebar, go to โActionsโ, click โSecretsโ, and then โAdd Newโ. Name the secret
oracle.providerApiKey and paste the API token as well as any other sensitive information you need.
Store Oracle Wallet Private Key. To send transactions to the chain, our Web3 Action needs to have a private key to sign transactions and fund them. The
OracleContract is designed to only accept updates that are signed by the address that deployed them.If youโre using Metamask, pick the account you used to deploy the smart contract and copy its private key following this Metamask guide.
In the Tenderly Dashboard, create a new Secret called
w3_oracle.oracle_address_private_key and paste the private key.6: Deploy Your Web3 Action
Go to the root of your project (folder containing the
tenderly.yaml file) and run the following command:1
tenderly actions deploy
Copied!
After the CLI shows successful deployment, you can head to Tenderly Dashboard. There you should see that your Web3 Action has been deployed (or is getting ready to be deployed).
7: Execute the Project
To check if what weโve created so far is working, head back to Remix and invoke the
doSomethingSmart function of the SimpleCoinConsumer contract.After a while, you should see an execution in the Execution tab in your Tenderly Dashboard. Youโll also see a new transaction that was sent from the oracleโs address by your Web3 Action, calling the
update function of the OracleContract contract. ๐