Saltar al contenido principal

Cómo funciona el arbitraje de Kleros con Reality.eth

Antes de integrarte, comprende el flujo de escalada:
  1. Se formula una pregunta en Reality.eth y quienes responden depositan fianzas.
  2. Cada nueva respuesta debe duplicar la fianza anterior (por ejemplo, 0,01 ETH → 0,02 → 0,04 ETH). Esto incentiva económicamente las respuestas correctas.
  3. Si nadie impugna la pregunta dentro del periodo timeout (normalmente 24 horas), la última respuesta se finaliza.
  4. Si una parte no está de acuerdo, paga la tasa de arbitraje para escalar la pregunta a Kleros. Esto cuesta más que una fianza, por lo que es el último recurso para las preguntas con mucho en juego.
  5. El Kleros Arbitrator Proxy crea una disputa en KlerosCore. Cuando Kleros falla, se notifica a Reality.eth y la respuesta se finaliza.

Parámetro de tiempo clave: feeTimeout

El contrato de integración de RealityV2 con Kleros tiene un parámetro feeTimeout (fijado en 600 segundos / 10 minutos en el despliegue de referencia). Es el plazo en el que la otra parte también debe pagar la tasa de arbitraje una vez solicitada. Si no la paga dentro de feeTimeout, quien la solicitó gana por defecto.
Informa a tus usuarios sobre este plazo: si solicitan el arbitraje, la otra parte solo tiene 10 minutos para igualar la tasa.
El campo disputeTemplateMappings del script de despliegue de Reality V2 está marcado actualmente como TODO en la implementación de referencia. Esto significa que la plantilla de disputa que ven los jurados de Kleros en las preguntas de Reality todavía no tiene asignaciones de datos dinámicas (muestra texto estático). Consulta el repositorio kleros/reality-v2 para conocer el estado más reciente antes de depender del relleno dinámico de las plantillas.

Opciones de integración

Hay dos formas de integrarse con el oráculo Reality.eth + Kleros.

Fuera de la cadena (pruebas rápidas)

Usa la interfaz web de Reality.eth para enviar preguntas y obtener respuestas manualmente. Es la mejor opción para:
  • Probar el sistema antes de una integración completa
  • Aprender cómo funciona el ciclo de vida de las preguntas
  • Preguntas puntuales que no necesitan automatización

En la cadena (producción)

Haz que tu contrato inteligente llame directamente a Reality.eth para formular preguntas, leer respuestas y reaccionar a las respuestas del oráculo de forma programática. Es el enfoque recomendado para las dApps en producción. Para la vía en la cadena, conviene que conozcas la interfaz de Reality.eth y el reality-eth-monorepo, donde están las direcciones de los contratos y las ABI.

Integración mediante contratos inteligentes

Paso 1: formula una pregunta

Cualquier ETH enviado con askQuestion se convierte en la recompensa de la pregunta, lo que incentiva a quienes responden.

Parámetros de la pregunta

  • templateID: 0 para bool, 1 para uint, 2 para single-select, 3 para multiple-select, 4 para datetime, 5 para hash.
  • question: parámetros separados por el delimitador ␟ (U+241F), con el formato que corresponda a la plantilla. Ejemplos:
    • Bool: "Did event X happen?␟category␟en"
    • Uint: "What was the price of ETH on April 16, 2025?␟crypto␟en"
    • Single-select: "Which team won?␟\"Lakers\",\"Celtics\",\"Bucks\"␟sports␟en"
  • arbitrator: dirección del Kleros Arbitrator Proxy. Consulta Contratos inteligentes para ver los proxies disponibles.
  • timeout: segundos antes de que se finalice una respuesta no impugnada. Normalmente 86400 (24 horas). El contrato impone un máximo de 365 días.
  • openingTimestamp: momento más temprano en el que se pueden enviar respuestas. Usa 0 para que sea inmediato.
  • nonce: diferenciador para preguntas idénticas con los mismos parámetros. Usa 0 si no necesitas formular la misma pregunta más de una vez.

Paso 2: lee la respuesta finalizada

resultFor() se revierte si la pregunta todavía no está finalizada. Comprueba siempre primero isFinalized() o usa un patrón de callback. Para la decodificación completa de los resultados por tipo de plantilla y cómo gestionar valores especiales como INVALID y ANSWERED_TOO_EARLY, consulta Contratos inteligentes → Interpretación de los resultados.

Paso 3: gestiona el callback (opcional)

Para la ejecución automatizada, usa el mecanismo de callback de Reality.eth:

Elegir un proxy de árbitro

Cada Kleros Arbitrator Proxy se configura con: Usa un proxy existente de la página Contratos inteligentes o escribe a [email protected] para desplegar uno configurado para tu caso de uso. Para las aplicaciones que abarcan varias cadenas (por ejemplo, la pregunta en Polygon y el arbitraje en Ethereum), usa un proxy entre cadenas. Para consultar la tasa de arbitraje actual:

Presentación de evidencias

Cuando una pregunta de Reality.eth pasa al arbitraje, las evidencias ayudan a los jurados a tomar decisiones informadas. Envía las evidencias a través del Kleros Arbitrator Proxy, no de Reality.eth.

Cronología de las evidencias

  1. Se publica la pregunta en Reality.eth
  2. Fase de respuestas: los usuarios envían respuestas con fianzas
  3. Se solicita el arbitraje: alguien paga la tasa de arbitraje
  4. Se abre el periodo de evidencias (normalmente de 3 a 7 días, según la configuración del tribunal)
  5. Fase de votación: los jurados de Kleros revisan las evidencias y votan
  6. El fallo final se comunica a Reality.eth

Enviar evidencias desde un contrato

Enviar evidencias directamente

También puedes llamar directamente al proxy:

Formato de las evidencias

El JSON de las evidencias sigue el estándar ERC-1497. Aloja el JSON en IPFS (preferible) o en cualquier URL de acceso público.

Buenas prácticas para las evidencias

  • IPFS primero: /ipfs/QmHash o ipfs://QmHash es preferible por su permanencia. Las URL web funcionan, pero dependen de la disponibilidad del servidor.
  • Ambas partes deben enviar evidencias: quienes apoyan cada respuesta deben enviar sus propias evidencias. Los jurados valoran ambas.
  • Calidad antes que cantidad: las fuentes claras y autorizadas valen más que muchas fuentes débiles.
  • Envíalas pronto: cualquiera puede enviar evidencias durante el periodo de evidencias, pero los envíos tardíos corren el riesgo de pasar desapercibidos.
  • Haz referencia a la afirmación subyacente: cada archivo de evidencias debe corresponder claramente a la respuesta que respalda.

Supervisar el envío de evidencias

Vigila estos eventos en el contrato proxy:

Tasas y pagos

El sistema Reality.eth + Kleros tiene cinco tipos de tasas. Cada uno desempeña una función concreta en la estructura de incentivos. *Cuando se resuelve por arbitraje, el árbitro especifica quién recibe la recompensa.

Recompensa de la pregunta

  • Se establece enviando ETH (o tokens mediante askQuestionERC20) al llamar a askQuestion()
  • Se paga a quien da la respuesta final aceptada, menos cualquier tasa del árbitro
  • Las recompensas más altas suelen dar lugar a respuestas más rápidas y precisas

Fianza de la respuesta

  • Respalda la afirmación de quien responde de que su respuesta es correcta
  • Debe ser al menos el doble de la fianza anterior si ya había una respuesta
  • Se devuelve si la respuesta es correcta
  • Se paga a la siguiente respuesta correcta si la respuesta original se revoca

Tasa de sustitución

  • Compensa a quien respondió antes cuando otra persona asume una respuesta correcta
  • Es igual a la fianza que aportó la persona que dio antes esa respuesta
  • Se deduce de las recompensas que, de otro modo, recibiría quien responde después

Tasa de arbitraje

  • Se paga al árbitro cuando una parte escala la pregunta
  • La fija el árbitro (consúltala mediante realityETH.getArbitrator(_qid).getDisputeFee(_qid))
  • Normalmente la paga alguien cuya respuesta fue sustituida

Tasa de reclamación

  • Activa a partir de Reality.eth v2.1
  • Se quema el 2,5% de las fianzas reclamadas (excluida la fianza final)

Documento principal personalizado para el arbitraje

La mayoría de las integraciones de dApps funcionan bien con la política estándar de resolución de preguntas. En algunos casos, puedes necesitar un documento principal personalizado y adaptado a tu aplicación.

Cuándo necesitas un documento personalizado

  • Tu dApp tiene reglas específicas sobre cómo deben juzgarse las disputas
  • Resolver las disputas requiere conocimientos o contexto especializados
  • Necesitas un tribunal de Kleros específico para las disputas de tu aplicación
  • La interpretación de las respuestas en tu ámbito difiere de las interpretaciones estándar

Cómo funciona el proceso

  1. Evaluación inicial: el equipo de Kleros revisa tu caso de uso para confirmar que es necesario un documento personalizado
  2. Redacción del documento: trabajas con Kleros para crear un documento que:
    • Explique a los jurados el contexto de tu aplicación
    • Oriente sobre cómo evaluar las evidencias
    • Defina la terminología especializada
    • Establezca criterios claros para determinar las respuestas correctas
  3. Despliegue: Kleros despliega un proxy de árbitro específico con tu documento principal integrado en el metaevidence del proxy
  4. Uso: cuando las disputas pasan al arbitraje, los jurados aplican tus pautas

Ejemplo real: los mercados de predicción de Seer

Seer necesitaba una política de resolución personalizada porque sus mercados de predicción tienen reglas específicas para gestionar resultados complejos, casos límite como los eventos aplazados y fuentes de información autorizadas explícitas. Si tu aplicación puede necesitar este nivel de personalización, escribe a [email protected].

Integración con la gobernanza de DAO

El oráculo Reality.eth + Kleros impulsa SafeSnap, que convierte las votaciones de Snapshot fuera de la cadena en ejecución en la cadena mediante un Gnosis Safe, con Kleros Court como respaldo de arbitraje. Consulta la página del producto SafeSnap para saber qué es y cómo funciona el flujo, y el ejemplo de gobernanza de DAO para la instalación y la configuración.

Despliegues de Reality.eth

Los contratos de Reality.eth están desplegados en varias cadenas. Usa la dirección de contrato correcta para tu cadena de destino: Datos completos de los despliegues: monorepo de Reality.eth.

Integraciones en producción

El oráculo Reality.eth + Kleros se usa en producción en:
  • Mercados de predicción: Seer, Polkamarkets/Foreland y Omen lo usan para verificar los resultados de eventos del mundo real
  • Gobernanza optimista: el módulo Zodiac SafeSnap lo usa para una ejecución segura de las propuestas de las DAO
  • Moderación de contenidos: Moderate / Susie bot lo usa para aplicar de forma descentralizada las políticas de contenido

Pruebas

Para el desarrollo local, despliega Reality.eth y un árbitro simulado en una testnet:
Para las pruebas de integración con Kleros Court V2, usa la testnet Arbitrum Sepolia, donde están desplegados los contratos de Kleros V2. Para las pruebas con Court V1, usa Sepolia con el proxy del General Court en 0x05b942faecfb3924970e3a28e0f230910cedff45.

Preguntas habituales

¿Mi dApp necesita llamar directamente al proxy de árbitro? No. Tu dApp solo necesita interactuar con Reality.eth para el flujo estándar de preguntas y respuestas. El proxy se invoca automáticamente cuando se solicita el arbitraje. Solo necesitas llamar directamente al proxy para enviar evidencias durante un arbitraje activo. ¿Qué ocurre si hay una disputa? Reality.eth y Kleros gestionan el flujo de la disputa mediante el proxy de árbitro. Tu dApp no necesita ninguna lógica especial: cuando se resuelve la disputa, resultFor() devuelve la respuesta arbitrada. ¿Cómo redacto una pregunta clara? Sé específico, incluye los criterios de resolución e indica una fuente de información fiable. Ejemplo: “Did the S&P 500 close above 5,000 on April 10, 2025, according to the official S&P website?” (“¿Cerró el S&P 500 por encima de 5.000 el 10 de abril de 2025, según el sitio web oficial de S&P?”). ¿Puedo gestionar todo el flujo dentro de mi dApp sin usar el frontend de Reality.eth? Sí. Puedes implementarlo todo desde tu dApp: formular preguntas, enviar respuestas, solicitar el arbitraje y presentar evidencias.

¿Necesitas ayuda?

Contacta con el equipo de Kleros en [email protected] para:
  • Despliegues de proxies de árbitro personalizados
  • Ayuda con la integración de Reality.eth
  • Asistencia con casos de uso complejos o documentos principales personalizados