NGN/USD Oracle Client for Base Mainnet

A Node.js client for interacting with Chainlink's cNGN/USD price feed oracle on Base mainnet. This implementation provides real-time exchange rate monitoring, event-driven updates, and historical data queries for the Nigerian Naira to US Dollar pair.

📋 Table of Contents

Overview
Features
Prerequisites
Installation
Docker Installation
Configuration
Usage
API Reference
HTTP API Endpoints
Events
Examples
Security Considerations
Troubleshooting
Contributing
License

🌟 Overview

This client interfaces with Chainlink's cNGN/USD price feed oracle deployed on Base mainnet at address 0xdfbb5Cbc88E382de007bfe6CE99C388176ED80aD. The oracle provides reliable, decentralized exchange rate data for the Nigerian Naira (NGN) against the US Dollar (USD).

About Chainlink cNGN Oracle

Chainlink's cNGN oracle is part of their comprehensive price feed network, providing:

Decentralized data aggregation from multiple sources
High reliability with multiple node operators
Tamper-resistant price information
Regular updates based on market conditions

✨ Features

🔄 Real-time Price Monitoring - Continuous polling of current exchange rates
📡 Event-Driven Architecture - Listen to price update events in real-time
📊 Historical Data Query - Access past price updates and events
️ Error Handling - Robust error management and retry logic
📈 Detailed Logging - Comprehensive logging for debugging and monitoring

📚 Prerequisites

Before you begin, ensure you have the following installed:

Node.js v16.0.0 or higher
npm or yarn package manager
Git for version control

You'll also need:

RPC endpoint (default uses public Base RPC)

🚀 Installation

Clone the repository

git clone https://github.com/wrappedcbdc/cngn-price-oracle.git
cd cngn-price-oracle

Install dependencies

npm install

or with yarn:

yarn install

Set up environment variables

cp .env.example .env

🐳 Docker Installation (Recommended)

Quick Start with Docker

Clone and configure

git clone https://github.com/wrappedcbdc/cngn-price-oracle.git
cd cngn-price-oracle
cp .env.example .env

Build and run with Docker Compose

# Start both API server and monitoring service
docker-compose up -d

# Or start only the API server
docker-compose up -d cngn-oracle-api

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Using Docker Directly

Build the image:

docker build -t cngn-oracle .

Run API server:

docker run -d \
  --name cngn-oracle-api \
  -p 3000:3000 \
  -e ORACLE_CONTRACT_ADDRESS=0xdfbb5Cbc88E382de007bfe6CE99C388176ED80aD \
  -e RPC_URL=https://mainnet.base.org \
  cngn-oracle

Run monitoring service:

docker run -d \
  --name cngn-oracle-monitor \
  -e ORACLE_CONTRACT_ADDRESS=0xdfbb5Cbc88E382de007bfe6CE99C388176ED80aD \
  -e RPC_URL=https://mainnet.base.org \
  cngn-oracle npm start

Using environment file:

docker run -d \
  --name cngn-oracle-api \
  -p 3000:3000 \
  --env-file .env \
  cngn-oracle

Docker commands:

# View logs
docker logs -f cngn-oracle-api

# Stop container
docker stop cngn-oracle-api

# Remove container
docker rm cngn-oracle-api

# Execute commands inside container
docker exec -it cngn-oracle-api npm run dev

⚙️ Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Required
ORACLE_CONTRACT_ADDRESS=0xdfbb5Cbc88E382de007bfe6CE99C388176ED80aD

# Optional (defaults provided)
RPC_URL=https://mainnet.base.org
POLLING_INTERVAL=30000  # Price check interval in milliseconds
API_PORT=3000  # API server port

Network Configuration

The client is configured for Base mainnet by default. Network details:

Parameter	Value
Network	Base Mainnet
Chain ID	8453
Currency	ETH
Oracle	Chainlink cNGN/USD
Contract	`0xdfbb5Cbc88E382de007bfe6CE99C388176ED80aD`

📖 Usage

Quick Start

# Run the oracle client
npm start

# Run in development mode with auto-restart
npm run dev

API Server

# Start the API server
npm run api         # production mode
npm run dev:api     # development mode with auto-restart

Basic Implementation

const { NGNUSDOracle } = require('./oracle');
const { ethers } = require('ethers');

const rpcUrl = "https://mainnet.base.org";
const provider = new ethers.JsonRpcProvider(rpcUrl);

async function main() {
    // Initialize the oracle client
    const oracle = new NGNUSDOracle(provider);
    
    // Get current price
    const price = await oracle.getCurrentPrice();
    console.log(`Current rate: ${price.formattedPrice}`);
    
    // Start monitoring with events
    oracle.setupEventListeners();
    await oracle.monitorPrice(60000); // Check every minute
}

main().catch(console.error);

📚 API Reference

Constructor

new NGNUSDOracle(provider)

Creates a new instance of the NGN/USD oracle client.

Parameters:

provider (ethers.Provider): An ethers.js provider connected to Base mainnet

Methods

`getCurrentPrice()`

Fetches the current NGN/USD exchange rate.

Returns: Promise<Object>

{
    price: 1450.50,              // Numeric price
    decimals: 8,                 // Price decimals
    timestamp: 1699564800,       // Unix timestamp
    formattedPrice: "1 USD = 1450.50 NGN"  // Human-readable format
}

`getLatestRoundData()`

Retrieves detailed information about the latest price update round.

Returns: Promise<Object>

{
    roundId: "18446744073709562776",
    answer: 145050000000,        // Raw price with decimals
    startedAt: 1699564800,
    updatedAt: 1699564800,
    answeredInRound: "18446744073709562776"
}

`setupEventListeners()`

Initializes event listeners for real-time updates.

oracle.setupEventListeners();

`monitorPrice(intervalMs)`

Starts continuous price monitoring.

Parameters:

intervalMs (number): Polling interval in milliseconds (default: 60000)

`queryHistoricalEvents(fromBlock, toBlock)`

Queries past price update events.

Parameters:

fromBlock (number|string): Starting block number or 'latest'
toBlock (number|string): Ending block number or 'latest'

Returns: Promise<Array> of event objects

🌐 HTTP API Endpoints

The project includes a REST API server (implemented in api.js) that exposes HTTP endpoints for easy integration with web applications and external services.

GET /health

Health check endpoint to verify API server status.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "oracle": "initialized"
}

GET /api/price

Retrieves the current NGN/USD exchange rate with comprehensive price data.

Response:

{
  "success": true,
  "data": {
    "usdToNgn": 1450.50,
    "ngnToUsd": 0.000689,
    "formattedPrice": "1 USD = 1450.50 NGN",
    "reversePrice": "1 NGN = 0.000689 USD",
    "decimals": 8,
    "description": "NGN/USD",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

GET /api/round

Fetches detailed information about the latest price update round.

Response:

{
  "success": true,
  "data": {
    "roundId": "18446744073709562776",
    "usdToNgn": 1450.50,
    "ngnToUsd": 0.000689,
    "formattedPrice": "1 USD = 1450.50 NGN",
    "reversePrice": "1 NGN = 0.000689 USD",
    "updatedAt": 1699564800,
    "updatedAtFormatted": "2024-01-15T10:30:00.000Z",
    "answeredInRound": "18446744073709562776"
  }
}

GET /api/convert/usd-to-ngn/:amount

Converts a specified USD amount to NGN using the current exchange rate.

Parameters:

amount (path parameter): USD amount to convert (must be a valid number)

Example: /api/convert/usd-to-ngn/100

Response:

{
  "success": true,
  "data": {
    "usdAmount": 100,
    "ngnAmount": 145050,
    "rate": 1450.50,
    "formattedResult": "100 USD = 145050.00 NGN",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

GET /api/convert/ngn-to-usd/:amount

Converts a specified NGN amount to USD using the current exchange rate.

Parameters:

amount (path parameter): NGN amount to convert (must be a valid number)

Example: /api/convert/ngn-to-usd/145050

Response:

{
  "success": true,
  "data": {
    "ngnAmount": 145050,
    "usdAmount": 100.000000,
    "rate": 0.000689,
    "formattedResult": "145050 NGN = 100.000000 USD",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

GET /api/history?blocks=

Retrieves historical price update events from the blockchain.

Parameters:

blocks (query parameter, optional): Number of blocks to query (default: 50)

Example: /api/history?blocks=100

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "roundId": "18446744073709562776",
        "price": 1450.50,
        "formattedPrice": "1 USD = 1450.50 NGN",
        "updatedAt": 1699564800,
        "updatedAtFormatted": "2024-01-15T10:30:00.000Z",
        "blockNumber": 12345678,
        "transactionHash": "0x..."
      }
    ],
    "count": 25,
    "blocksQueried": 100
  }
}

Error Response Format:

All endpoints return errors in the following format:

{
  "success": false,
  "error": "Error description",
  "message": "Detailed error message"
}

📡 Events

The oracle emits the following events:

`AnswerUpdated`

Emitted when the oracle price is updated.

oracle.contract.on('AnswerUpdated', (current, roundId, updatedAt, event) => {
    console.log('New price:', current);
    console.log('Round ID:', roundId);
    console.log('Updated at:', updatedAt);
});

💡 Examples

Example 1: Simple Price Check

async function checkPrice() {
    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
    const oracle = new NGNUSDOracle(provider);
    const { formattedPrice } = await oracle.getCurrentPrice();
    console.log(formattedPrice);
}

Example 2: Historical Analysis

async function analyzeHistory() {
    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
    const oracle = new NGNUSDOracle(provider);
    const events = await oracle.queryHistoricalEvents(1000);
    
    events.forEach(event => {
        console.log(`${event.updatedAtFormatted}: ${event.formattedPrice}`);
    });
}

Example 3: Price Alert System

async function priceAlerts() {
    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
    const oracle = new NGNUSDOracle(provider);
    const threshold = 1500; // Alert if 1 USD > 1500 NGN
    
    oracle.contract.on('AnswerUpdated', async (current, roundId, updatedAt) => {
        const decimals = await oracle.contract.decimals();
        const rate = Number(current) / Math.pow(10, Number(decimals));
        
        if (rate > threshold) {
            console.log(`🚨 ALERT: NGN/USD rate exceeded ${threshold}!`);
            // Send notification, email, etc.
        }
    });
}

🔒 Security Considerations

RPC Security
- Use private RPC endpoints for production
- Implement rate limiting to avoid DOS
- Monitor for unusual activity
Best Practices

// Good: Using environment variable for RPC
const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const oracle = new NGNUSDOracle(provider);

🔧 Troubleshooting

Common Issues

1. Connection Errors

Error: Could not connect to Base mainnet

Solution: Check your internet connection and RPC endpoint availability.

2. Invalid ABI

Error: Contract method not found

Solution: Verify you're using the correct contract ABI.

Debug Mode

Enable debug logging:

const provider = new ethers.JsonRpcProvider(rpcUrl);
const oracle = new NGNUSDOracle(provider);

Health Check

async function healthCheck() {
    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
    const oracle = new NGNUSDOracle(provider);
    
    try {
        await oracle.getCurrentPrice();
        console.log('✅ Oracle is healthy');
    } catch (error) {
        console.error('❌ Oracle health check failed:', error);
    }
}

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Install development dependencies
npm install --save-dev

# Run tests
npm test

# Run linter
npm run lint

# Build documentation
npm run docs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

📞 Support

Open an issue on GitHub
Email: contact@cngn.co

Disclaimer: This software is provided "as is" without warranty of any kind. Always test thoroughly before using in production environments.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
api.js		api.js
docker-compose.yml		docker-compose.yml
oracle.js		oracle.js
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

NGN/USD Oracle Client for Base Mainnet

📋 Table of Contents

🌟 Overview

About Chainlink cNGN Oracle

✨ Features

📚 Prerequisites

🚀 Installation

🐳 Docker Installation (Recommended)

Quick Start with Docker

Using Docker Directly

⚙️ Configuration

Environment Variables

Network Configuration

📖 Usage

Quick Start

API Server

Basic Implementation

📚 API Reference

Constructor

Methods

getCurrentPrice()

getLatestRoundData()

setupEventListeners()

monitorPrice(intervalMs)

queryHistoricalEvents(fromBlock, toBlock)

🌐 HTTP API Endpoints

GET /health

GET /api/price

GET /api/round

GET /api/convert/usd-to-ngn/:amount

GET /api/convert/ngn-to-usd/:amount

GET /api/history?blocks=

📡 Events

AnswerUpdated

💡 Examples

Example 1: Simple Price Check

Example 2: Historical Analysis

Example 3: Price Alert System

🔒 Security Considerations

🔧 Troubleshooting

Common Issues

1. Connection Errors

2. Invalid ABI

Debug Mode

Health Check

🤝 Contributing

Development Setup

📄 License

🔗 Resources

📞 Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`getCurrentPrice()`

`getLatestRoundData()`

`setupEventListeners()`

`monitorPrice(intervalMs)`

`queryHistoricalEvents(fromBlock, toBlock)`

`AnswerUpdated`

Packages