Price Oracle 가이드

FlutterDev 블록체인의 Price Oracle 시스템에 대한 가이드입니다.

---

Oracle이란?

블록체인은 외부 데이터에 직접 접근할 수 없습니다. Oracle은 외부 세계의 데이터(가격, 날씨, 스포츠 결과 등)를 블록체인에 전달하는 중개자 역할을 합니다.

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   외부 세계      │      │     Oracle      │      │   블록체인      │
│  (가격 API 등)   │─────▶│   (중개자)      │─────▶│ (스마트 컨트랙트)│
└─────────────────┘      └─────────────────┘      └─────────────────┘

---

아키텍처

FlutterDev Oracle 시스템은 3개의 컴포넌트로 구성됩니다:

┌──────────────────────────────────────────────────────────────┐
│                    Oracle Architecture                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────┐                                         │
│  │  Oracle Server  │  ◄── Off-chain (Node.js)               │
│  │   (Port 3004)   │      • 가격 수집/변동 시뮬레이션        │
│  │                 │      • 1분마다 온체인 업데이트          │
│  └────────┬────────┘      • REST API 제공                   │
│           │                                                  │
│           │ updatePrices()                                   │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │  PriceOracle    │  ◄── On-chain (Solidity)               │
│  │   Contract      │      • 토큰별 가격 저장                 │
│  │                 │      • Staleness 체크 (1시간)          │
│  └────────┬────────┘      • 가격 조회 함수                   │
│           │                                                  │
│           │ getPrice()                                       │
│           ▼                                                  │
│  ┌─────────────────┐                                         │
│  │ LendingPoolV2   │  ◄── On-chain (Solidity)               │
│  │   Contract      │      • USD 기준 담보 가치 계산          │
│  │                 │      • Health Factor 계산               │
│  └─────────────────┘                                         │
│                                                              │
└──────────────────────────────────────────────────────────────┘

---

스마트 컨트랙트

PriceOracle.sol

항목	값
주소	0x4beeEFF741f6CF8D14C3bF1420f0D8C59e86E29D
소유자	Deployer
가격 단위	USD (18 decimals)
Stale 기준	1시간

주요 함수

// 단일 토큰 가격 업데이트 (Owner만)
function updatePrice(address token, uint256 price) external onlyOwner;

// 다중 토큰 가격 업데이트 (Owner만)
function updatePrices(address[] tokens, uint256[] prices) external onlyOwner;

// 가격 조회 (Stale 체크 포함)
function getPrice(address token) external view returns (uint256);

// 가격 정보 조회 (Stale 체크 없음, UI용)
function getPriceInfo(address token) external view returns (
    uint256 price,
    uint256 timestamp,
    bool isStale
);

가격 형식

가격은 18 decimals 형식으로 저장됩니다:

토큰	실제 가격	저장 값
ETH	$2,000	2000 * 10^18
FDT	$1	1 * 10^18
USDC	$1	1 * 10^18

---

Oracle Server

실행 방법

cd /home/blockchain/lending/oracle-server
npm install
node index.js

설정

const config = {
  rpcUrl: 'http://127.0.0.1:32768',
  oracleAddress: '0x4beeEFF741f6CF8D14C3bF1420f0D8C59e86E29D',
  updateInterval: 60000, // 1분
  port: 3004
};

API 엔드포인트

메서드	경로	설명
GET	/prices	전체 토큰 가격 조회
GET	/price/:symbol	개별 토큰 가격 조회
POST	/update	수동 가격 업데이트 트리거
POST	/set-price	특정 토큰 가격 설정 (테스트용)
GET	/health	서버 상태 확인

API 사용 예시

전체 가격 조회

curl http://localhost:3004/prices

응답:

{
  "success": true,
  "prices": {
    "ETH": {
      "address": "0xEeee...",
      "price": "2000.0",
      "lastUpdated": 1733123456,
      "lastUpdatedDate": "2025-12-02T..."
    },
    "FDT": {
      "address": "0xfD87...",
      "price": "1.0",
      ...
    }
  }
}

개별 가격 조회

curl http://localhost:3004/price/ETH

응답:

{
  "success": true,
  "symbol": "ETH",
  "address": "0xEeee...",
  "price": "2000.0",
  "priceUSD": 2000,
  "lastUpdated": 1733123456
}

가격 수동 설정 (테스트용)

curl -X POST http://localhost:3004/set-price \
  -H "Content-Type: application/json" \
  -d '{"symbol": "ETH", "price": 2500}'

---

가격 변동 시뮬레이션

Oracle Server는 실제 가격 피드가 없어 시뮬레이션된 가격을 사용합니다:

토큰	기준 가격	변동폭	설명
ETH	$2,000	±2%	1분마다 랜덤 변동
FDT	$1	±5%	1분마다 랜덤 변동
USDC	$1	0%	스테이블코인 (고정)
DAI	$1	0%	스테이블코인 (고정)

---

Lending 통합

LendingPoolV2는 Oracle을 사용하여:

1. USD 기준 담보 가치 계산

담보 가치 (USD) = 예금량 × Oracle 가격

2. Health Factor 계산

Health Factor = (총 담보 USD × 75%) / 총 대출 USD

3. 청산 판단

Health Factor < 1.0 → 청산 가능

예시

상황	ETH 가격	담보 (10 ETH)	대출 (FDT)	Health
정상	$2,000	$20,000	$10,000	1.50
하락	$1,500	$15,000	$10,000	1.125
위험	$1,200	$12,000	$10,000	0.90

---

문제 해결

"Price is stale" 오류

원인: 가격이 1시간 이상 업데이트되지 않음

해결:

1. Oracle Server가 실행 중인지 확인

   curl http://localhost:3004/health

2. 수동으로 가격 업데이트

   curl -X POST http://localhost:3004/update

"Price not available" 오류

원인: 해당 토큰의 가격이 설정되지 않음

해결:

1. 토큰 주소가 올바른지 확인
2. Oracle에 가격 설정

   curl -X POST http://localhost:3004/set-price \
     -d '{"symbol": "TOKEN", "price": 1.0}'

Oracle Server 연결 실패

체크리스트:

1. 서버 실행 확인: ps aux | grep "oracle"
2. 포트 확인: netstat -tlnp | grep 3004
3. RPC 연결 확인: 블록체인 노드 상태 확인

---

확장: 실제 가격 피드 연동

실제 서비스에서는 외부 가격 API를 연동할 수 있습니다:

// CoinGecko API 예시
async function fetchRealPrices() {
  const response = await fetch(
    'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd'
  );
  const data = await response.json();
  return data.ethereum.usd;
}

주요 가격 소스

서비스	특징
Chainlink	분산형 Oracle 네트워크, 가장 신뢰도 높음
CoinGecko	무료 API, 중앙화
CoinMarketCap	무료/유료 API, 중앙화
Uniswap TWAP	온체인 DEX 가격, 조작 방지

---

컨트랙트 소스

파일	경로
PriceOracle.sol	/home/blockchain/lending/contracts/PriceOracle.sol
LendingPoolV2.sol	/home/blockchain/lending/contracts/LendingPoolV2.sol
Oracle Server	/home/blockchain/lending/oracle-server/

---

관련 링크

• FlutterLend - Oracle을 사용하는 Lending 프로토콜
• FlutterDex - 토큰 스왑
• Block Explorer - 트랜잭션 확인