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 server 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 free, 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 mail de provisioning).

  • curl instalado (o cualquier HTTP client).

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

  • Setear BASE_URL a tu URL de sandbox:

    Ventana de terminal
    export BASE_URL="https://sandbox.<region>.darwinevolution.io"

  1. Autenticarse

    Sección titulada «Autenticarse»

    Login con las credenciales de operador del mail de provisioning 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á scopeada 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 process map 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 process map. 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 mail de provisioning 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 process map.

  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 server validó el payload, lo escribió a IPFS (devuelve el CID), y preparó la transacción no firmada. Nada está on-chain todavía. El private key del actor nunca tocó la plataforma.

  4. Firmar + enviar a la chain

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

    Esta parte es client-side: 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);

    El RPC del sandbox lo da el mail de provisioning (Geth chainID 1337 self-hosted en rpc.sandbox.darwin.ahteslabs.com o similar).

  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, …).

    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 process map del tenant.
  2. Escribió el JSON canónico del evento a IPFS (off-chain, addressable 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 tracke confirmación + emita webhooks.
  6. Devolvió el NFT del lote, queryable por TLC.

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

Próximos pasos

Sección titulada «Próximos pasos»