# NOTARIO - Sistema de Sellado Blockchain
**Version:** 2.0
**Dependencia:** `S-CONTRACT.md`
**Estado:** Especificacion

---

# 1. Introduccion

NOTARIO es el modulo responsable del **sellado inmutable** de registros criticos en blockchain. Opera como la ultima capa de confianza del ecosistema GRACE.

```
+---------------------------------------------------------------------+
|                    PRINCIPIO NOTARIO                                 |
|                                                                      |
|   "Lo que NOTARIO sella, nadie lo altera"                           |
+---------------------------------------------------------------------+
```

---

# 2. Arquitectura

```
+---------------------------------------------------------------------+
|                         NOTARIO                                      |
+---------------------------------------------------------------------+
|                                                                      |
|  SYS_LOG (Libro Diario)                                             |
|        |                                                             |
|        | (procesos completados + auditados)                          |
|        v                                                             |
|  +-----------------+                                                 |
|  | BATCH COLLECTOR |  Agrupa registros por ventana temporal          |
|  +-----------------+                                                 |
|        |                                                             |
|        v                                                             |
|  +-----------------+                                                 |
|  | MERKLE BUILDER  |  Construye arbol Merkle del batch               |
|  +-----------------+                                                 |
|        |                                                             |
|        v                                                             |
|  +-----------------+                                                 |
|  | BLOCKCHAIN TX   |  Publica hash raiz en blockchain                |
|  +-----------------+                                                 |
|        |                                                             |
|        v                                                             |
|  SYS_LOG (UPDATE blockchain_tx_ref)                                 |
|                                                                      |
+---------------------------------------------------------------------+
```

---

# 3. Dos Franjas Temporales

## 3.1 Franja Interna

Tiempo del sistema para:
- Procesar operaciones
- Ejecutar auditoria SENTINEL
- Preparar datos para consolidacion

**Duracion tipica**: Minutos a horas

## 3.2 Franja Blockchain

Tiempo de NOTARIO para:
- Agrupar registros en batches
- Construir pruebas criptograficas
- Publicar en blockchain
- Confirmar transacciones

**Duracion tipica**: Horas a dias (segun volumen y costos)

---

# 4. Ciclo de Sellado

```
1. RECOLECTAR
   - Query SYS_LOG WHERE audit_status = 'DEEP_PASS'
   - AND blockchain_pending = FALSE
   - 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 trace_id
   - Calcular hash de cada registro
   - Construir arbol binario
   - Obtener merkle_root

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

5. PUBLICAR
   - Enviar transaccion a blockchain
   - Esperar confirmaciones

6. ACTUALIZAR
   - UPDATE SYS_LOG SET blockchain_tx_ref = tx_hash
   - INSERT NOTARIO_BATCHES con detalles
```

---

# 5. Tabla NOTARIO_BATCHES

```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,
  trace_ids             UUID[] 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',

  -- Metadata
  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);
```

---

# 6. Verificacion de Integridad

Para verificar que un registro no ha sido alterado:

```python
def verify_record_integrity(trace_id, notario_batch_id):
    """
    Verifica que un registro esta incluido en un batch sellado.
    """
    # 1. Obtener batch
    batch = get_batch(notario_batch_id)

    # 2. Verificar que trace_id esta en el batch
    assert trace_id in batch.trace_ids

    # 3. Obtener registro
    record = get_syslog_record(trace_id)

    # 4. Calcular hash del registro
    record_hash = sha256(serialize(record))

    # 5. Verificar inclusion en merkle tree
    proof = get_merkle_proof(batch.merkle_tree, trace_id)
    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 esta en blockchain
    tx = get_blockchain_tx(batch.blockchain_tx_ref)
    assert tx.data == batch.merkle_root

    return True
```

---

# 7. Integracion con S-CONTRACT

## 7.1 Campos en Response

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

## 7.2 Campos post-sellado

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

---

# 8. Configuracion

```yaml
notario:
  enabled: true

  # Ventana de agregacion
  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
```

---

# 9. Checklist de Implementacion

- [ ] 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 periodico
- [ ] Configurar alertas para fallos

---

**Fin del Documento NOTARIO - Version 2.0**

*Sistema GRACE - "Lo que NOTARIO sella, nadie lo altera"*