{ "title": "Oracle Centralizado — Documentación Técnica", "version": "2.0.0", "updated": "2026-06-26", "sections": [ { "id": "intro", "title": "Introducción", "content": [ "Oracle Centralizado es una infraestructura de datos financieros en tiempo real,\ndiseñada para alimentar contratos inteligentes en BNB Smart Chain (BSC) y proveer\ninformación de mercado precisa al ecosistema cripto venezolano.\n\nOpera con múltiples fuentes independientes —mercado libre y fuentes oficiales—\nsincronizadas cada minuto. Ningún precio depende de una única fuente; el sistema\nagrega, valida y persiste cada valor con trazabilidad completa.", "El destino final del Oracle es servir como capa de datos verificable para\ncontratos inteligentes que ejecuten una economía real basada en modelos de paridad\n1:1 entre activos digitales y existencias reales, asegurando que nuestro sistema\nmonetario no otorga derechos sobre bienes físicos, sino que ofrece soluciones\nnativas en la blockchain BSC." ] }, { "id": "endpoints", "title": "API REST — Endpoints", "content": [ "Base URL: https:\/\/oraculo.criptoinversiones.net\/api\/", "Todas las respuestas son JSON. No se requiere API key.\nRate limit: 100 peticiones\/minuto por IP (excepto \/api\/health.php: 30\/min)." ], "endpoints": [ [ "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=" ] ] }, { "id": "limits", "title": "Límites de Uso", "content": [ "• Rate limiting: 100 peticiones\/minuto por IP (token bucket).\n• Endpoint \/api\/health.php: 30 peticiones\/minuto.\n• Histórico: máximo 90 días de retención.\n• Sin autenticación requerida para consultas GET.\n• El uso abusivo o automatizado sin pausa entre peticiones resultará\n en bloqueo temporal de la IP.\n• Los datos se actualizan cada 60 segundos vía cron interno." ] }, { "id": "apps", "title": "Aplicaciones del Ecosistema", "content": [ "El Oracle Centralizado es la columna vertebral de datos del ecosistema GoldT.\nLas siguientes aplicaciones consumen sus endpoints:" ], "apps": [ [ "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." ] ] }, { "id": "economy", "title": "Modelo Económico — Contratos Inteligentes", "content": [ "El Oracle está diseñado para alimentar contratos inteligentes en BNB Smart Chain (BSC)\nque ejecutan una economía real basada en paridad 1:1 entre activos digitales y\nexistencias reales. Este sistema monetario no otorga derechos sobre bienes físicos;\nson soluciones nativas en la blockchain BSC.", "Los inversores pueden convertir BNB al token de su elección (GOLDT, FIAT_G,\ncommodities) y negociarlos en el mercado real con productores o especuladores.\nCada conversión ejecuta un fee del 1% sobre el token transado, que forma parte\ndel beneficio del creador del sistema.", "Flujo de conversión:\n1. Usuario envía BNB al contrato GoldTokenBase\n2. El contrato consulta el precio vía Oracle (precio congelado 24h)\n3. Se mintea el token correspondiente menos el fee del 1%\n4. El usuario puede mantener, transferir o negociar el token\n5. El fee se distribuye al vault GOLDVE como beneficio del creador" ] }, { "id": "goldve", "title": "Token GOLDVE — Vault de Participación", "content": [ "GOLDVE es el token de participación del vault del sistema. Su valor es asignado\npor la lógica del contrato GOLDVE.sol en BSC, no por mercado externo.", "Características fundamentales:\n• Es receptor de BNB\/DAI únicamente aportados por el creador o donantes.\n• No es redimible por usuarios diferentes al creador.\n• La única vía de liquidar GOLDVE es cuando el creador decide invertir\n sus tokens en economía real o financiera, extrayendo los BNB auto-ahorrados\n en el vault.\n• 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\nlas conversiones del sistema (1% por transacción). Funciona como un mecanismo\nde ahorro forzoso: cada conversión deja un excedente en el vault, y ese\nexcedente solo puede ser extraído por el creador mediante la quema de sus\npropios tokens GOLDVE.", "Este diseño asegura que:\n• El creador tiene incentivo alineado con el crecimiento del sistema.\n• Los usuarios tienen garantía de que los fees no son extraíbles arbitrariamente.\n• El vault funciona como reserva de valor auto-acumulable." ] }, { "id": "fees", "title": "Estructura de Fees", "content": [ "• GOLDT: 0.05% por conversión (BNB → GOLDT)\n• FIAT_G: 1% por conversión (BNB → FIAT_G)\n• Commodities: 1% por conversión (BNB → CommodityToken)\n• Todos los fees se dirigen al vault GOLDVE.\n• El creador puede extraer BNB del vault quemando GOLDVE propios.\n• Sin comisiones por transferencias entre usuarios.\n• Límite máximo por wallet: 10,000 GOLDT.\n• Depósito mínimo: 0.001 BNB. Máximo: 100 BNB por transacción." ] }, { "id": "tech", "title": "Arquitectura Técnica", "content": [ "• Servidor: Hostinger shared hosting, PHP 8.3.30, Composer 2.9.8\n• Framework: PHP vanilla sin dependencias MVC\n• HTTP Client: Guzzle 7.12 con HTTP\/2 y pool concurrente\n• Logger: Monolog 3.10 con RotatingFileHandler (30 días)\n• Config: Dotenv 5.6 (variables de entorno fuera de public_html)\n• Cache: Archivos JSON planos en storage\/cache\/\n• Histórico: CSV por día con rotación 90 días\n• Base de datos: MariaDB 11.8.6 (goldt.criptoinversiones.net)\n• Fuente commodities: Yahoo Finance v8 chart API (sin API key)\n• Fuente USD\/VES: Binance P2P (primaria), Yadio, GoldT API (BCV)" ] }, { "id": "security", "title": "Seguridad", "content": [ "• Rate Limiter: Token bucket por IP (archivos JSON en storage\/cache\/ratelimit)\n• Auditoría: Todas las consultas logueadas con IP hash, endpoint, status\n• HSTS: Strict-Transport-Security max-age=31536000, includeSubDomains\n• CSP: Content-Security-Policy restrictiva por endpoint\n• X-Frame-Options: DENY\n• X-Content-Type-Options: nosniff\n• Sin API key: El diseño es de lectura pública; el abuso se mitiga vía rate limiting\n• .env fuera de public_html: Credenciales nunca expuestas en la web" ] }, { "id": "signing", "title": "Firma Criptográfica", "content": [ "Todas las respuestas de la API incluyen un campo _signature con firma\nECDSA sobre curva secp256k1. Esto permite verificar la autenticidad e\nintegridad de los datos tanto off-chain como on-chain en BSC.", "Cada respuesta incluye:\n• value: Firma DER en hex sobre el mensaje timestamp.nonce.json_data\n• algorithm: ecdsa-secp256k1\n• public_key: Clave pública en hex (DER SubjectPublicKeyInfo)\n• timestamp: UNIX timestamp en milisegundos\n• nonce: 16 bytes aleatorios en hex", "La clave pública está disponible en \/api\/public-key.php.\nPara verificar en Solidity: keccak256(message) → ecrecover(hash, v, r, s)." ] } ] }