EUDI-BC-Oracles-ForCarbonCredits

Smart Carbon Credit System using Oracles, Blockchain, and Digital Identity Wallets

1. Repository Structure

The repository is divided into two primary environments:

• blockchain/: The core Hardhat project directory. Contains the Solidity smart contracts. Key contracts include the ConsumerContract (handling load-balanced Oracle requests and carbon credit logic), Operator, MinimalForwarder (for meta-transactions), and mock tokens. It also contains TypeScript and Bash scripts for deployment and environment management.
• chainlink-node/: Contains the infrastructure and configuration for the chainlink nodes.
• web/: Contains the off-chain applications and services.
  • frontend/: A React application built with Vite. It interacts with the backend API and the deployed smart contracts via the RPC exposed by the blockchain node.
  • backend/: A Node.js/Express API that manages user authentication, interacts with a PostgreSQL database, and implements an EIP-2771 compatible relayer system to facilitate gasless meta-transactions for users. It also provides simulated external data endpoints.

2. Multi-VM Testing Architecture

To simulate the envisioned decentralized network, the testing pipeline is designed to be distributed across multiple Virtual Machines (VMs).

The infrastructure is split into three distinct roles:

A. The Blockchain VM (Master Node)

This VM acts as the orchestrator of the test. It hosts the local blockchain network, deploys the contracts, and drives the automated testing pipeline.

1. Setup the Node: Start your local blockchain node and RPC endpoint on this VM so that it is accessible to the other VMs.
2. Define Chainlink Nodes: In the root of the blockchain/ directory on this VM, create a file named master_nodes.txt.
3. Configure IP Addresses: Add the IP addresses of your Chainlink Node VMs to master_nodes.txt, with one IP address per line. The testing pipeline will dynamically read this file to determine how many nodes to scale and target during the run.
4. Execute Tests: Run the master test script from this VM:

./run-all-tests.sh

B. The Chainlink Node VM(s)

These VMs act as the decentralized oracle network. You can provision one or multiple VMs to test load balancing and system stress.

• Role: Run the Chainlink node software and connected database (e.g., PostgreSQL).
• Setup: The nodes must be configured to point to the RPC URL of the Blockchain VM. Their wallet addresses will be automatically authorized and funded by the scripts running on the Blockchain VM.

C. The Web VM

This VM isolates the frontend and backend environments from the blockchain infrastructure.

• Role: Runs the React/Vite web application and the Node.js Express backend.
• Setup:
  • For the backend: Navigate to web/backend/. Configure .env with the RPC_URL (pointing to the Blockchain VM), FORWARDER_ADDRESS, and ADMIN_PRIVATE_KEY.
  • For the frontend: Navigate to web/frontend/. Configure your environment variables to point to the IP address of the Blockchain VM's RPC, the Backend API, and the newly deployed contract addresses.

3. Local Development Environment

For testing on a single machine or for development, you can run the entire stack locally using Docker.

Step 1: Start the Environment

This command spins up the Blockchain, Chainlink Node, Database, Backend API, and Frontend on your local machine.

# Start all containers (wiping previous DB to ensure synchronization)
docker compose down -v
docker compose up -d

Wait about 30-60 seconds for the Chainlink Node to initialize and become "Healthy" before proceeding.

Step 2: Automated Deployment

We use a custom script that deploys contracts, funds accounts, creates the Chainlink Job via API, and updates your frontend/backend configurations automatically.

cd oracle-echosystem
npx hardhat run scripts/deploy-local.ts --network localhost

What this script does:

1. Deploys LinkToken, Operator, MinimalForwarder, and SatelliteCreditManager.
2. Authorizes the Chainlink Node on the Operator contract.
3. Funds the Node with ETH and the contracts with LINK.
4. Logs into the Chainlink Node API and creates a new Direct Request Job using job-spec.toml.
5. Updates web/frontend/public/config.json and .env files with the new addresses and Job ID.
6. Copies the latest ABIs to the frontend/backend source folders.

Step 3: Use the App

• Open http://localhost:5173 in your browser to access the frontend dashboard.
• Open http://localhost:5000/docs to access the Backend API Swagger documentation.
• Open http://localhost:6688 to access the Chainlink Operator UI.