# Oracle Centralizado — Documentación Técnica

**Versión:** 2.0.0  
**Actualizado:** 2026-06-27  

---

## Introducción

Oracle Centralizado es una infraestructura de datos financieros en tiempo real,
diseñada para alimentar contratos inteligentes en BNB Smart Chain (BSC) y proveer
información de mercado precisa al ecosistema cripto venezolano.

Opera con múltiples fuentes independientes —mercado libre y fuentes oficiales—
sincronizadas cada minuto. Ningún precio depende de una única fuente; el sistema
agrega, valida y persiste cada valor con trazabilidad completa.

El destino final del Oracle es servir como capa de datos verificable para
contratos inteligentes que ejecuten una economía real basada en modelos de paridad
1:1 entre activos digitales y existencias reales, asegurando que nuestro sistema
monetario no otorga derechos sobre bienes físicos, sino que ofrece soluciones
nativas en la blockchain BSC.

## API REST — Endpoints

Base URL: https://oraculo.criptoinversiones.net/api/

Todas las respuestas son JSON. No se requiere API key.
Rate limit: 100 peticiones/minuto por IP (excepto /api/health.php: 30/min).

| Endpoint | Descripción | Detalle |
|---|---|---|
| `GET /api/health.php` | Estado del sistema | Conectividad de fuentes, última sincronización, conteo de activos |
| `GET /api/rates.php` | 143 tasas | FIAT + Spot crypto + USD/VES. Filtro ?iso= para búsqueda directa |
| `GET /api/rates_ves.php` | USD/VES multi-fuente | Binance P2P, Yadio, EnParaleloVzla, DolarToday, GoldT API (BCV) |
| `GET /api/commodities.php` | 24 commodities globales | Energía, metales, agrícolas. OHLC + variación 24h vía Yahoo Finance |
| `GET /api/history.php` | Histórico 1-minuto | Parámetros: type=rates|commodities, date=YYYYMMDD, ticker=, limit= |

## Límites de Uso

• Rate limiting: 100 peticiones/minuto por IP (token bucket).
• Endpoint /api/health.php: 30 peticiones/minuto.
• Histórico: máximo 90 días de retención.
• Sin autenticación requerida para consultas GET.
• El uso abusivo o automatizado sin pausa entre peticiones resultará
  en bloqueo temporal de la IP.
• Los datos se actualizan cada 60 segundos vía cron interno.

## Aplicaciones del Ecosistema

El Oracle Centralizado es la columna vertebral de datos del ecosistema GoldT.
Las siguientes aplicaciones consumen sus endpoints:

| App | URL | Descripción |
|---|---|---|
| **GoldT** | goldt.criptoinversiones.net | Token GOLDT (1g oro sintético), vault GOLDVE, terminal OTC. Consume tasas USD/VES y precios de commodities para minteo y conversiones. |
| **Binance Oracle** | binance.criptoinversiones.net | Feed de precios P2P y Spot. Fuente secundaria de USD/VES con respaldo del Oracle Centralizado. |
| **Deriv Widget** | oraculo2.criptoinversiones.net | Widget de estadísticas financieras con Chart.js. Visualización de históricos y tendencias. |
| **Contratos Inteligentes BSC** | Blockchain | Los contratos GoldTokenBase.sol, Oracle.sol y GOLDVE.sol consumen precios on-chain para ejecutar conversiones, minteo y distribución de fees. |

## Modelo Económico — Contratos Inteligentes

El Oracle está diseñado para alimentar contratos inteligentes en BNB Smart Chain (BSC)
que ejecutan una economía real basada en paridad 1:1 entre activos digitales y
existencias reales. Este sistema monetario no otorga derechos sobre bienes físicos;
son soluciones nativas en la blockchain BSC.

Los inversores pueden convertir BNB al token de su elección (GOLDT, FIAT_G,
commodities) y negociarlos en el mercado real con productores o especuladores.
Cada conversión ejecuta un fee del 1% sobre el token transado, que forma parte
del beneficio del creador del sistema.

Flujo de conversión:
1. Usuario envía BNB al contrato GoldTokenBase
2. El contrato consulta el precio vía Oracle (precio congelado 24h)
3. Se mintea el token correspondiente menos el fee del 1%
4. El usuario puede mantener, transferir o negociar el token
5. El fee se distribuye al vault GOLDVE como beneficio del creador

## Token GOLDVE — Vault de Participación

GOLDVE es el token de participación del vault del sistema. Su valor es asignado
por la lógica del contrato GOLDVE.sol en BSC, no por mercado externo.

Características fundamentales:
• Es receptor de BNB/DAI únicamente aportados por el creador o donantes.
• No es redimible por usuarios diferentes al creador.
• La única vía de liquidar GOLDVE es cuando el creador decide invertir
  sus tokens en economía real o financiera, extrayendo los BNB auto-ahorrados
  en el vault.
• Esta condición solo es válida si el creador dispone de GOLDVE propios.

GOLDVE representa la participación en el vault que acumula los fees de todas
las conversiones del sistema (1% por transacción). Funciona como un mecanismo
de ahorro forzoso: cada conversión deja un excedente en el vault, y ese
excedente solo puede ser extraído por el creador mediante la quema de sus
propios tokens GOLDVE.

Este diseño asegura que:
• El creador tiene incentivo alineado con el crecimiento del sistema.
• Los usuarios tienen garantía de que los fees no son extraíbles arbitrariamente.
• El vault funciona como reserva de valor auto-acumulable.

## Estructura de Fees

• GOLDT: 0.05% por conversión (BNB → GOLDT)
• FIAT_G: 1% por conversión (BNB → FIAT_G)
• Commodities: 1% por conversión (BNB → CommodityToken)
• Todos los fees se dirigen al vault GOLDVE.
• El creador puede extraer BNB del vault quemando GOLDVE propios.
• Sin comisiones por transferencias entre usuarios.
• Límite máximo por wallet: 10,000 GOLDT.
• Depósito mínimo: 0.001 BNB. Máximo: 100 BNB por transacción.

## Arquitectura Técnica

• Servidor: Hostinger shared hosting, PHP 8.3.30, Composer 2.9.8
• Framework: PHP vanilla sin dependencias MVC
• HTTP Client: Guzzle 7.12 con HTTP/2 y pool concurrente
• Logger: Monolog 3.10 con RotatingFileHandler (30 días)
• Config: Dotenv 5.6 (variables de entorno fuera de public_html)
• Cache: Archivos JSON planos en storage/cache/
• Histórico: CSV por día con rotación 90 días
• Base de datos: MariaDB 11.8.6 (goldt.criptoinversiones.net)
• Fuente commodities: Yahoo Finance v8 chart API (sin API key)
• Fuente USD/VES: Binance P2P (primaria), Yadio, GoldT API (BCV)

## Seguridad

• Rate Limiter: Token bucket por IP (archivos JSON en storage/cache/ratelimit)
• Auditoría: Todas las consultas logueadas con IP hash, endpoint, status
• HSTS: Strict-Transport-Security max-age=31536000, includeSubDomains
• CSP: Content-Security-Policy restrictiva por endpoint
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Sin API key: El diseño es de lectura pública; el abuso se mitiga vía rate limiting
• .env fuera de public_html: Credenciales nunca expuestas en la web

## Firma Criptográfica

Todas las respuestas de la API incluyen un campo _signature con firma
ECDSA sobre curva secp256k1. Esto permite verificar la autenticidad e
integridad de los datos tanto off-chain como on-chain en BSC.

Cada respuesta incluye:
• value: Firma DER en hex sobre el mensaje timestamp.nonce.json_data
• algorithm: ecdsa-secp256k1
• public_key: Clave pública en hex (DER SubjectPublicKeyInfo)
• timestamp: UNIX timestamp en milisegundos
• nonce: 16 bytes aleatorios en hex

La clave pública está disponible en /api/public-key.php.
Para verificar en Solidity: keccak256(message) → ecrecover(hash, v, r, s).

---

*Documentación generada desde Oracle Centralizado v2.0.0*