Configuración del entorno

Esta página explica cómo gestionar las credenciales y la configuración de las que dependen las integraciones de EnergyAS: claves privadas, endpoints RPC y API keys del subgraph.

Credenciales requeridas

Desarrollo local

Crea un archivo .env en la raíz de tu proyecto:

# Operator wallet — manages organizations, projects, and attester lists
PRIVATE_KEY=0x...

# IoT device wallet — submits readings only
DEVICE_PRIVATE_KEY=0x...

# The Graph API key — get one free at thegraph.com/studio → API Keys
THEGRAPH_API_KEY=...

# Optional: custom RPC endpoint (defaults to public RPCs if omitted)
# RPC_URL=https://...

Cárgalo con dotenv:

import 'dotenv/config';

const sdk = await EnergySDK.fromPrivateKey({
  network: 'amoy',
  privateKey: process.env.PRIVATE_KEY,
});

Agrega siempre .env a .gitignore: nunca subas claves privadas al repositorio.

echo ".env" >> .gitignore

Separación de wallets

Usa al menos dos wallets:

Esto limita el alcance de un incidente: si la clave de un dispositivo se compromete, un atacante solo puede enviar lecturas (potencialmente incorrectas) para los proyectos autorizados; no puede modificar la estructura de la organización ni drenar fondos más allá del gas. Rota las claves de dispositivo comprometidas llamando a removeAttester + addAttester desde la wallet del operador.

Pipelines de CI/CD

Guarda las credenciales como secretos de entorno en tu proveedor de CI (GitHub Actions, GitLab CI, etc.); nunca las escribas directamente en scripts ni las subas al control de versiones.

GitHub Actions

# .github/workflows/submit-readings.yml
env:
  PRIVATE_KEY: ${{ secrets.DEVICE_PRIVATE_KEY }}
  THEGRAPH_API_KEY: ${{ secrets.THEGRAPH_API_KEY }}

Define los secretos en Settings → Secrets and variables → Actions de tu repositorio de GitHub.

GitLab CI

# .gitlab-ci.yml
variables:
  PRIVATE_KEY: $DEVICE_PRIVATE_KEY      # set in Settings → CI/CD → Variables
  THEGRAPH_API_KEY: $THEGRAPH_API_KEY

Marca las variables como Masked para que no aparezcan en los logs, y como Protected si solo quieres que estén disponibles en ramas protegidas.

Despliegues con Docker y contenedores

Pasa los secretos como variables de entorno en tiempo de ejecución; nunca los incluyas en las imágenes:

docker run \
  -e PRIVATE_KEY="$DEVICE_PRIVATE_KEY" \
  -e THEGRAPH_API_KEY="$THEGRAPH_API_KEY" \
  your-image:latest

Con Docker Compose, usa un archivo .env en el host:

# docker-compose.yml
services:
  reporter:
    image: your-image:latest
    env_file: .env

En despliegues de producción, prefiere un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) en lugar de archivos .env en texto plano en disco.

API key de The Graph

Tu API key de The Graph es una credencial para leer datos del subgraph. No es un secreto en el mismo sentido que una clave privada (no puede autorizar transacciones), pero tiene un límite de uso asociado a tu cuenta, así que trátala con cuidado:

• No la subas a repositorios públicos
• En apps de frontend, haz pasar las consultas al subgraph por tu backend (para que la clave nunca llegue al navegador) o usa un patrón backend-for-frontend
• La landing page de EnergyAS muestra un proxy basado en nginx: la API key se inyecta en el servidor y nunca se expone en el bundle de JavaScript

Endpoints RPC

El SDK usa por defecto endpoints RPC públicos y gratuitos:

Son adecuados para desarrollo, pero pueden limitar las solicitudes bajo carga sostenida. Para cargas de producción, usa un proveedor de RPC dedicado (Alchemy, QuickNode, Infura, Ankr, etc.) y pasa la URL mediante rpcUrl:

const sdk = await EnergySDK.fromPrivateKey({
  network: 'polygon',
  privateKey: process.env.PRIVATE_KEY,
  rpcUrl: process.env.RPC_URL,
});

Selección de red

Elige la red adecuada para cada etapa:

Nunca mezcles claves de testnet y mainnet en el mismo script: deriva siempre la red de una única variable de entorno:

const network = process.env.NETWORK ?? 'amoy';  // 'polygon' | 'celo' | 'amoy'

const sdk = await EnergySDK.fromPrivateKey({
  network,
  privateKey: process.env.PRIVATE_KEY,
});