Arquitectura Técnica

Candidatura al premio SCF Build · Pista de Integración
Proyecto: Agentes Comunitarios REAL8: inclusión financiera sobre Stellar, empezando por Venezuela
Versión: 1.0 · 23/04/2026

1. Resumen ejecutivo

REAL8 es un activo nativo de Stellar lanzado en 2018 con una misión de inclusión financiera en comunidades desatendidas, inspirado en el Real de a Ocho — la primera moneda de reserva mundial, acuñada en la Casa de la Moneda de México en 1538. Esta propuesta de premio Build plantea la construcción de una red de agentes comunitarios: una plataforma de operadores independientes, con presencia local, que compran y venden REAL8 a cambio de una comisión, acercando el activo a personas excluidas de los circuitos bancarios convencionales. El mercado piloto es Venezuela, donde el levantamiento parcial de sanciones de la OFAC al Banco Central de Venezuela (Licencia General nº 57, abril de 2026) ha eliminado el riesgo legal bloqueante para este tipo de trabajo.

La red se construye sobre la infraestructura ya existente de REAL8: aplicación de monedero, puente multicadena, servidor de federación SEP-2, integración con MoneyGram, pasarela de pago Stripe y monitor de arbitraje — todos ya en producción. Este premio Build financia las superficies nuevas necesarias para lanzar la red de agentes: alta del agente, anclaje del contrato, supervisión on-chain de la actividad, pago de bonificaciones, paneles de agente y de administración, y medidas de mitigación de fraude.

2. Alcance del proyecto

Entregables dentro del alcance (ventana de 3 a 5 meses)

Flujo de alta del agente — recogida de documentación KYC, cribado de riesgo (OFAC SDN, PEP), flujo de aprobación, vinculación de cuenta Stellar.
Firma del contrato y anclaje on-chain — contrato en PDF firmado fuera de cadena, hash SHA-256 anclado en Stellar mediante una transacción con memo, más una firma tipo SEP-10 en la que el agente firma con su clave para registrar la aceptación de los términos en cadena.
Panel del agente — tablero de autoservicio para cada agente: operaciones, conteo de clientes únicos, bonificación mensual estimada, histórico de pagos, uso de límites.
Panel de administración (equipo REAL8) — aprobación de agentes, suspensión, auditoría, revisión manual de bonificaciones grandes, panel de señales de fraude.
Indexador de actividad on-chain — indexador respaldado por PostgreSQL que sigue los pagos salientes de REAL8 desde las cuentas Stellar de los agentes, los clasifica (venta a cliente, transferencia interna, dirección excluida) y mantiene agregados mensuales.
Tarea mensual de bonificación — proceso programado que calcula la bonificación del 5% por agente, verifica el umbral de 25 clientes únicos y paga automáticamente en REAL8 a la cuenta Stellar del agente (con un umbral configurable por encima del cual se requiere auditoría manual).
Capa de mitigación de fraude — antigüedad mínima de cuenta, tamaño mínimo de transacción, detección de patrones sospechosos, lista blanca para transferencias que no son ventas.
Interfaz bilingüe (español e inglés) — siguiendo las convenciones de internacionalización ya establecidas en el monedero REAL8.

Expresamente fuera de alcance

Custodia de efectivo o depósitos en garantía — el agente opera con su propio inventario de REAL8; REAL8.org nunca custodia sus activos ni su dinero fiduciario.
KYC del cliente final — el agente es responsable de conocer a su cliente.
Contratos de gobernanza en Soroban — se considerará en una segunda versión; no entra en este premio Build.

3. Arquitectura general

┌───────────────────────┐          ┌───────────────────────────┐
│   agent.real8.org     │          │    admin panel (w.real8)  │
│   (agent dashboard)   │          │  (REAL8 team operations)  │
└──────────┬────────────┘          └────────────┬──────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────────────────────────────────────────────────┐
│             api.real8.org  (Express + TypeScript)             │
│  /agents · /agents/:id · /agents/:id/bonification · /admin/*  │
└──────────────────────────────┬────────────────────────────────┘
                               │
      ┌────────────────────────┼────────────────────────┐
      ▼                        ▼                        ▼
┌──────────┐          ┌─────────────────┐      ┌─────────────────┐
│PostgreSQL│          │ OFAC / SDN API  │      │ Stellar Horizon │
│ real8_   │          │ (Treasury gov)  │      │  (public node)  │
│ bridge   │          └─────────────────┘      └─────────────────┘
└──────────┘
      │
      ▼
┌────────────────────────────────────────────────────────────────┐
│                     Background services                         │
│                                                                 │
│   agent-activity-indexer    monthly-bonification-job            │
│   (follows agent accounts,  (runs 1st of month,                 │
│    classifies payments)      pays 5% to qualifying agents)      │
└────────────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────────────┐
│         Stellar Public Network                                  │
│                                                                 │
│   REAL8 issuer · Agent accounts · Bonification distribution     │
│   Federation ([email protected]) · Contract-anchor transactions   │
└────────────────────────────────────────────────────────────────┘

Todos los componentes nuevos se integran detrás del back-end Express existente de api.real8.org y comparten su base de datos PostgreSQL (real8_bridge), capa de autenticación, middleware de geobloqueo MaxMind, limitadores de tasa y servicio de correo Postmark. El indexador y la tarea de bonificación se ejecutan como procesos PM2 adicionales junto a los servicios existentes real8-moneygram-api y bridge-automation.

4. Piezas de Stellar integradas

La Pista de Integración es específicamente para proyectos que «incorporan piezas existentes de Stellar». Esta propuesta integra:

Pieza	Uso
Federación SEP-2	Cada agente recibe una dirección de federación `[email protected]` mediante el servidor de federación ya en producción (tabla `federation_records`). Los clientes operan con direcciones legibles en lugar de cuentas G... sin procesar.
Autenticación web SEP-10	El inicio de sesión del agente en el panel usa autenticación SEP-10, reutilizando el endpoint `/auth` y el flujo de firma ya utilizados para MoneyGram. Se adapta añadiendo una transacción XDR de «aceptación de términos» que el agente firma para dejar constancia de la firma del contrato en cadena.
Multifirma nativa de Stellar	Las cuentas Stellar de los agentes pueden configurarse opcionalmente como multifirma 2 de 3 para mayor seguridad de inventarios grandes — multifirma nativa, sin la sobrecarga de un contrato inteligente.
API Streaming de Horizon	El indexador de actividad del agente usa el endpoint `/accounts/:id/payments` de Horizon con persistencia del cursor (patrón reutilizado de `stellarMonitorService.ts`, ya en producción para el puente).
Memos de transacción Stellar	El anclaje del contrato escribe el SHA-256 del PDF firmado en el campo `memo_hash` de una transacción entre REAL8 y la cuenta del agente, produciendo un registro verificable y con sello de tiempo sin infraestructura adicional.
Pagos clásicos de REAL8	El pago de la bonificación es un pago estándar del activo REAL8 desde una cuenta distribuidora dedicada hacia la cuenta del agente — reutilizando el patrón de distribución con secuencia aislada que ya se usa para la pasarela Stripe.

Todas son primitivas nativas de Stellar, probadas en producción. El proyecto no requiere extensiones personalizadas del protocolo Stellar; compone SEPs y operaciones existentes en una red de inclusión financiera coherente.

5. Modelo de datos

Tablas nuevas de PostgreSQL en la base de datos existente real8_bridge:

-- Perfil del agente
CREATE TABLE agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  stellar_address TEXT UNIQUE NOT NULL,
  federation_name TEXT UNIQUE,
  country_iso2 CHAR(2) NOT NULL,
  kyc_status TEXT NOT NULL,           -- pending | approved | suspended | revoked
  kyc_documents JSONB,
  contract_anchor_tx TEXT,            -- hash de la tx con memo SHA-256
  contract_pdf_sha256 TEXT,
  bonification_auto_max_usd NUMERIC(10,2),
  daily_volume_cap_usd NUMERIC(10,2),
  monthly_volume_cap_usd NUMERIC(10,2),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  approved_at TIMESTAMPTZ,
  suspended_at TIMESTAMPTZ
);

-- Estado del indexador — una fila por agente
CREATE TABLE agent_activity_cursor (
  agent_id UUID PRIMARY KEY REFERENCES agents(id),
  last_horizon_cursor TEXT,
  last_indexed_at TIMESTAMPTZ
);

-- Pagos salientes clasificados desde la cuenta del agente
CREATE TABLE agent_transactions (
  id BIGSERIAL PRIMARY KEY,
  agent_id UUID REFERENCES agents(id),
  stellar_tx_hash TEXT UNIQUE NOT NULL,
  destination_account TEXT NOT NULL,
  real8_amount NUMERIC(20,7) NOT NULL,
  usd_equivalent NUMERIC(20,2),
  classification TEXT NOT NULL,       -- client_sale | internal_transfer | exchange | excluded
  classification_reason TEXT,
  counted_for_bonification BOOLEAN NOT NULL,
  ledger_closed_at TIMESTAMPTZ NOT NULL,
  indexed_at TIMESTAMPTZ DEFAULT NOW()
);

-- Agregados mensuales y bonificación
CREATE TABLE agent_monthly_summary (
  id BIGSERIAL PRIMARY KEY,
  agent_id UUID REFERENCES agents(id),
  month DATE NOT NULL,
  eligible_sales_real8 NUMERIC(20,7) DEFAULT 0,
  eligible_sales_usd NUMERIC(20,2) DEFAULT 0,
  unique_clients INT DEFAULT 0,
  unique_client_threshold INT NOT NULL,
  threshold_met BOOLEAN DEFAULT FALSE,
  bonification_real8 NUMERIC(20,7),
  bonification_status TEXT,           -- pending | approved | paid | held_for_audit
  bonification_paid_tx TEXT,
  audit_notes TEXT,
  UNIQUE(agent_id, month)
);

-- Lista blanca de direcciones excluidas (exchanges, monederos del propio agente, tesorería de REAL8, etc.)
CREATE TABLE agent_exclusion_addresses (
  stellar_address TEXT PRIMARY KEY,
  kind TEXT NOT NULL,                 -- exchange | agent_own | real8_treasury | other
  notes TEXT,
  added_at TIMESTAMPTZ DEFAULT NOW()
);

Durante la tarea de bonificación se usa bloqueo a nivel de fila (SELECT ... FOR UPDATE) sobre agent_monthly_summary, siguiendo el mismo patrón atómico adoptado para los límites de liberación del puente (tabla bridge_releases, api v1.6.1).

6. Flujos principales

6.1 Alta del agente

El aspirante a agente se registra en agent.real8.org/signup: correo electrónico, país, cuenta Stellar (nueva o existente).
Los documentos KYC se suben a almacenamiento cifrado (envoltura AES-256-GCM, siguiendo el mismo patrón de cifrado ya empleado para las claves privadas de airdrop, api v1.6.4).
Cribado contra la lista SDN de la OFAC mediante la API pública del Tesoro de Estados Unidos.
El equipo de REAL8 revisa en el panel de administración, aprueba o rechaza. Tras la aprobación: se crea el registro de federación; se genera el PDF del contrato con los datos legales y Stellar del agente precargados.
El agente firma el PDF fuera de cadena (DocuSign o equivalente — se decide en el arranque).
Se calcula el SHA-256 del PDF firmado y se escribe en el memo de una transacción Stellar desde la tesorería de REAL8 hacia la cuenta del agente, junto con una XDR estilo SEP-10 que el agente firma para dejar constancia de la aceptación.
El hash de la transacción de anclaje se almacena en agents.contract_anchor_tx. El agente queda operativo.

6.2 Venta al cliente (observada, no intermediada)

REAL8.org no interviene en la transacción. El agente vende REAL8 desde su propia cuenta Stellar a un cliente que le ha pagado en moneda local. Desde nuestro lado:

El agent-activity-indexer consulta Horizon /accounts/:id/payments para cada agente aprobado (cadencia de 30 s, cursor persistido).
Por cada pago saliente de REAL8:
- Se comprueba el destino contra agent_exclusion_addresses → si coincide, se clasifica como internal_transfer o exchange (no cuenta).
- Se comprueba la antigüedad del destino (fecha de creación de la trustline y primera operación vía Horizon): si alguna es < 30 días, se clasifica como pending_review (no cuenta en este ciclo, se marca para auditoría).
- Se comprueba si el destino ha tenido al menos una operación previa con una contraparte distinta del agente: si no, se marca para revisión antifraude.
- Se comprueba el importe: si es < mínimo configurable (por defecto 50 REAL8 ≈ 5 $), se clasifica como below_threshold (no cuenta).
- En caso contrario se clasifica como client_sale y se inserta en agent_transactions con counted_for_bonification = true.
Agregación de clientes únicos: un esquema HyperLogLog por agente y mes (usando la extensión hll de PostgreSQL) para contar cuentas únicas con precisión sin guardar listas completas más tiempo del necesario.

6.3 Ciclo mensual de bonificación

El día 1 de cada mes a las 03:00 UTC:

Para cada agente aprobado, se agregan las agent_transactions del mes anterior con counted_for_bonification = true.
Se aplica el umbral progresivo de clientes únicos: 5 (mes 1) → 15 (2) → 20 (3) → 25 (mes 4 en adelante).
Si se alcanza el umbral: se calcula el 5% de bonificación en REAL8 usando la cotización REAL8/USD al cierre del periodo obtenida del servicio de precios.
Si la bonificación > agent.bonification_auto_max_usd (por defecto 500 $): se marca como held_for_audit y se avisa al administrador.
En caso contrario: se ejecuta un pago atómico — bloqueo de fila sobre agent_monthly_summary, envío del pago Stellar desde la cuenta distribuidora de bonificaciones, guardado del hash y marcado como paid.
Se envía un correo por agente vía Postmark (bilingüe ES/EN) con el desglose detallado.

6.4 Suspensión y apelaciones

El administrador puede suspender a cualquier agente desde el panel. La suspensión detiene la indexación y congela cualquier bonificación pendiente. Las apelaciones se registran como filas en el log de auditoría para la traza de cumplimiento.

7. Diseño antifraude

El riesgo de seguridad más relevante es que un agente cree cuentas Stellar falsas como destinos y se auto-pague para cobrar la bonificación del 5% sobre actividad inexistente. El coste del ataque sin mitigaciones es de unos 3 € para 25 cuentas falsas, y la bonificación podría ser arbitrariamente alta. Mitigaciones en capas aplicadas en esta arquitectura:

Antigüedad mínima de la cuenta (30 días) sobre las cuentas destinatarias — aumenta el coste del ataque e introduce una ventana de 30 días para detectarlo.
Requisito de contraparte previa — el destino debe haber tenido al menos una operación previa con alguien distinto del agente, lo que rompe los esquemas puramente cerrados sobre sí mismos.
Tamaño mínimo por transacción — por debajo de 50 REAL8 (≈ 5 $) no cuenta, lo que evita la inflación por micropagos.
Techo configurable de pago automático — por defecto 500 $; por encima de ese importe, revisión manual.
Detección de patrones — racimos de cuentas destino con fechas de creación compartidas, IPs compartidas (en cualquier superficie propia de REAL8 que hayan tocado) o identificadores Stellar secuenciales se marcan.
Fianza del agente (opcional) — depósito reembolsable de 100 REAL8 en el alta, que se pierde si se detecta fraude; configurable por agente desde el panel de administración.

Las mitigaciones son de nivel de implementación y configurables — la combinación concreta a activar se confirmará con Anselmo (co-líder del proyecto, responsable de las decisiones del lado de negocio, seguimiento en la incidencia #60 de GitHub) durante el hito de arranque.

8. Pila técnica

Capa	Tecnología	Notas
Frontal (paneles de agente y administración)	React 19 + Vite 8 + MUI 7 + TypeScript 5.8	Coincide con la pila existente del monedero `app.real8.org`; librería de componentes compartida
Back-end	Express 5.2 + TypeScript 5.8 sobre Node 20	Mismo código base que `api.real8.org` — se añaden rutas nuevas, no hay un servicio separado
Base de datos	PostgreSQL 15	Misma instancia `real8_bridge` — tablas nuevas, infraestructura existente
SDK de Stellar	`@stellar/stellar-sdk 14.6.1`	Ya en uso para puente, federación y precios
Tareas en segundo plano	Procesos PM2 + node-cron	Patrón probado con `bridge-automation`
Correo electrónico	Postmark mediante el servicio emailService existente	Bilingüe ES/EN
Geobloqueo	Middleware basado en MaxMind ya existente (api v1.6.0)	Señales de país y ASN de hosting ya en producción
Hosting	VPS Webdock (`api.real8.org`)	Infraestructura de producción actual

No requiere infraestructura nueva. Todo el trabajo se integra limpiamente en la pila existente.

9. Entregables e hitos

Hito	Duración	Entregable
H1 — Arranque y congelación del esquema	Semanas 1–2	Configuración final de mitigaciones antifraude con Anselmo; migración del esquema de base de datos; roles de usuario administrador
H2 — Alta del agente y anclaje del contrato	Semanas 3–5	Flujo de registro, recogida KYC, cribado OFAC, generación del PDF, anclaje on-chain y aceptación SEP-10
H3 — Indexador de actividad y lista de exclusión	Semanas 6–8	Lector de Horizon con persistencia de cursor, motor de clasificación, interfaz de administración de exclusiones
H4 — Panel del agente y federación	Semanas 9–11	Tablero del agente (operaciones, progreso de clientes únicos, bonificación estimada), emisión de `[email protected]`
H5 — Panel de administración y tarea de bonificación	Semanas 12–14	Cola de revisión del administrador, flujo de auditoría manual, cron mensual de bonificación con pago automatizado
H6 — Endurecimiento, auditoría externa y lanzamiento piloto	Semanas 15–18	Revisión de seguridad externa, pruebas de penetración, simulacros de fraude, revisión bilingüe de UX, alta de los 3 primeros agentes piloto en Venezuela

Entregable final: una red de agentes operativa y auditable, con al menos 3 agentes piloto dados de alta operando con REAL8 en Venezuela.

10. Riesgos y dependencias

Revisión legal específica para Venezuela: la está gestionando en paralelo el responsable administrativo del proyecto (Anselmo). La Licencia General nº 57 de la OFAC (abril de 2026) elimina el bloqueo principal, pero la confirmación legal específica del país es un paso obligado antes del piloto en producción.
Elección del proveedor de KYC: diferida al H1. Candidatos: Sumsub, Onfido. Alternativa: recogida manual de documentos con revisión interna durante la ventana piloto.
DocuSign o equivalente: pequeña dependencia externa para la firma del PDF fuera de cadena. Puede sustituirse por cualquier proveedor de firma que devuelva un PDF canónico cuyo SHA-256 se pueda calcular.
Dependencia de la infraestructura de Stellar: todas las operaciones usan Horizon público; el Horizon de SDF es el objetivo principal, con nodos de la comunidad como respaldo.

11. Relación con la infraestructura REAL8 existente

Este premio Build extiende — no reemplaza — la infraestructura de producción actual de REAL8. Componentes ya desplegados sobre los que se apoya esta propuesta:

app.real8.org (monedero, v4.4.0) — librería de componentes compartida y primitivas de autenticación.
api.real8.org (back-end, v1.7.0) — aquí viven las nuevas rutas de agente; se reutilizan la federación SEP-2, la autenticación SEP-10, el geobloqueo MaxMind, el correo Postmark, la pasarela Stripe y los canales de precios.
real8-bridge (wREAL8 multicadena) — el panel del agente expone el puente wREAL8 para agentes que operan en regiones multicadena, reutilizando la automatización del puente existente.
Monitor de arbitraje v3.4 — los agentes pueden consultar la profundidad de mercado de REAL8 desde su panel para un precio informado.

El efecto neto es una plataforma de inclusión financiera cohesionada y anclada en Stellar, donde la red de agentes se convierte en la última milla humana de una pila tecnológica nativa de Stellar, madura y en producción.

Fuente e historial de versiones: github.com/REAL8-crypto/governance