system-docs/05_INTEGRACIONES/notario.md

Notario

Versión: 2.0
Estado: Especificación

---

Descripción

Sistema de sellado inmutable en blockchain. Última capa de confianza del ecosistema.

┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO NOTARIO                            │
│                                                                 │
│           "Lo que NOTARIO sella, nadie lo altera"              │
└─────────────────────────────────────────────────────────────────┘

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                         NOTARIO                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Feldman (bloques consolidados)                                │
│        │                                                        │
│        │ (auditados por SENTINEL)                              │
│        ▼                                                        │
│  ┌─────────────────┐                                           │
│  │ BATCH COLLECTOR │  Agrupa por ventana temporal              │
│  └─────────────────┘                                           │
│        │                                                        │
│        ▼                                                        │
│  ┌─────────────────┐                                           │
│  │ MERKLE BUILDER  │  Construye árbol Merkle                   │
│  └─────────────────┘                                           │
│        │                                                        │
│        ▼                                                        │
│  ┌─────────────────┐                                           │
│  │ BLOCKCHAIN TX   │  Publica hash raíz                        │
│  └─────────────────┘                                           │
│        │                                                        │
│        ▼                                                        │
│  Registro actualizado con blockchain_tx_ref                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Dos Franjas Temporales

Franja Interna

Tiempo del sistema para:

• Procesar operaciones
• Ejecutar auditoría SENTINEL
• Consolidar en Feldman

Duración: Minutos a horas

Franja Blockchain

Tiempo de NOTARIO para:

• Agrupar registros en batches
• Construir pruebas criptográficas
• Publicar en blockchain
• Confirmar transacciones

Duración: Horas a días

---

Ciclo de Sellado

1. RECOLECTAR
   SELECT FROM feldman_bloques
   WHERE audit_status = 'DEEP_PASS'
   AND blockchain_tx_ref IS NULL

2. AGRUPAR
   Crear batch con ventana temporal (ej: 24h)
   Asignar notario_batch_id

3. CONSTRUIR MERKLE
   - Ordenar registros por h_bloque
   - Calcular hash de cada registro
   - Construir árbol binario
   - Obtener merkle_root

4. FIRMAR
   - Firmar merkle_root con llave NOTARIO
   - Generar timestamp certificado

5. PUBLICAR
   - Enviar transacción a blockchain
   - Esperar confirmaciones

6. ACTUALIZAR
   UPDATE feldman_bloques SET blockchain_tx_ref = tx_hash

---

Schema SQL

CREATE TABLE notario_batches (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  batch_id UUID UNIQUE NOT NULL,
  
  -- Ventana temporal
  window_start TIMESTAMPTZ NOT NULL,
  window_end TIMESTAMPTZ NOT NULL,
  
  -- Contenido
  records_count INTEGER NOT NULL,
  bloque_hashes TEXT[] NOT NULL,
  
  -- Merkle
  merkle_root CHAR(64) NOT NULL,
  merkle_tree JSONB,
  
  -- Firma
  signature TEXT NOT NULL,
  signing_key_id VARCHAR(100),
  signed_at TIMESTAMPTZ NOT NULL,
  
  -- Blockchain
  blockchain_network VARCHAR(50) DEFAULT 'ethereum',
  blockchain_tx_ref VARCHAR(100),
  blockchain_block BIGINT,
  blockchain_timestamp TIMESTAMPTZ,
  confirmations INTEGER DEFAULT 0,
  
  -- Estado
  status VARCHAR(20) DEFAULT 'PENDING',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  
  CONSTRAINT valid_status CHECK (
    status IN ('PENDING', 'SUBMITTED', 'CONFIRMED', 'FAILED')
  )
);

CREATE INDEX idx_notario_status ON notario_batches(status);
CREATE INDEX idx_notario_window ON notario_batches(window_start, window_end);

---

Verificación de Integridad

def verify_record_integrity(h_bloque, notario_batch_id):
    # 1. Obtener batch
    batch = get_batch(notario_batch_id)
    
    # 2. Verificar que h_bloque está en el batch
    assert h_bloque in batch.bloque_hashes
    
    # 3. Obtener registro de Feldman
    record = get_feldman_record(h_bloque)
    
    # 4. Calcular hash del registro
    record_hash = sha256(serialize(record))
    
    # 5. Verificar inclusión en merkle tree
    proof = get_merkle_proof(batch.merkle_tree, h_bloque)
    assert verify_merkle_proof(record_hash, proof, batch.merkle_root)
    
    # 6. Verificar firma del batch
    assert verify_signature(
        batch.merkle_root, 
        batch.signature, 
        batch.signing_key_id
    )
    
    # 7. Verificar que merkle_root está en blockchain
    tx = get_blockchain_tx(batch.blockchain_tx_ref)
    assert tx.data == batch.merkle_root
    
    return True

---

Integración con S-CONTRACT

Campos en Response (pre-sellado)

"audit": {
  "blockchain_pending": true,
  "blockchain_tx_ref": null,
  "notario_batch_id": "uuid-batch"
}

Campos post-sellado

"audit": {
  "blockchain_pending": false,
  "blockchain_tx_ref": "0x1234...abcd",
  "notario_batch_id": "uuid-batch"
}

---

Configuración

notario:
  enabled: true
  
  # Ventana de agregación
  batch_window_hours: 24
  min_records_per_batch: 10
  max_records_per_batch: 10000
  
  # Blockchain
  network: ethereum
  contract_address: "0x..."
  gas_limit: 100000
  
  # Firma
  signing_key: kv://production/signing/notario
  
  # Reintentos
  max_retries: 3
  retry_delay_minutes: 60

---

Pendiente

• Crear tabla notario_batches
• Implementar recolector de registros
• Implementar constructor Merkle tree
• Configurar llave de firma
• Integrar con proveedor blockchain
• Implementar verificador de integridad
• Crear workflow de sellado periódico