oracle-brownie-kit

A Python Brownie starter project for building and testing decentralized oracle smart contracts on Ethereum. Demonstrates three core oracle patterns — price feeds, verifiable random numbers (VRF), and external API data requests — each with deployment scripts, mock contracts for local testing, and a full pytest suite.

What this project covers

Feature	What it does
Price Feeds	Reads an on-chain ETH/USD price from an aggregator contract
VRF	Requests a provably random uint256 from an on-chain VRF coordinator
API Consumer	Makes an HTTP GET request to an external API via an oracle node

Project structure

contracts/
  PriceFeed.sol              - wraps an aggregator interface to expose getLatestPrice()
  VRFConsumer.sol            - requests and receives verifiable random numbers
  APIConsumer.sol            - sends oracle requests to fetch external API data
  test_contracts/            - local-only mock contracts (not for mainnet)
    LinkToken.sol            - deployable ERC677 LINK token for local testing
    Oracle.sol               - modified oracle contract with test-accessible fields
    mocks/                   - mock aggregator, VRF coordinator, and oracle
interfaces/
  LinkTokenInterface.sol     - ERC677 LINK token interface
scripts/
  price_feed_scripts/        - deploy and read price feed
  vrf_scripts/               - deploy, fund, request, and read VRF
  chainlink_api_scripts/     - deploy, fund, request, and read API consumer
tests/
  conftest.py                - shared fixtures, network-branching logic
  test_price_feeds.py        - price feed unit tests
  test_vrf.py                - VRF unit and integration tests
  test_api_consumer.py       - API consumer unit and integration tests
  test_unnecessary/          - in-depth oracle internals tests (skipped by default)

Prerequisites

• Python 3.8+
• Node.js 14+ and npm
• eth-brownie — pip install eth-brownie
• ganache-cli — npm install -g ganache-cli

For testnet or mainnet deployment you also need:

• A blockchain RPC provider project ID, exported as WEB3_INFURA_PROJECT_ID
• A wallet private key, exported as PRIVATE_KEY

Installation

git clone <repository-url>
cd oracle-brownie-kit
pip install -r requirements.txt
npm install -g ganache-cli

Usage

All commands default to the local development network (ganache). Add --network kovan or --network rinkeby to run on a testnet (requires environment variables above).

Price Feeds

brownie run scripts/price_feed_scripts/deploy_price_consumer_v3.py --network kovan
brownie run scripts/price_feed_scripts/read_price_feed.py --network kovan

To interact via the Brownie console on a mainnet fork:

brownie console --network mainnet-fork
>>> price_feed = PriceFeed.deploy('0x5d62e9518bc50aa17060b8281f876b5216d8c00f', {'from': accounts[0]})
>>> price_feed.getLatestPrice()

Verifiable Random Function (VRF)

brownie run scripts/vrf_scripts/deploy_vrf.py --network kovan
brownie run scripts/vrf_scripts/fund_vrf.py --network kovan
brownie run scripts/vrf_scripts/request_randomness.py --network kovan
brownie run scripts/vrf_scripts/read_random_number.py --network kovan

Note: VRF requests are fulfilled asynchronously. Wait for the oracle node to respond before running read_random_number.py.

API Consumer

brownie run scripts/chainlink_api_scripts/deploy_api_consumer.py --network kovan
brownie run scripts/chainlink_api_scripts/fund_chainlink_api.py --network kovan
brownie run scripts/chainlink_api_scripts/request_api.py --network kovan
brownie run scripts/chainlink_api_scripts/read_data.py --network kovan

Testing

Tests are split into unit tests (run against a local ganache network with mock contracts) and integration tests (run against a live testnet).

Run all unit tests locally:

brownie test

Run against a mainnet fork (requires WEB3_INFURA_PROJECT_ID):

brownie test --network mainnet-fork

Run integration tests on a testnet:

brownie test --network kovan

The tests/test_unnecessary directory contains deeper tests for oracle contract internals. They are marked @pytest.mark.skip by default and are intended as a learning exercise rather than part of the standard suite.

Adding networks

Register any EVM-compatible chain:

brownie networks add Ethereum <network-name> host=http://your-rpc-endpoint chainid=<chain-id>

Register a forked development environment:

brownie networks add development <fork-name> cmd=ganache-cli host=http://127.0.0.1 fork=http://your-rpc-endpoint accounts=10 mnemonic=brownie port=8545

Environment variables

Variable	Required for	Description
PRIVATE_KEY	Testnet/mainnet deploy	Hex private key of the deployer wallet
WEB3_INFURA_PROJECT_ID	Testnet/mainnet/fork	RPC provider project ID used by Brownie

Never commit a .env file. Both variables are excluded from version control via .gitignore.

License

MIT — see LICENSE.