Saltar al contenido principal

Light Curate: integración para desarrolladores

Esta página trata Light Curate (V1). Para Curate V2, consulta la sección de Curate para desarrolladores.
Classic Curate está en proceso de retirada. Los contratos de Classic Curate siguen desplegados y sin cambios, por lo que las listas Classic existentes siguen funcionando: todavía se pueden enviar, impugnar y consultar elementos. Kleros no lanzará nuevos registros en Classic Curate, y se está desactivando la creación de listas Classic desde los frontends de Kleros. Light Curate y Stake Curate no se ven afectados y siguen siendo totalmente compatibles; las nuevas listas, incluidos los registros Kleros Verified que aparecen en la página de inicio de la aplicación Curate, se crean en Light Curate.

Descripción general

Light Curate reduce considerablemente los costes de despliegue y funcionamiento respecto a Curate Classic al cambiar la estrategia de almacenamiento de los datos:
  • Los datos de los elementos NO se almacenan en el almacenamiento del contrato. En la cadena solo se almacena el multihash de IPFS. El coste de almacenamiento es O(1) en lugar de O(n).
  • Los campos de los elementos se almacenan en el subgraph mediante la API de IPFS de The Graph. No se necesita @kleros/gtcr-encoder.
  • Usa el proxy mínimo EIP-1167 para los despliegues. El coste de despliegue bajó de ~7M a ~700K de gas.
Contrapartida: otros contratos no pueden consultar al TCR los valores de los campos en la cadena (solo está disponible el hash de IPFS).

Leer datos

Obtener los elementos mediante el subgraph

Light Curate usa las entidades litems (con el prefijo l). Pasa la dirección del TCR para filtrar:
El campo props contiene directamente los campos decodificados del elemento. No se necesita ninguna biblioteca de codificación.

Obtener un elemento concreto

Las entidades de los elementos tienen ID con el formato <itemID>@<listAddress>:

Contrato View

Hay un contrato View disponible para obtener toda la información relevante en una sola llamada. Despliegue en Gnosis Chain: 0x08e58Bc26CFB0d346bABD253A1799866F269805a

Escribir datos

Enviar un elemento

  1. Sube los datos del elemento a IPFS (usa tanto el endpoint de IPFS de The Graph como el nodo IPFS de Kleros)
  2. Llama a addItem() en el contrato LightGeneralizedTCR con la URI de IPFS y el depósito exigido
Fija los datos en nodos IPFS que controles, además de en los de The Graph y Kleros.

Impugnar y ejecutar solicitudes

  • Impugnar: llama a challengeRequest() con un depósito
  • Ejecutar: llama a executeRequest() una vez transcurrido el periodo de impugnación sin impugnaciones

Estándar de MetaEvidence

MetaEvidence es la única fuente de verdad en la cadena tanto para la política legible por personas como para el esquema de los elementos legible por máquinas. Resuélvelo siempre en vivo a partir de los eventos de la cadena. Nunca lo codifiques de forma fija, lo guardes en caché ni lo deduzcas.

Dos flujos independientes

Light Curate (LGTCR) requiere dos documentos de MetaEvidence separados: Normalmente ambos se emiten en el despliegue (por convención, _metaEvidenceID = 0 para el registro y = 1 para la retirada), pero el governor de un registro puede publicar un nuevo MetaEvidence, lo que incrementa el ID. Nunca supongas que solo existen los ID 0 y 1; toma siempre el último evento aplicable de cada flujo.

Obtención

  1. Consulta eth_getLogs sobre la dirección del registro, filtrando por el topic del evento MetaEvidence:
  2. Ordena los registros coincidentes por blockNumber, después por transactionIndex y después por logIndex.
  3. Obtén cada puntero de IPFS de _evidence mediante un gateway (por ejemplo, https://cdn.kleros.link/ipfs/<hash>). No dupliques el prefijo /ipfs/.
  4. Clasifica cada JSON como de registro o de retirada según el contenido de su title/description/opciones de fallo (“Add” frente a “Remove”), no según el orden de los registros. Algunas transacciones del governor emiten un evento de registro seguido inmediatamente de uno de retirada en el mismo bloque.
  5. Usa el último evento que corresponda a la operación que estás realizando. Si la clasificación es ambigua, detente y consulta a una persona.

Forma del MetaEvidence en producción

El MetaEvidence de retirada usa exactamente la misma forma, con title/description/question orientados a la retirada, y reutiliza las mismas metadata.columns. metadata.columns es el esquema autorizado del registro: cada item.json enviado debe contener una copia profunda idéntica de este array. Usa sustantivos comunes en minúsculas para itemName/itemNamePlural (por ejemplo, "token", "tokens").

Requisitos de los campos

Al llamar a deploy(...) de la fábrica, pasa primero la URI del MetaEvidence de registro y después la de retirada. El constructor asigna _metaEvidenceID por posición. Bloqueos absolutos (no despliegues): el JSON no se analiza; metadata.columns falta o está vacío; alguna columna usa un type no admitido; falta fileURI; falta logoURI en producción; la política no es un PDF y no se aceptó el riesgo; no se han validado ambos flujos.

Estándar de item.json

item.json se sube a IPFS y se referencia en la cadena mediante addItem(string _item).
Reglas de construcción (innegociables):
  • columns debe ser una copia profunda literal de las MetaEvidence.metadata.columns activas (mismas etiquetas, descripciones, tipos, indicadores isIdentifier y mismo orden). Incluso corregir la gramática incumple el contrato.
  • values es la única parte dinámica.
  • Object.keys(values) debe ser exactamente igual a columns.map(c => c.label), en el mismo orden. Sin claves que falten, sobren, cambien de nombre o de orden.
  • Nunca reconstruyas el esquema a partir de textos de la interfaz, capturas de pantalla, documentación antigua o de memoria; obtén siempre metadata.columns del MetaEvidence activo en ese momento.
Fallos habituales que hay que rechazar en la revisión: renombrar una etiqueta, reordenar las columnas, reescribir las descripciones, cambiar isIdentifier, usar type: "url" o enviar valores parciales o provisionales.

Estándar de tipos de campo

Solo estas cadenas de tipo son válidas para las columnas de Curate V1 (GTCR). No uses las grafías exclusivas de V2 salvo que un MetaEvidence activo demuestre que esa grafía ya está en producción para la lista. Alias prohibidos: url → link; string → text; markdown → long text; bool → boolean; integer/int/float/decimal → number; longText/richAddress/chain (grafías de V2) → long text/rich address. Usar un tipo no admitido se manifiesta como un error de la interfaz, como Unhandled input type url. Reglas de los identificadores: se requiere al menos una columna identificadora; se admiten hasta cinco; image, file y long text nunca deben ser identificadores. Para los registros de tokens multicadena, es preferible rich address a address simple.

Estándar de rich address

rich address es un valor al estilo CAIP que hace referencia a una dirección en una cadena concreta, lo que evita la ambigüedad de una cadena 0x... sin más:
Espacios de nombres: eip155 (cadenas EVM), bip122 (tipo Bitcoin), solana, tvm (TON), stacks. Entre los ID de referencia habituales de eip155 están Ethereum Mainnet 1, Optimism 10, BNB Smart Chain 56, Gnosis 100, Polygon 137, Base 8453, Arbitrum One 42161, Avalanche 43114, Linea 59144 y Sepolia 11155111. Nunca deduzcas la cadena de destino de una rich address a partir del contexto; confírmala siempre explícitamente. Una dirección simple resuelta con un referenceId equivocado apunta sin avisar a otra cuenta en otra cadena.

Cálculo de los depósitos

Los depósitos de Curate V1 se pagan íntegramente en el token nativo de la cadena (ETH en Mainnet/Sepolia, xDAI en Gnosis). Nunca codifiques un depósito de forma fija. Los parámetros de los depósitos los controla la gobernanza. Calcúlalos en vivo con lecturas en la cadena justo antes de construir una transacción. El frontend solo muestra el depósito base; enviar solo ese importe como msg.value hace que se revierta, porque el contrato exige el depósito base más el coste del arbitraje en un único valor. arbitrationCost se obtiene a partir de registry.arbitrator() y registry.arbitratorExtraData() y, después, de IArbitrator(arbitrator).arbitrationCost(extraData). Financiación de las apelaciones: requiredForSide = appealCost + appealCost * feeStakeMultiplier / MULTIPLIER_DIVISOR, donde el multiplicador es sharedStakeMultiplier() (todavía no hay fallo), winnerStakeMultiplier() (la parte coincide con el fallo actual) o loserStakeMultiplier() (la parte se opone a él). La parte perdedora debe financiar antes de la mitad del plazo de apelación.

Interfaz del contrato (LightGeneralizedTCR)

Funciones de escritura:
_side en fundAppeal usa la enumeración Party: 0 = None, 1 = Requester, 2 = Challenger. Funciones de lectura clave: submissionBaseDeposit(), removalBaseDeposit(), submissionChallengeBaseDeposit(), removalChallengeBaseDeposit(), challengePeriodDuration(), arbitrator(), arbitratorExtraData(), winnerStakeMultiplier(), loserStakeMultiplier(), sharedStakeMultiplier(), MULTIPLIER_DIVISOR(), getItemInfo(bytes32), getRequestInfo(bytes32, uint256). Eventos clave:
Fábrica: deploy(address _arbitrator, bytes _arbitratorExtraData, address _connectedTCR, string _registrationMetaEvidence, string _clearingMetaEvidence, address _governor, uint256[4] _baseDeposits, uint256 _challengePeriodDuration, uint256[3] _stakeMultipliers, address _relayContract), que emite NewGTCR(address). No codifiques de forma fija la dirección de la fábrica; verifícala en cada cadena. Auxiliar View: LightGeneralizedTCRView.fetchArbitrable(address) devuelve todos los parámetros de los depósitos en una sola llamada. Úsalo para las lecturas agregadas; usa las lecturas directas del contrato como verdad final para los valores críticos.

Verificación del registro

Antes de tocar el MetaEvidence o los depósitos de una dirección que no conoces:
  1. Confirma que el chainId es el previsto (Mainnet 1, Sepolia 11155111, Gnosis 100).
  2. Llama a eth_getCode(listAddress) en esa cadena. Si el resultado es 0x, no es un contrato en esa cadena; detente.
  3. Realiza una lectura característica (submissionBaseDeposit() o arbitrator()). Si se revierte, no es una instancia válida de LGTCR; detente.

Enviar un elemento (de principio a fin)

  1. Obtén el último MetaEvidence de registro.
  2. Lee la política en fileURI antes de construir nada.
  3. Construye item.json a partir de metadata.columns; si es tu primer envío, realiza una auditoría de desviación del esquema frente a una muestra reciente de NewItem.
  4. Sube item.json a IPFS para obtener /ipfs/<hash>.
  5. Calcula el depósito en vivo: submissionBaseDeposit() + arbitrationCost.
  6. Simula la transacción con los mismos calldata y msg.value.
  7. Llama a addItem("/ipfs/<hash>") con msg.value = deposit.
Desplegar una lista no hace que sea visible en el frontend de Curate: también debe registrarse en la lista de listas. Desde agosto de 2026, la lista de listas (los registros Kleros Verified de la página de inicio de Curate) funciona en Light Curate, en 0x2418D887d0d0Fe03b793A6aF4321fa488226A0b5 en Gnosis y en 0x2aCF59a420cA888f46d46974f62570F8a38Cd4Da en la red principal de Ethereum.

Convenciones del subgraph

Las direcciones deben estar en minúsculas en las consultas. El subgraph no entiende las direcciones con checksum. El servicio alojado tiene un límite de 1000 elementos por consulta. Para los registros más grandes, pagina con skip o id_gt.

Despliegue del subgraph

Si desplegaste una lista con la fábrica, ya tiene un subgraph desplegado y disponible. Para los despliegues personalizados, consulta la documentación de The Graph.

Recursos

Contratos de Light Curate

Código fuente

Ejemplos de consultas

Más ejemplos de consultas GraphQL