Federated Learning (FL)

Savitri Network는 AI 모델의 분산 훈련을 위한 온체인 Federated Learning 시스템을 포함합니다. FL 컨트랙트는 모델 등록, 훈련 라운드, 업데이트 제출, 보상 배분, 거버넌스를 관리합니다.

아키텍처

거버넌스 (제안 + 투표)
    │
    ▼
모델 레지스트리
    │ 모델 등록, 역할 할당, 버전 추적
    ▼
작업 생명 주기
    │ 라운드 생성 → 열기 → 업데이트 제출 → 봉인 → 완료
    ▼
보상 풀
    │ 머클 증명으로 보상 청구
    ▼
트레이너 + 집계자

모델 레지스트리

모델은 메타데이터, 버전 관리, 역할 기반 접근 제어로 온체인에 등록됩니다.

모델 등록

// 새 모델 등록
FlModelRegistry::register_model(
    &mut storage,
    &db,
    &creator,           // [u8; 32] - 모델 생성자 주소
    "sentiment-v1",     // 모델 이름
    "ipfs://Qm.../meta", // 메타데이터 URI
    "MIT",              // 라이선스 URI
    "ipfs://Qm.../weights", // 초기 가중치 URI
    &mut events,
    Some(&mut gas),
)?;

모델 버전 관리

모델은 불변의 버전 체인을 가집니다. 각 새 버전은 이전 버전을 참조합니다:

v1 (초기) → v2 (파인튜닝) → v3 (프로덕션)

버전 메타데이터 포함 항목:

• metadata_uri: 모델 아키텍처 설명
• weights_uri: 훈련된 가중치 위치
• aggregator: 이 버전을 생성한 주소
• parent_version: 이전 버전 링크

역할 기반 접근 제어 (RBAC)

역할	권한
Creator	모델 등록, 버전 관리, 정책 설정
Viewer	모델 메타데이터 및 버전 읽기
Trainer	라운드에 훈련 업데이트 제출
Aggregator	업데이트 집계, 라운드 완료, 버전 생성

트레이너 접근은 모델별 허용 목록/거부 목록을 통해 제어됩니다.

정책 관리

각 모델은 설정 가능한 정책을 가집니다:

정책	설명
access_policy_hash	모델 데이터에 접근할 수 있는 사람
reward_policy_hash	보상 배분 방법
max_trainers	최대 동시 트레이너 수
aggregator_whitelist	승인된 집계자

작업 생명 주기

FL 훈련은 정해진 생명 주기를 가진 라운드로 구성됩니다:

예정됨 → 열림 → 봉인됨 → 완료됨
                    ↘ 중단됨 (거버넌스를 통해)

라운드 상태

상태	설명	허용된 액션
Planned	라운드 생성됨, 업데이트 대기 전	열기
Open	트레이너의 업데이트 대기 중	업데이트 제출, 봉인
Sealed	더 이상 업데이트 없음, 집계 진행 중	완료, 중단
Finalized	보상 배분됨, 라운드 완료	보상 청구
Aborted	거버넌스를 통해 라운드 취소됨	없음

라운드 생성

FlJobLifecycle::create_round(
    &mut storage,
    &db,
    &creator,
    &model_id,          // [u8; 32]
    round_id,           // u64
    reward_pool_amount,  // u128
    &mut events,
    Some(&mut gas),
)?;

훈련 업데이트 제출

트레이너는 열린 단계 동안 모델 업데이트를 제출합니다:

FlJobLifecycle::submit_update(
    &mut storage,
    &db,
    &trainer,           // [u8; 32]
    &model_id,
    round_id,
    &update_data,       // training update bytes
    nonce,              // replay protection
    &mut events,
    Some(&mut gas),
)?;

재생 방지: 각 트레이너는 라운드당 논스를 가지며 엄격하게 증가해야 합니다.

봉인 및 완료

// 라운드 봉인 (업데이트 수신 중단)
FlJobLifecycle::seal_round(&mut storage, &db, &aggregator, &model_id, round_id, ...)?;

// 라운드 완료 (보상 배분)
FlJobLifecycle::finalize_round(
    &mut storage, &db, &aggregator, &model_id, round_id,
    &merkle_root,       // reward distribution Merkle root
    &new_weights_uri,   // aggregated model weights
    ...
)?;

보상 청구

트레이너는 머클 증명으로 보상을 청구합니다:

FlJobLifecycle::claim_reward(
    &mut storage, &db, &trainer, &model_id, round_id,
    amount,             // reward amount
    &merkle_proof,      // proof of inclusion in reward distribution
    ...
)?;

재무 수수료

설정 가능한 비율 (fee_treasury_bps, 최대 10000 = 100%)이 네트워크 재무를 위해 보상 풀에서 공제됩니다. 계산은 반올림 오류를 방지하기 위해 고정소수점 산술을 사용합니다.

FL 거버넌스 제안

FL 특화 거버넌스 액션:

SetFlPolicy

FL 매개변수 수정 제안:

ProposalAction::SetFlPolicy {
    fee_treasury_bps: 500,      // 5% treasury fee
    max_models: 100,            // max registered models
    aggregator_whitelist: vec!["addr1", "addr2"],
}

검증: fee_treasury_bps <= 10000, max_models > 0, 허용 목록 비어 있지 않음.

ApproveFlModel

프로덕션 사용을 위한 모델 승인:

ProposalAction::ApproveFlModel {
    model_id: "abc123...64hex",  // 32-byte hex model ID
}

AbortFlRound

활성 훈련 라운드의 긴급 중단:

ProposalAction::AbortFlRound {
    model_id: "abc123...64hex",
    round_id: 5,
}

검증: round_id > 0, 유효한 32바이트 model_id.

스토리지 레이아웃

FL 컨트랙트는 슬롯 100부터 스토리지를 사용합니다:

슬롯 범위	목적
100+	모델 메타데이터
200+	버전 체인
300+	라운드 상태
400+	업데이트 제출
500+	보상 풀
600+	역할 매핑

SDK를 통한 통합

use savitri_sdk::{TransactionBuilder, GovernanceAction};

// FL 거버넌스 제안 생성
let tx = TransactionBuilder::new()
    .create_fl_proposal(
        "governance_contract_address",
        "Approve sentiment model v2",
        "Production-ready model with 95% accuracy",
        604800,  // 7-day voting period
    )
    .nonce(nonce)
    .fee(5_000_000_000_000_000)
    .build_and_sign(&wallet)?;