262 lines
7.0 KiB
Markdown
262 lines
7.0 KiB
Markdown
|
# 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"*
|