ledgermind
juanfranpaezz/ledgermind
Core de pagos en Java 21 / Spring Boot: ledger de doble entrada append-only, idempotencia y concurrencia segura, con un servidor MCP (OAuth2.1) para auditoria asistida por IA y firma post-cuantica (ML-DSA) del journal.
Instalação
npx convez-ai juanfranpaezz/ledgermind1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
LedgerMind
Core de pagos en Java/Spring Boot: ledger de doble entrada append-only, idempotencia por clave única (exactly-once) y control de concurrencia con optimistic locking + retry (probado con un spike de 50 transferencias concurrentes contra Postgres real), expuesto a un agente de IA por un servidor MCP con OAuth2.1, sobre una escalera de auditabilidad que termina en una firma post-cuántica (ML-DSA / FIPS 204) del journal.
EN — A payments core: append-only double-entry ledger, exactly-once idempotency and explicit concurrency control (optimistic locking + retry, proven by a 50-transfer concurrency spike on real Postgres), exposed to an AI agent through an OAuth2.1-secured MCP server, on an auditability ladder that ends in a post-quantum (ML-DSA / FIPS 204) signature of the journal.
Qué es
LedgerMind es el motor de cuentas y movimientos de una fintech: registra dinero como asientos de doble entrada append-only, impide por construcción (restricción UNIQUE en la DB) que un reintento duplique un cobro (idempotencia), y que el dinero no se cree ni se pierda bajo concurrencia (optimistic locking + retry). Es backend puro.
Encima del ledger hay dos cosas que lo separan de un CRUD:
- Un servidor MCP (Model Context Protocol) que deja a un agente de IA consultar y auditar el ledger — nunca mover dinero —, protegido con OAuth2.1 y scopes mínimos por herramienta.
- Una escalera de auditabilidad que hace el journal tamper-evident: hash-chain → checkpoint firmado con criptografía post-cuántica → una herramienta MCP con la que el propio agente verifica la integridad.
Está construido para ser defendible: cada decisión tiene su porqué y sus límites están escritos, no escondidos (ver Alcance y límites honestos).
Demo
El camino confiable es correr en local (1 comando, ver Cómo correr). También suele haber una instancia de demo efímera en https://childhood-stereo-cookie-praise.trycloudflare.com (puede estar caída).
BASE=http://localhost:8080 # o la instancia de demo
# Crear dos cuentas y transferir (la transferencia es idempotente por idempotencyKey)
curl -s -XPOST $BASE/api/accounts -H 'Content-Type: application/json' \
-d '{"address":"wallet:ana","asset":"ARS","allowNegative":true}'
curl -s -XPOST $BASE/api/accounts -H 'Content-Type: application/json' \
-d '{"address":"wallet:beto","asset":"ARS"}'
curl -s -XPOST $BASE/api/transfers -H 'Content-Type: application/json' \
-d '{"debitAddress":"wallet:ana","creditAddress":"wallet:beto","amount":50000,"idempotencyKey":"demo-1"}'
# Auditar la integridad del journal (mismo dato que ve el agente por MCP)
curl -s $BASE/api/journal/audit
# Flujo OAuth2.1 → MCP (perfil demo): pedir un token y llamar a /mcp con el Bearer
TOKEN=$(curl -s -u mcp-client:secret -d grant_type=client_credentials -d scope=ledger.read \
$BASE/oauth2/token | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')
curl -s -o /dev/null -w '%{http_code}\n' $BASE/mcp # sin token → 401
curl -s $BASE/mcp -H "Authorization: Bearer $TOKEN" # con token → MCP responde
Arquitectura
flowchart TB
U["Cliente REST"]
AG["Agente IA<br/>(MCP client)"]
U -->|HTTP| API["REST API<br/>/api/**"]
AG -->|"MCP · OAuth2.1 Bearer"| MCP["MCP Server<br/>/mcp · scope por tool"]
API --> SVC["LedgerService"]
MCP --> SVC
SVC --> DOM["Dominio del ledger<br/>Account · Posting · TransferService<br/>doble entrada · idempotencia · @Version + retry"]
DOM -->|"escribe asientos (append-only)"| PG[("PostgreSQL<br/>esquema por Flyway")]
subgraph AUD["Auditabilidad — dos jobs @Scheduled INDEPENDIENTES (async, fuera del hot path)"]
CH["JournalChainer<br/>hash-chain SHA-256"]
CHK["JournalCheckpointService<br/>firma ML-DSA-65 (FIPS 204)"]
end
CH -.->|"pollea asientos y los encadena"| PG
CHK -.->|"firma la cabeza de la cadena"| PG
MCP -->|"verify_journal_integrity"| CHK
Es un monolito modular (Spring Modulith): hoy un único bounded context ledger con adaptadores REST (ledger.web) y MCP (ledger.mcp), pensado para dividirse a medida que crezca. El esquema lo manda Flyway; Hibernate solo valida.
La escalera de auditabilidad
| Capa | Qué hace | Qué garantiza (honesto) |
|---|---|---|
| 1 · Hash-chain | Encadena cada asiento: entry_hash = SHA-256(prev_hash ‖ canonical(posting)) en una tabla append-only aparte (patrón AWS QLDB). | Tamper-evidence: editar un asiento ya encadenado rompe la cadena y se detecta el punto exacto. |
| 2 · Checkpoint firmado | Firma la cabeza de la cadena con ML-DSA-65 (post-cuántico, BouncyCastle) en checkpoints append-only (patrón Signed Tree Head). | Ancla la cabeza en el tiempo bajo un compromiso resistente a un futuro falsificador cuántico (forge-later). |
| 3 · Auditor MCP | El tool verify_journal_integrity deja que un agente recomponga la cadena + valide la firma y reciba un veredicto. | Cierra el lazo: el sistema se audita a sí mismo y le explica el resultado a una IA. |
La firma demuestra crypto-agility (interfaz
JournalSignerintercambiable) y tamper-evidence firmado — no es prevención ni reemplaza el control de acceso. Los límites están en Alcance y límites honestos.
Cómo correr
Requisitos: JDK 21 y Docker (para Postgres y para los tests con Testcontainers).
# 1) Postgres local
docker compose up -d
# 2) La app (perfil demo = incluye un Authorization Server embebido para emitir tokens del MCP)
./mvnw spring-boot:run -Dspring-boot.run.profiles=demo
# Tests (spike de concurrencia, runtime real de ML-DSA, enforcement de scope, reconciliación...). Solo necesita Docker:
./mvnw verify
API y herramientas MCP
REST (/api)
| Método | Ruta | Qué hace |
|---|---|---|
POST | /api/accounts | Crea una cuenta. |
GET | /api/accounts/{address} | Saldo y contadores de una cuenta. |
POST | /api/transfers | Transferencia idempotente (doble entrada). |
GET | /api/journal/verify | Recomputa la hash-chain (Capa 1). |
GET | /api/journal/checkpoint | Último checkpoint firmado + clave pública + firma (Capa 2). |
GET | /api/journal/checkpoint/verify | Verifica firma + cadena en planos separados. |
GET | /api/journal/audit | Auditoría consolidada con veredicto legible (= tool MCP). |
POST | /api/reconciliation | Reconcilia un feed de liquidación del PSP contra el ledger (matching determinista por referencia). |
MCP (/mcp, OAuth2.1 — scope ledger.read por tool + validación de audiencia, solo lectura)
| Tool | Qué hace |
|---|---|
get_balance | Saldo de una cuenta. |
list_transactions | Movimientos de una cuenta. |
verify_journal_integrity | Audita la integridad del journal (hash-chain + firma post-cuántica). |
explain_reconciliation_discrepancy | Reconcilia el ledger contra el feed del PSP y devuelve los descuadres clasificados (la IA los narra; el código decide). |
El endpoint /mcp exige un JWT Bearer válido; sin token → 401. En el perfil demo, un Spring Authorization Server embebido emite tokens (client_credentials) en /oauth2/token.
Decisiones de diseño (con su porqué)
- Dinero como enteros (centavos /
BIGINT), nuncadouble— el ledger tiene que cuadrar al centavo. - Saldo derivado de contadores acumulados (
posted_debits/credits) — lectura O(1), journal append-only. - Optimistic locking (
@Version) + retry fuera de la transacción — previene lost updates sin serializar todo. - Idempotencia por
idempotency_keyúnico — un reintento de red nunca duplica un movimiento. - Flyway dueño del esquema, Hibernate solo valida — sin cambios destructivos silenciosos del ORM.
- Testcontainers (Postgres real, no H2) — los tests prueban el locking real de Postgres.
- Todo en UTC (JVM + Hibernate + DB) — timestamps de dinero sin ambigüedad.
Las decisiones formales más relevantes están como ADRs en docs/adr/.
Tests
La suite (./mvnw verify, contra Postgres real), entre otros:
- Spike de concurrencia — 50 transferencias en paralelo sobre una cuenta con saldo limitado: se verifica conservación del dinero, no-sobregiro y doble-entrada global.
- Idempotencia exactly-once — 24 requests con la misma clave en paralelo reciben el mismo asiento (replay, no 500); reusar la clave con otros parámetros → 409.
- Runtime de ML-DSA — prueba que BouncyCastle realmente firma y verifica (no solo que compila), y rechaza datos alterados y claves ajenas.
- Seguridad MCP — enforcement del scope
ledger.readpor tool + el SAS emiteaud=ledgermind-mcp(validación de audiencia). - Tamper-evidence — edita un asiento por SQL directo y verifica que la cadena lo detecta y la firma queda disociada.
- Reconciliación — matcher determinista que cuadra y clasifica los 4 descuadres (incl. refs duplicadas del PSP que se agregan, sin cuadrar en falso).
Alcance y límites honestos
Esto es un proyecto de demostración; los límites están escritos a propósito (son parte del criterio de ingeniería):
- Dinero simulado — es una demostración de capacidad, no un sistema con compliance certificado.
- Clave de firma efímera — se genera al arranque. En producción la privada vive en HSM/KMS y la pública se ancla fuera de la DB; la verificación de firma prueba integridad-de-mensaje, no autenticidad del firmante sin ese ancla.
- Tamper-EVIDENCE, no prevención — un actor con escritura total en la DB puede reescribir contenido + cadena + checkpoint de forma consistente; lo que sube el costo y lo hace detectable es anclar externamente (HSM + log de transparencia + WORM). La auditoría no detecta por sí sola el truncado de la cola sin un high-water-mark externo.
/apiabierto en la demo — solo/mcpestá bajo OAuth (con validación de audiencia); en producción el read-model también iría con auth. Los endpoints/api/demo/*(reset/tamper) existen solo bajo el perfildemoy están rate-limitados.verify()es O(n) — a escala real, el paso siguiente es Merkle + verificación incremental desde el último checkpoint.- Reconciliación con feed simulado — el matching es por referencia + importe exactos (sin tolerancia, ventana T+N ni multi-moneda); en prod el feed vendría del archivo real del PSP y se reconciliaría por ventana. Asume
idempotencyKey == id de orden del clientecomo eje de correlación.
Stack
Java 21 · Spring Boot 3.5 · Spring Modulith · Spring AI 1.1 (MCP server) · Spring Security / OAuth2.1 · PostgreSQL 16 + Flyway · BouncyCastle (ML-DSA / FIPS 204) · Testcontainers · Actuator + Micrometer/Prometheus · Docker · GitHub Actions.
LedgerMind is a payments backend in Java/Spring Boot: an append-only double-entry ledger with exact integer money, exactly-once idempotency, and explicit concurrency control (optimistic locking + retry), proven by a Testcontainers concurrency test. It exposes read-only MCP tools (Spring AI) to an AI agent behind an OAuth2.1 resource server with per-tool scopes and audience validation (confused-deputy defense). On top sits a three-layer auditability ladder: a SHA-256 hash-chain (tamper-evidence), a post-quantum ML-DSA / FIPS 204 signature of the chain head (Signed Tree Head), and an MCP tool (verify_journal_integrity) that lets the agent audit the journal itself. A reconciliation module deterministically matches a PSP settlement feed against the ledger and classifies discrepancies (the AI only narrates them; the code decides). Limitations (ephemeral demo key, tamper-evidence vs prevention, O(n) verification, simulated feed) are documented on purpose. See docs/adr/ for the rationale behind each decision.