🔗 SCO60-CRE — Chainlink CRE Hackathon Project

Risk & Compliance Track — Automated cryptoasset exposure monitoring, SCO 60 regulatory compliance engine, and AI-powered advisory system built on Chainlink CRE.

---

🎯 Project Overview

SCO60-CRE is a real-time cryptoasset supervisory platform that integrates Chainlink CRE workflows with a full-stack monitoring system to help regulators enforce Basel III SCO 60 rules — the BCBS standard governing institutional cryptoasset exposure.

What It Does

Module	Function
CRE Workflow	Orchestration layer: cron-triggered + on-chain log-triggered monitoring
SCO 60 Engine	Classifies assets (Group 1a/1b/2a/2b), calculates RWA, checks soft/hard caps
On-Chain Reporting	Writes exposure results to ExposureOracle.sol, triggers RiskAlertManager.sol
AI Advisory	Google Gemini 2.0 Flash generates compliant regulatory action recommendations
Stress Testing	Simulates market shocks (50% price drop, liquidity haircut) and recalculates CAR
Regulator Dashboard	React UI with glassmorphism design, real-time BTC/ETH prices, alert management

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Chainlink CRE Layer                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  workflow.go — CRE Workflow (Cron + Log Triggers)        │   │
│  │  ├─ FetchPrices()    — CoinGecko API                     │   │
│  │  ├─ CheckExposures() — SCO 60 threshold engine           │   │
│  │  ├─ AnalyzeRisk()    — Gemini AI advisory                │   │
│  │  ├─ WriteOnChain()   → ExposureOracle.sol                │   │
│  │  └─ EmitAlerts()     → RiskAlertManager.sol              │   │
│  └──────────────────────────────────────────────────────────┘   │
└───────────────────────────────┬─────────────────────────────────┘
                                │ REST API / Events
┌───────────────────────────────▼─────────────────────────────────┐
│        Golang Backend API Server (Gin + JWT + RBAC)             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │
│  │ Exposure │ │ Pricing  │ │  Alerts  │ │   Stress Testing   │ │
│  │  Engine  │ │CoinGecko │ │  System  │ │      Engine        │ │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────────┘ │
│                      PostgreSQL 16                               │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTP / JSON
┌───────────────────────────────▼─────────────────────────────────┐
│     React + Tailwind Frontend — Supervisory Portal              │
│  Dashboard │ Institutions │ Alert Center │ Stress Testing        │
└─────────────────────────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Go 1.23+
• Node.js 20+
• Docker & Docker Compose
• Chainlink CRE CLI

Option A — Docker Compose (Recommended)

# 1. Clone the repository
git clone https://github.com/smpebble/sco60-cre_demo
cd SCO60-CRE

# 2. Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env — add your AI_PROVIDER_KEY (Gemini API) and blockchain keys

# 3. Start all services (PostgreSQL + Backend + Frontend)
docker-compose up -d

# 4. Verify everything is running
curl http://localhost:8090/health
open http://localhost:3000

Option B — Local Development

# 1. Start database
docker-compose -f docker-compose.db.yml up -d

# 2. Start backend API server
cd backend
cp .env.example .env  # Edit .env
go run cmd/server/main.go

# 3. Start frontend (new terminal)
cd frontend
npm install
npm run dev

# 4. Run the Chainlink CRE workflow (new terminal)
cd sco60-cre
cre workflow simulate sco60-cre

---

📊 SCO 60 Regulatory Logic

Basel III SCO 60 classifies cryptoassets into four groups with corresponding risk weights:

Group	Asset Type	Risk Weight	Treatment
1a	Tokenised traditional assets	20%	Standard credit/market risk
1b	Stablecoins (meets stabilisation criteria)	20%	Standard credit/market risk
2a	Crypto (meets hedging criteria)	100%	Multiplication factor applied
2b	Unhedged crypto (BTC, ETH)	1250%	Full deduction from capital

Group 2 Exposure Caps (applied against Tier 1 Capital):

• 🟡 Soft Cap (1%) — Warning, enhanced monitoring required
• 🔴 Hard Cap (2%) — Critical, excess exposure receives 1250% RW penalty

---

🔗 Chainlink CRE Integration

The sco60-cre/ directory contains the CRE workflow, meeting hackathon requirements:

✅ Blockchain integration — Reads on-chain events from RiskAlertManager.sol (log trigger), writes to ExposureOracle.sol

✅ External API — CoinGecko real-time price feeds (REST integration)

✅ AI/LLM — Google Gemini 2.0 Flash for regulatory risk assessment and recommendations

✅ Automated monitoring — Cron trigger (every hour) + manual/log triggers

Workflow Steps

1. FetchPrices       → CoinGecko API: BTC, ETH, USDT, USDC prices
2. CheckExposures    → SCO 60 Group 1a/1b/2a/2b categorization + RWA
3. AIAnalysis        → Gemini: Generate regulatory compliance assessment
4. WriteOnChain      → ExposureOracle.sol: reportExposure() transaction
5. EmitAlerts        → RiskAlertManager.sol: emitAlert() if thresholds exceeded

---

🗄️ Database Schema

15 core tables including:

Table	Description
institutions	Regulated entities (bank, securities, trust)
crypto_assets	SCO 60 classified assets with risk weights
holdings	Daily position reports by institution
exposure_results	Calculated SCO 60 metrics per institution per date
alerts	On-chain event log + off-chain risk alerts
stress_test_results	Historical stress simulation results
ai_advisories	LLM-generated regulatory recommendations
price_history	Daily OHLCV from CoinGecko

---

🛡️ Smart Contracts

Contract	Network	Purpose
ExposureOracle.sol	Sepolia	Stores institution exposure data on-chain
RiskAlertManager.sol	Sepolia	Emits threshold breach events (CRE log trigger)

---

🔐 API Reference

All endpoints require JWT authentication (Authorization: Bearer <token>).

POST /api/v1/auth/login
GET  /api/v1/dashboard
GET  /api/v1/institutions
GET  /api/v1/institutions/:id
GET  /api/v1/assets
GET  /api/v1/exposures/:institutionId
POST /api/v1/exposures/calculate      [ADMIN, REGULATOR]
GET  /api/v1/alerts
POST /api/v1/alerts/:id/resolve       [ADMIN, REGULATOR]
GET  /api/v1/prices
GET  /api/v1/stress/scenarios
POST /api/v1/stress/run               [ADMIN, REGULATOR]
POST /api/v1/ai/advisory              [ADMIN, REGULATOR]
GET  /api/v1/ai/advisories/:instId
GET  /api/v1/holdings/:instId

---

🧪 Integration Testing (Simulation)

To prove the core workflow engine works without requiring judges to configure the Chainlink CRE CLI locally, we provide native simulation scripts that execute the exact identical pipeline:

Option A: Unix / macOS (Bash)

# Ensure backend is running, then execute:
chmod +x scripts/simulate_cre.sh
API_BASE_URL=http://localhost:8090/api/v1 ./scripts/simulate_cre.sh

Option B: Windows (PowerShell)

# Open PowerShell and execute from the project root:
$env:API_BASE_URL="http://localhost:8090/api/v1"; .\scripts\simulate_cre.ps1

---

📁 Project Structure

SCO60-CRE/
├── sco60-cre/              # Chainlink CRE Workflow
│   ├── workflow.go         # CRE workflow (cron + log triggers)
│   ├── exposure_checker.go # SCO 60 threshold engine
│   ├── ai_analyzer.go      # Gemini LLM integration
│   └── workflow_test.go    # 6 unit tests
│
├── backend/                # Golang API Server
│   ├── cmd/server/main.go  # Entry point
│   ├── internal/
│   │   ├── config/         # Environment configuration
│   │   ├── models/         # Domain types (15+ models)
│   │   ├── middleware/      # JWT + RBAC + CORS
│   │   ├── repository/     # PostgreSQL data access (9 repos)
│   │   ├── service/        # Business logic (7 services)
│   │   └── handler/        # HTTP handlers (17 endpoints)
│   ├── migrations/         # PostgreSQL schema (15 tables)
│   └── Dockerfile
│
├── frontend/               # React + Tailwind Portal
│   ├── src/
│   │   ├── pages/          # Dashboard, Institutions, Alerts, Stress Test
│   │   ├── components/     # MainLayout, shared UI
│   │   ├── contexts/       # AuthContext
│   │   ├── lib/            # API client, utilities
│   │   └── types/          # TypeScript DTOs
│   └── Dockerfile
│
├── contracts/              # Solidity Smart Contracts
│   ├── ExposureOracle.sol
│   └── RiskAlertManager.sol
│
├── scripts/
│   └── simulate_cre.sh     # Integration test script
├── docker-compose.yml      # Full-stack deployment
└── README.md

---

🏆 Hackathon Submission — Risk & Compliance Track

This project satisfies all Chainlink CRE hackathon requirements:

• ✅ CRE Workflow as the orchestration layer with at least one blockchain + external API integration
• ✅ Automated Risk Monitoring — Continuous SCO 60 exposure assessment
• ✅ Real-time Backup Health Checks — Capital adequacy monitoring with threshold alerts
• ✅ Protocol Protection Triggers — On-chain RiskAlertManager.sol events for automated response
• ✅ AI/LLM Integration — Gemini 2.0 Flash for regulatory advisory generation
• ✅ Successful CRE Workflow deployment — Staging and production configurations included

---

📜 License

MIT License — Built for the Chainlink Hackathon 2026.