Saltearse al contenido
Darwin Evolution

Quickstart

Esta guía te lleva paso a paso por el registro de un evento de cadena de suministro contra la API sandbox de Tracium. Usa el patrón de prepared transaction: el servidor valida y prepara una transacción no firmada; el cliente firma localmente y envía a la chain RPC; opcionalmente registra el txHash con Tracium para que la plataforma rastree confirmación.

Necesitás acceso al sandbox

Para seguir este quickstart end-to-end necesitás un tenant sandbox de Darwin. Sandbox es gratuito, sin tarjeta de crédito.

Pedir sandbox →

Antes de empezar

Sección titulada «Antes de empezar»

  • Credenciales de operador + URL base del sandbox (de tu correo de aprovisionamiento).

  • curl instalado (o cualquier HTTP client).

  • Una wallet/signer del lado del cliente (ethers.js, viem, MetaMask, etc.) para firmar la transacción preparada y enviarla al RPC.

  • Setear BASE_URL a la URL base que recibís en el correo de aprovisionamiento. Reemplazá <API_BASE_URL> por ese valor:

    Ventana de terminal
    export BASE_URL="<API_BASE_URL>"

  1. Autenticarse

    Sección titulada «Autenticarse»

    Login con las credenciales de operador del correo de aprovisionamiento de tu sandbox:

    Ventana de terminal
    curl -X POST "$BASE_URL/api/v2/auth/login" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "operator@sandbox.example.com",
        "password": "tu-password-sandbox"
      }'

    La respuesta contiene accessToken + refreshToken. Si tu cuenta está delimitada a un solo tenant, el accessToken ya está listo. Si pertenecés a múltiples tenants, el token viene partial: true y tenés que llamar POST /api/v2/auth/select-tenant para promoverlo:

    Ventana de terminal
    curl -X POST "$BASE_URL/api/v2/auth/select-tenant" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "tenantId": "<tu-tenant-sandbox-id>" }'
    Ventana de terminal
    export TOKEN="<accessToken>"

  2. Validar el payload del evento

    Sección titulada «Validar el payload del evento»

    Antes de preparar la transacción, validá el evento contra el mapa de procesos del tenant. Esto atrapa errores de schema y campos faltantes sin gastar gas.

    Ventana de terminal
    curl -X POST "$BASE_URL/api/v1/events/validate" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "processType": "RICE_HARVESTING",
        "outputTlc": "TLC-DEMO-001",
        "outputCustodian": "0xTuSandboxOperatorAddress",
        "metadata": {
          "product": "Arroz Koshihikari Orgánico",
          "location": { "lat": 37.5, "lng": 139.9 },
          "quantity": { "value": 500, "unit": "kg" },
          "timestamp": "2026-05-08T08:00:00Z"
        }
      }'

    Respuesta exitosa:

    { "valid": true, "errors": [], "warnings": [] }

    Notá los nombres de campo:

    • processType: clave del mapa de procesos. Cada sandbox tiene procesos distintos según el demo: el sandbox food usa organic-sushi-co, el automotive usa automotive-parts-mx-tier2, el textil textiles-cooperative-latam. Tu correo de aprovisionamiento lista los processType válidos para tu tenant.
    • outputTlc: el TLC del lote a acuñar (string).
    • outputCustodian: wallet address EIP-55 del custodian destino.
    • inputTokenIds: opcional, array de tokenIds (números) si este evento consume lotes existentes (transformación).
    • metadata: objeto libre validado contra el schema del mapa de procesos.

  3. Preparar la transacción on-chain

    Sección titulada «Preparar la transacción on-chain»
    Ventana de terminal
    curl -X POST "$BASE_URL/api/v1/events/prepare" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "processType": "RICE_HARVESTING",
        "outputTlc": "TLC-DEMO-001",
        "outputCustodian": "0xTuSandboxOperatorAddress",
        "metadata": {
          "product": "Arroz Koshihikari Orgánico",
          "location": { "lat": 37.5, "lng": 139.9 },
          "quantity": { "value": 500, "unit": "kg" },
          "timestamp": "2026-05-08T08:00:00Z"
        }
      }'

    Respuesta:

    {
      "eventId": "evt_abc123",
      "ipfsCid": "bafybeig...",
      "preparedTx": {
        "to": "0xContractAddress",
        "data": "0x...",
        "gasEstimate": 250000,
        "chainId": 1337
      }
    }

    En este punto: el servidor validó el payload, lo escribió a IPFS (devuelve el CID), y preparó la transacción no firmada. Nada está on-chain todavía. La clave privada del actor nunca tocó la plataforma.

  4. Firmar + enviar a la chain

    Sección titulada «Firmar + enviar a la chain»

    Esta parte es del lado del cliente: tomá preparedTx.to + preparedTx.data

    • gasEstimate + chainId y enviá la transacción usando tu signer. Ejemplo con ethers.js:
    import { ethers } from 'ethers';
    

    const wallet = new ethers.Wallet(process.env.OPERATOR_PRIV_KEY, provider);
    const tx = await wallet.sendTransaction({
      to: prepared.preparedTx.to,
      data: prepared.preparedTx.data,
      gasLimit: prepared.preparedTx.gasEstimate,
    });
    const receipt = await tx.wait();
    console.log('on-chain', receipt.hash, receipt.blockNumber);

    La URL del RPC y el chainID figuran en el correo de aprovisionamiento de tu sandbox.

  5. (Opcional) Registrar el txHash con Tracium

    Sección titulada «(Opcional) Registrar el txHash con Tracium»

    Para que Tracium rastree la confirmación + emita webhooks event.recorded cuando el bloque sea minado:

    Ventana de terminal
    curl -X POST "$BASE_URL/api/v1/tx/track" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "txHash": "0xa1b2c3..." }'

    Y consultá el estado:

    Ventana de terminal
    curl -X POST "$BASE_URL/api/v1/tx/track/status" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "txHash": "0xa1b2c3..." }'

  6. Verificar la traza

    Sección titulada «Verificar la traza»

    Una vez confirmada, leé el NFT acuñado:

    Ventana de terminal
    curl "$BASE_URL/api/v1/nfts/tlc/TLC-DEMO-001" \
      -H "Authorization: Bearer $TOKEN"

    La respuesta incluye los campos del NFT (tokenId, tlc, status, custodian, metadataCid, metadata, txHash, blockNumber, eventCount, createdAt, etc.).

    Para ver linaje:

    Ventana de terminal
    curl "$BASE_URL/api/v1/nfts/<tokenId>/ancestry" \
      -H "Authorization: Bearer $TOKEN"

Qué pasó

Sección titulada «Qué pasó»

Creaste un Critical Tracking Event para un alimento designado por FSMA 204 (arroz). Tracium:

  1. Validó el payload contra el mapa de procesos del tenant.
  2. Escribió el JSON canónico del evento a IPFS (off-chain, direccionable por CID).
  3. Preparó una transacción blockchain no firmada con el hash del evento.
  4. Vos firmaste y enviaste a la chain RPC (la clave privada nunca tocó la plataforma).
  5. Opcionalmente registraste el txHash para que Tracium rastree confirmación + emita webhooks.
  6. Devolvió el NFT del lote, consultable por TLC.

El mismo TLC va a viajar ahora por la cadena. Cuando registres un evento de proceso (molienda, empaque), Tracium lo enlaza como hijo de este NFT vía inputTokenIds. Para cuando el arroz se envíe, el linaje completo está on-chain con prueba criptográfica en cada paso.

Próximos pasos

Sección titulada «Próximos pasos»