Skip to main content

๐Ÿ”ฎOracle Starter Kit


Check this out to learn some basics about Decentralized Oracle.


Oracle Starter Kit is integrated with Witnet services. This is a hardhat project containing oracle contracts and scripts implementing 3 features :

  • Price Feeds
  • VRF
  • External API Calls

It also has a command line interface to initialize a sample project and interact with the deployed contract. Follow the below steps to use Oracle starter kit and get off-chain data to your dapp.


npm install -g @klaytn/kss-cli --force

The above command installs the cli package for Klaytn service sdk globally, so that we can use oracle-starter-kit

Quick Usageโ€‹

For a default set of contracts and tests, run the following within the required project directory:

> kss-cli oracle init
> cd oracle-starter-kit
> npm install --force

Above commands downloads the oracle-starter-kit folder structure in the current project directory. Enter inside the generated folder and install the packages as mentioned

Next, follow the below steps to compile and deploy contracts to the Klaytn network and run their associated unit tests.

Setup hardhat configurationsโ€‹

1. Connect to Klaytn Test Network (Baobab)โ€‹

The default hardhat configurations can be modified in helper-hardhat-config.json. By default it connects to Klaytn test network (Boabab)

Hardhat configuration variables can be found in helper-hardhat-config.json in the root directory. Below is the configuration explaination for 1001 network.

  • name - hardhat network name Ex: baobab
  • witnetPriceRouter - witnetPriceRouter Address Ex: 0xeD074DA2A76FD2Ca90C1508930b4FB4420e413B0 for Klaytn Testnet. See WitnetPriceRouter for reference.
  • witnetRandomness - witnetRandomness Address. Ex: 0xb4b2e2e00e9d6e5490d55623e4f403ec84c6d33f for Klaytn Testnet. See WitnetRandomness Contract Addresses for reference.

2. Environment Variablesโ€‹

We will need to set environment variables by following below steps

  1. copy .env.example file and rename to .env
  2. Modify environment variables. Below is the explaination of each variable
  • BAOBAB_RPC_URL - string can be used. its the rpc url of blockchain.
  • PRIVATE_KEY - string This is private key from wallet, ie MetaMask. This is required for deploying contracts to public networks.


Don't commit and push any changes to .env files that may contain sensitive information, such as a private key! If this information reaches a public GitHub repository, someone can use it to check if you have any Mainnet funds in that wallet address, and steal them!

Get some Baobab Testnet KLAY

Go to the Klaytn faucets to get some KLAY to configured account.

Deploy contractsโ€‹

You should now be all setup! You can run any method now! Since we configured the environment variables and hardhat configurations so you don't really need to pass any configurations.

To compile contracts

npx hardhat compile

To deploy all contracts

npx hardhat deploy --network baobab

To run tests

npm run test

Interacting with Deployed Contractsโ€‹

After deploying your contracts, the deployment output will give you the contract addresses as they are deployed.You can then use these contract addresses in conjunction with Hardhat tasks to perform operations on each contract.

Witnet Price Feedsโ€‹

The Witnet Price Feeds consumer contract has one task, to read the latest price of a specified price feed contract.

  npx hardhat read-witnet-price-feed --contract <deployedContractAddress> --id <id> --network baobab


deployedContractAddress - string Deployed WitnetPriceFeed contract address id - string id4 is the witnet pricefeed ID. Ex: 0x6cc828d1 for Price-KLAY/USD-6. See Klaytn Witnet PriceFeeds for reference.


  • price - price of KLAY/USD.


  // As at the time of writing this document, 1 KLAY = 0.23 USD
npx hardhat read-witnet-price-feed --contract 0x573AAAdF4Cf117586e74AE3845473fc65cd59C4c --id 0x6cc828d1 --network baobab

Last price is: 237467

Check out witnet documentation for other available price feeds for Klaytn Network.

Witnet Randomnessโ€‹

The Witnet Randomness has 4 tasks. Make sure the deployWitnetRandomNumber method successful execution.

This 2-step process preserves unpredictability of the random numbers that you get because it guarantees that the number is derived from a seed that was generated only after the request was sent.

NOTE: Initially 1 and 2nd step has to be completed sequentially. Only after that 3rd or 4th can be executed for fetching a random number.

1. Request new randomnessโ€‹

Requesting the new randomness. Once the the request to new randomness is performed successfully. The other tasks can be performed after transaction submission.

  npx hardhat request-witnet-randomness --contract <deployedContractAddress> --value <value> --network baobab


deployedContractAddress - string Deployed Deployed Witnet RandomNumber contract address value - number Value for transaction cost when requesting random numbers. Ex: 500000000000000000 i.e, 0.5 KLAY

  • transaction hash - Transaction hash
npx hardhat request-witnet-randomness --contract 0x8937C127F3060fF8a23E9a0fb5AEA10bc30e28be --value 500000000000000000 --network baobab
Transaction Hash: 0x809addb235dc953c90a563c396c11978a359b574336564c7ec890514c961e050

2. Fetch Witnet random numberโ€‹

Initiate fetch witnet random number transaction.

WARNING: Calling fetch-witnet-random-number right after request-witnet-randomness will most likely cause the transaction to revert. Please allow 5-10 minutes for the randomization request to complete

  npx hardhat fetch-witnet-random-number --contract <deployedContractAddress> --network baobab


deployedContractAddress - string Deployed Witnet RandomNumber contract address

  • transaction hash - Transaction hash
  npx hardhat fetch-witnet-random-number --contract 0x8937C127F3060fF8a23E9a0fb5AEA10bc30e28be --network baobab
Transaction Hash: 0x0eb8fe1217ecdc3860009bc49f5319cab6ffdedd80877c39df02899a3542db24'

3. Get the latest randomizing blockโ€‹

  npx hardhat read-latest-randomizing-block --contract <deployedContractAddress> --network baobab


deployedContractAddress - string Deployed Witnet RandomNumber contract address

  • randomizingBlock - randomized block value
  npx hardhat read-latest-randomizing-block --contract 0x8937C127F3060fF8a23E9a0fb5AEA10bc30e28be --network baobab
The latest randomizing block is: 113690138

4. Get the generated random numberโ€‹

fetches the generated random number

NOTE: Make sure first 2 steps are executed sequentially.

  npx hardhat read-witnet-random-number --contract <deployedContractAddress> --network baobab


deployedContractAddress - string Deployed Witnet RandomNumber contract address

  • randomNumber - generated random number
  npx hardhat read-witnet-random-number --contract 0x8937C127F3060fF8a23E9a0fb5AEA10bc30e28be --network baobab
Random Number is: 1392104028

Witnet Web Oracle Requestโ€‹

We have 2 examples for Witnet HTTP Request:

  • KlayPrice: a GET request example to get Klay token price in USD
  • postRequestExample: a POST request example echoes back any data and headers that you send in your POST requests (based on this tutorial)

Inside witnet-queries folder you will find predefined Witnet oracle queries.

You can follow this link to learn how to create other queries.

Compile the Witnet queries into Solidity contractsโ€‹

npx rad2sol --target ./witnet-queries --write-contracts ./contracts/witnet-requests
  npx rad2sol --target ./witnet-queries --write-contracts ./contracts/witnet-requests

Execute Witnet Queriesโ€‹

After the contracts have been created, you can query locally to preview the result by running:

npx witnet-toolkit try-query --from-solidity ./contracts/witnet-requests/<contractFileName>

contractFileName - string generatedSolFileName

  • Result - string
Example 1 - Fetch Coinpriceโ€‹
  // 1 KLAY = 0.19 USD. Divide the return value by 10^6 to get actual coin price result.
npx witnet-toolkit try-query --from-solidity ./contracts/witnet-requests/coinPrice.sol
Result: 195467
Example 2 - Post Requestโ€‹
  // Gets parsed data of headers.Header-Name from the post api
npx witnet-toolkit try-query --from-solidity ./contracts/witnet-requests/postAPI.sol
Result: "Header-Value"

NOTE: If above tryWitnetQueries is stuck, please try to run command shown in below snapshot npx witnet-toolkit, install the binary once in the machine and retry above method WitnetToolkitBinary

Supra Price Feedsโ€‹

The Supra Price Feeds consumer contract has one task, to read the latest price of a specified price feed contract

  npx hardhat read-supra-price-feed --contract <deployedContractAddress> --marketpair <marketpair> --network baobab


deployedContractAddress - string Deployed SupraValueFeedExample contract address marketpair - string marketpair is the Supra marketpair id. Ex: btc_usdt. See Klaytn Supra PriceFeeds for reference.


  • price - price of requested market pair.


  // 1 BTC = 28837.54156500 USD
npx hardhat read-supra-price-feed --contract 0x80d2d67802942e9060122fafdf62bdc747d09021 --marketpair btc_usdt --network baobab
Last price is: BigNumber { value: "2883754156500" }

Reference Docsโ€‹