⛓️ Hackathon-back-25

API backend desarrollada con Node.js, Express y ethers.js para interactuar con un smart contract orientado a la gestión de sesiones, el reporte de consumo, la administración de depósitos y el cierre o cancelación de sesiones.

El proyecto no utiliza base de datos tradicional: toda la lógica de persistencia y estado vive en el contrato inteligente y se consulta o modifica a través de esta API.

📌 Descripción general

Este backend expone un conjunto de endpoints REST bajo /api para:

• iniciar sesiones enviando un precio unitario y un depósito inicial;
• consultar el estado actual de una sesión;
• obtener estadísticas globales del contrato;
• reportar consumo de unidades desde la cuenta del oráculo;
• agregar depósitos a una sesión activa;
• cerrar o cancelar sesiones;
• calcular el costo estimado de un número de unidades;
• verificar si una cantidad de unidades puede consumirse con el estado actual.

La aplicación trabaja con dos proveedores JSON-RPC y dos wallets distintas:

• una wallet principal para operaciones del servicio;
• una wallet de oráculo para reportar consumo.

⚙️ Tecnologías

• Node.js
• Express 5
• ethers.js
• dotenv

🧩 Estructura del proyecto

Hackathon-back-25/
├── index.js
├── package.json
├── README.md
├── .env-example
└── src/
    ├── config.js
    ├── contract-controller.js
    ├── contract-service.js
    └── routes.js

🏗️ Arquitectura

• index.js inicializa Express, habilita JSON en el body y monta el router principal en /api.
• src/routes.js define las rutas públicas del backend.
• src/contract-controller.js valida entrada, transforma datos y devuelve respuestas HTTP.
• src/contract-service.js concentra la interacción directa con el smart contract.
• src/config.js carga variables de entorno, crea los providers, las wallets y las instancias del contrato.

🔌 Variables de entorno

Crear un archivo .env en la raíz del proyecto tomando como base .env-example.

PRIVATE_KEY=""
PRIVATE_KEY_ORACLE=""
RPC_URL=""
RPC_ORACLE_URL=""
CONTRACT_ADDRESS=""
PORT=3000

Descripción

• PRIVATE_KEY: clave privada de la wallet principal.
• PRIVATE_KEY_ORACLE: clave privada de la wallet utilizada para ReportUsage.
• RPC_URL: URL del nodo RPC principal.
• RPC_ORACLE_URL: URL del nodo RPC del oráculo.
• CONTRACT_ADDRESS: dirección del smart contract.
• PORT: puerto donde levantará la API.

🚀 Instalación y ejecucion

# 1. Clonar el repositorio
git clone https://github.com/FernandoJaime/Hackathon-back-25.git
cd Hackathon-back-25

# 2. Instalar dependencias
npm install

# 3. Configurar variables de entorno
copy .env-example .env
# Editar .env con los valores reales

# Ejecucion
npm run dev
npm start

# La API quedará disponible en http://localhost:<PORT>

🛰️ Endpoints

Todos los endpoints están prefijados con /api.

GET

• GET /api/session
  Devuelve la información de la sesión activa: user, deposit, unitPrice, unitsConsumed, totalCost, availableRefund, isActive y startTime.

• GET /api/stats
  Devuelve estadísticas globales del contrato: totalSessions, totalEarnings y contractBalance.

• GET /api/calculate-cost?units=10
  Calcula el costo estimado para una cantidad de unidades.

• GET /api/can-consume?units=10
  Verifica si el contrato permite consumir esa cantidad de unidades.

POST

• POST /api/start-session
  Inicia una nueva sesión.

  Body:

  {
    "unitPrice": "0.00001",
    "deposit": "0.0001"
  }

• POST /api/report-usage
  Reporta consumo de unidades desde la wallet del oráculo.

  Body:

  {
    "units": 50
  }

• POST /api/add-deposit
  Agrega un depósito adicional a la sesión activa.

  Body:

  {
    "amount": "0.00005"
  }

• POST /api/close-session
  Cierra la sesión y liquida fondos.

• POST /api/cancel-session
  Cancela la sesión y devuelve fondos según la lógica del contrato.

🔐 Lógica funcional

• start-session exige unitPrice y deposit.
• El depósito inicial se valida en el controlador y no puede ser menor a 0.0001 ETH.
• report-usage solo acepta unidades mayores a 0.
• calculate-cost y can-consume trabajan con lectura directa del contrato, sin gastar gas.
• La fecha de inicio de la sesión se ajusta a UTC-3 antes de serializarse en la respuesta.

📦 Funciones expuestas por el contrato

El backend consume, entre otras, estas funciones del smart contract:

• StartSession
• getSessionInfo
• getStats
• ReportUsage
• addDeposit
• CloseSession
• CancelSession
• calculateCost
• canConsumeUnits

🧪 Ejemplos de uso

# Consultar sesión activa
curl http://localhost:3000/api/session

# Calcular costo de 25 unidades
curl "http://localhost:3000/api/calculate-cost?units=25"

# Verificar si pueden consumirse 25 unidades
curl "http://localhost:3000/api/can-consume?units=25"

Última actualización

Abril 2026