Archive: System v4 - Estado al 2024-12-24
This commit is contained in:
ARCHITECT
261
v4-archive/contratos-comunes/docs/NOTARIO.md
Normal file
261
v4-archive/contratos-comunes/docs/NOTARIO.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# 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"*
|
||||
Reference in New Issue
Block a user