CuyTrace — Documentación del Proyecto

1) Resumen

CuyTrace es una DApp (React + Vite + Ethers v6) para trazabilidad de carne de cuy usando blockchain (Sepolia). Cada actor (Granja, Acopio, Logística, Retail, SENASA) interactúa con el contrato mediante MetaMask. Los documentos (certificados/actas) se suben a IPFS (Pinata) y se registra su URL/hash en blockchain.

Incluye una vista pública Public Trace accesible por URL/QR (/track/:id) que permite consultar trazabilidad sin MetaMask (solo lectura vía RPC).

2) Requisitos

• Node.js 18+ recomendado
• NPM (incluido con Node)
• MetaMask (para módulos que firman transacciones)

3) Instalación y ejecución local

1. Instalar dependencias:

   npm install

2. Crear .env en la raíz (ver sección 4).
3. Ejecutar:

   npm run dev

4) Variables de entorno (.env)

Importante: Vite solo expone variables que comienzan con VITE_.

4.1 Variables obligatorias

• VITE_CONTRACT_ADDRESS
  • Dirección del contrato desplegado en Sepolia.

4.2 Variables para trazabilidad pública (recomendadas)

• VITE_PUBLIC_RPC_URL

  • RPC HTTP para lecturas sin MetaMask.
  • Ejemplo:

    VITE_PUBLIC_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com

• VITE_PUBLIC_APP_URL

  • URL pública del frontend (para que el QR apunte al dominio real y no a localhost).
  • Ejemplo (Render):

    VITE_PUBLIC_APP_URL=Aqui va el link de tu aplicación desplegada

4.3 Variables para IPFS (Pinata)

• VITE_PINATA_JWT
  • JWT de Pinata para subir archivos.

4.4 Variables de wallets por rol (para login automático por MetaMask)

Estas direcciones se usan en el frontend para detectar el rol del usuario conectado:

VITE_WALLET_PRODUCER=0x...
VITE_WALLET_PROCESSOR=0x...
VITE_WALLET_LOGISTICS=0x...
VITE_WALLET_RETAIL=0x...
VITE_WALLET_AUDITOR=0x...

5) Configuración en MetaMask

• Red: Sepolia Testnet
• Importar/usar las cuentas correspondientes a los roles:
  • Producer (Granja)
  • Processor (Acopio)
  • Logistics (Transporte)
  • Retail (Supermercado Wong)
  • Auditor (SENASA)

Nota: la app detecta el rol comparando la address conectada con las variables VITE_WALLET_*.

6) Deploy en Render

6.1 Build / Start

Este proyecto es estático (Vite). En Render normalmente:

• Build Command: npm install && npm run build
• Publish Directory: dist

6.2 Environment Variables en Render

En el panel de Render agrega:

• VITE_CONTRACT_ADDRESS
• VITE_PUBLIC_RPC_URL
• VITE_PUBLIC_APP_URL=Aqui va el link de tu aplicación desplegada
• VITE_PINATA_JWT
• VITE_WALLET_*

Importante: al cambiar variables VITE_* debes hacer redeploy porque quedan embebidas en el build.

7) Flujo de uso en la aplicación (demo)

7.1 Producer (Granja)

• Conectar con MetaMask (cuenta Producer)
• Subir PDF origen a IPFS
• Crear/acuñar lote (se obtiene un ID)
• Transferir custodia a Acopio

7.2 Processor (Acopio)

• Subir PDF HACCP
• Procesar lote
• Transferir custodia a Logística

7.3 Logistics (Transporte)

• Reportar IoT (temperatura + GPS)
• Entregar a Retail
  • La UI bloquea la entrega si el lote no fue inspeccionado/aprobado por SENASA o si está rechazado.

7.4 Retail (Supermercados Wong)

• Aceptar recepción (visual)
• Rechazar lote (on-chain)
  • Botones se bloquean si ya fue rechazado / ya se aceptó el mismo ID.

7.5 Auditor (SENASA)

• Subir acta a IPFS
• Registrar inspección (aprobado/no aprobado)
  • Botones se bloquean si ya fue inspeccionado o rechazado.

7.6 Public Trace (Cliente final)

• Consultar el lote por:
  • /trace (buscador)
  • /track/:id (QR)
• Funciona sin MetaMask.

8) Contrato Inteligente

8.1 Enlace al explorer (Sepolia)

• Contrato (ejemplo):
  • https://sepolia.etherscan.io/address/0x1890dAd0ecFb664abBA5aF94CFCCcE6112786ff7

El contrato inteligente de CuyTrace está implementado en Solidity. Puedes encontrar el código fuente en contracts/CuyTrace.sol.

8.2 Funcionalidades principales

• Gestión de lotes
• Transferencia de custodia
• Inspecciones SENASA
• Alertas IoT