copper-reference-oracle

A complete MVP Copper Reference Oracle for Base Sepolia (chainId 84532).

This repo contains:

• Hardhat contracts: an on-chain store for two values (both 8 decimals):
  • copperUsdPerKg (USD/kg)
  • copperBtcPerKg (BTC/kg)
• CRE-style workflow runner (TypeScript): runs hourly to fetch copper + BTC/USD, compute both values, apply guardrails, and submit on-chain.
• Lightweight read-only dApp (Vite + React): displays the latest values and refreshes every 30 seconds.

What it publishes (8 decimals)

• copperUsdPerKg — copper spot price normalized to USD per kilogram, scaled by 1e8.
• copperBtcPerKg — computed as copperUsdPerKg / btcUsd, scaled by 1e8.

Guardrails

• Workflow outlier filter (10%): rejects updates when |new - old| / old > 10% (first update allowed when old is 0).
• On-chain minimum update interval (1 hour): minUpdateInterval = 3600 seconds enforced in Solidity.

Workflow steps (1–6)

1. Fetch copper spot price from MetalpriceAPI: XCU in USD/oz.
2. Convert USD/oz → USD/kg using 1 oz = 0.028349523125 kg.
3. Read BTC/USD from a Chainlink AggregatorV3 feed.
4. Normalize BTC/USD to 8 decimals and compute copperBtcPerKg.
5. Apply 10% outlier check vs the last on-chain copperUsdPerKg.
6. Submit both values + sourceHash = keccak256(utf8(JSON.stringify(raw_api_payload))) to the on-chain contract.

Important: Chainlink feed addresses are network-specific and must be verified for Base Sepolia. The example address in .env.example is a common placeholder and may not be correct for Base Sepolia.

Codespaces quickstart

1) Contracts

cd contracts
cp .env.example .env
npm i
npm run compile
npm run deploy:base-sepolia

2) Workflow

cd ../workflow
cp .env.example .env
npm i

# One shot
npm run run-once

# Hourly runner
npm run run-hourly

3) dApp

cd ../dapp
cp .env.example .env
npm i
npm run dev

Folder layout

• contracts/ – Solidity contract + deploy script (Hardhat)
• workflow/ – CRE-style runner (TypeScript) with run-once and run-hourly
• dapp/ – Vite + React read-only UI

Reference Pattern Documentation

This repository includes additional documentation explaining the oracle reference pattern, trust boundaries, failure modes, and CRE compatibility:

• REFERENCE_PATTERN.md
• docs/TRUST_BOUNDARIES.md
• docs/FAILURE_MODES.md
• docs/CRE_MAPPING.md