Aprendizaje Federado (FL)

Savitri Network incluye un sistema de Aprendizaje Federado en cadena para el entrenamiento descentralizado de modelos de IA. Los contratos FL gestionan el registro de modelos, las rondas de entrenamiento, el envío de actualizaciones, la distribución de recompensas y la gobernanza.

Arquitectura

Governance (proposals + voting)
    │
    ▼
Model Registry
    │ register model, assign roles, version tracking
    ▼
Job Lifecycle
    │ create round → open → submit updates → seal → finalize
    ▼
Reward Pool
    │ Merkle-proof reward claims
    ▼
Trainers + Aggregators

Registro de Modelos

Los modelos se registran en cadena con metadatos, versionado y control de acceso basado en roles.

Registro de un Modelo

// Register a new model
FlModelRegistry::register_model(
    &mut storage,
    &db,
    &creator,           // [u8; 32] - model creator address
    "sentiment-v1",     // model name
    "ipfs://Qm.../meta", // metadata URI
    "MIT",              // license URI
    "ipfs://Qm.../weights", // initial weights URI
    &mut events,
    Some(&mut gas),
)?;

Versionado de Modelos

Los modelos tienen cadenas de versiones inmutables. Cada nueva versión referencia a su versión padre:

v1 (initial) → v2 (fine-tuned) → v3 (production)

Los metadatos de versión incluyen:

• metadata_uri: Descripción de la arquitectura del modelo
• weights_uri: Ubicación de los pesos entrenados
• aggregator: Dirección que produjo esta versión
• parent_version: Enlace a la versión anterior

Control de Acceso Basado en Roles (RBAC)

Rol	Permisos
Creator	Registrar modelos, gestionar versiones, establecer políticas
Viewer	Leer metadatos y versiones del modelo
Trainer	Enviar actualizaciones de entrenamiento a rondas
Aggregator	Agregar actualizaciones, finalizar rondas, producir versiones

El acceso de entrenadores se controla mediante listas de permitidos/denegados por modelo.

Gestión de Políticas

Cada modelo tiene políticas configurables:

Política	Descripción
access_policy_hash	Quién puede acceder a los datos del modelo
reward_policy_hash	Cómo se distribuyen las recompensas
max_trainers	Máximo de entrenadores concurrentes
aggregator_whitelist	Agregadores aprobados

Ciclo de Vida de Trabajos

El entrenamiento FL se organiza en rondas con un ciclo de vida definido:

Planned → Open → Sealed → Finalized
                    ↘ Aborted (via governance)

Estados de Ronda

Estado	Descripción	Acciones Permitidas
Planned	Ronda creada, aún no acepta actualizaciones	Abrir
Open	Acepta actualizaciones de entrenadores	Enviar actualización, Sellar
Sealed	Sin más actualizaciones, agregación en progreso	Finalizar, Abortar
Finalized	Recompensas distribuidas, ronda completa	Reclamar recompensas
Aborted	Ronda cancelada mediante gobernanza	Ninguna

Crear una Ronda

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

Enviar Actualización de Entrenamiento

Los entrenadores envían actualizaciones del modelo durante la fase Abierta:

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),
)?;

Protección contra repetición: cada entrenador tiene un nonce por ronda que debe incrementarse estrictamente.

Sellar y Finalizar

// Seal round (stop accepting updates)
FlJobLifecycle::seal_round(&mut storage, &db, &aggregator, &model_id, round_id, ...)?;

// Finalize round (distribute rewards)
FlJobLifecycle::finalize_round(
    &mut storage, &db, &aggregator, &model_id, round_id,
    &merkle_root,       // reward distribution Merkle root
    &new_weights_uri,   // aggregated model weights
    ...
)?;

Reclamar Recompensas

Los entrenadores reclaman recompensas con pruebas de Merkle:

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

Tarifa al Tesoro

Un porcentaje configurable (fee_treasury_bps, máximo 10000 = 100%) se deduce del fondo de recompensas para el tesoro de la red. El cálculo usa aritmética de punto fijo para prevenir errores de redondeo.

Propuestas de Gobernanza FL

Acciones de gobernanza específicas para FL:

SetFlPolicy

Proponer cambios en los parámetros FL:

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

Validación: fee_treasury_bps <= 10000, max_models > 0, lista blanca no vacía.

ApproveFlModel

Aprobar un modelo para uso en producción:

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

AbortFlRound

Abortar de emergencia una ronda de entrenamiento activa:

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

Validación: round_id > 0, model_id válido de 32 bytes.

Disposición del Almacenamiento

Los contratos FL usan ranuras de almacenamiento a partir del 100:

Rango de Ranulas	Propósito
100+	Metadatos del modelo
200+	Cadenas de versiones
300+	Estado de ronda
400+	Envíos de actualizaciones
500+	Fondos de recompensas
600+	Mapeos de roles

Integración mediante el SDK

use savitri_sdk::{TransactionBuilder, GovernanceAction};

// Create FL governance proposal
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)?;