> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleros.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Guía de integración

> Integra el oráculo Reality.eth y Kleros en tu contrato inteligente, con escalada de fianzas, proxies de árbitro y datos fiables del mundo real en la cadena.

## 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.

```solidity theme={null} theme={null}
uint32 public constant FEE_TIMEOUT = 600; // 10 minutes
```

Informa a tus usuarios sobre este plazo: si solicitan el arbitraje, la otra parte solo tiene 10 minutos para igualar la tasa.

> [!WARNING]
>
> 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](https://github.com/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](https://reality.eth.limo/) 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](https://reality.eth.limo/app/docs/html/) y el [reality-eth-monorepo](https://github.com/RealityETH/reality-eth-monorepo), donde están las direcciones de los contratos y las ABI.

***

## Integración mediante contratos inteligentes

### Paso 1: formula una pregunta

```solidity theme={null} theme={null}
import {IRealityETH} from "./interfaces/IRealityETH.sol";

contract OracleConsumer {
    IRealityETH public immutable realityETH;
    // Kleros Arbitrator Proxy General Court on Mainnet
    address public constant ARBITRATOR = 0x728cba71a3723caab33ea416cb46e2cc9215a596;
    uint32 public constant TIMEOUT = 86400; // 24 hours

    constructor(address _realityETH) {
        realityETH = IRealityETH(_realityETH);
    }

    function askQuestion(string calldata _question) external payable returns (bytes32) {
        return realityETH.askQuestion{value: msg.value}(
            0,              // template: bool (yes/no)
            _question,      // e.g. "Did team X win?␟sports␟en"
            ARBITRATOR,     // Kleros arbitrator proxy
            TIMEOUT,        // answer timeout
            0,              // opens immediately
            0               // nonce
        );
    }
}
```

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](https://docs.kleros.io/es/developers/products/reality/smart-contracts.md#kleros-arbitrator-proxy-addresses) 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

```solidity theme={null} theme={null}
function getAnswer(bytes32 _questionID) external view returns (bytes32) {
    require(realityETH.isFinalized(_questionID), "Not finalized");
    return realityETH.resultFor(_questionID);
}

function getAnswerAsBool(bytes32 _questionID) external view returns (bool) {
    bytes32 answer = realityETH.resultFor(_questionID);
    // 0x01 = Yes, 0x00 = No
    return answer == bytes32(uint256(1));
}
```

> [!WARNING]
>
> `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](https://docs.kleros.io/es/developers/products/reality/smart-contracts.md#result-interpretation).

### Paso 3: gestiona el callback (opcional)

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

```solidity theme={null} theme={null}
function resultReady(bytes32 _questionID) external {
    require(msg.sender == address(realityETH), "Only Reality.eth");
    bytes32 answer = realityETH.resultFor(_questionID);
    // Execute logic based on the answer
}
```

***

## Elegir un proxy de árbitro

Cada Kleros Arbitrator Proxy se configura con:

| Parámetro | Descripción |
| - | - |
| **Subtribunal** | Qué tribunal de Kleros resuelve las disputas |
| **Número de jurados** | Número inicial de jurados de la primera ronda |
| **Tasa de arbitraje** | Coste de escalar una pregunta a Kleros |

Usa un proxy existente de la página [Contratos inteligentes](https://docs.kleros.io/es/developers/products/reality/smart-contracts.md) o escribe a `integrations@kleros.io` 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](https://github.com/kleros/cross-chain-realitio-proxy/tree/master/contracts#deployments).

Para consultar la tasa de arbitraje actual:

```solidity theme={null} theme={null}
uint256 fee = realityETH.getArbitrator(_questionID).getDisputeFee(_questionID);
```

***

## 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

```solidity theme={null} theme={null}
interface IKlerosArbitratorProxy {
    function submitEvidence(
        uint256 _questionID,
        string calldata _evidenceURI
    ) external;
}

contract MyDApp {
    IKlerosArbitratorProxy public arbitratorProxy;

    constructor(address _arbitratorProxyAddress) {
        arbitratorProxy = IKlerosArbitratorProxy(_arbitratorProxyAddress);
    }

    function submitEvidenceForQuestion(
        bytes32 _questionID,
        string calldata _evidenceURI
    ) external {
        arbitratorProxy.submitEvidence(uint256(_questionID), _evidenceURI);
    }
}
```

### Enviar evidencias directamente

También puedes llamar directamente al proxy:

```solidity theme={null} theme={null}
arbitratorProxy.submitEvidence(
    uint256(questionID),
    "/ipfs/QmYourEvidenceHash"
);
```

### Formato de las evidencias

El JSON de las evidencias sigue el estándar [ERC-1497](https://github.com/ethereum/EIPs/issues/1497). Aloja el JSON en IPFS (preferible) o en cualquier URL de acceso público.

```json theme={null} theme={null}
{
  "name": "Evidence Supporting Yes",
  "description": "Official S&P website showing closing price of 5,127.43 on April 16, 2025",
  "fileURI": "/ipfs/QmScreenshotHash",
  "fileHash": "QmScreenshotHash",
  "fileTypeExtension": "png"
}
```

### 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:

```solidity theme={null} theme={null}
// Emitted when arbitration is created
event Dispute(
    IArbitrator indexed _arbitrator,
    uint256 indexed _disputeID,
    uint256 _metaEvidenceID,
    uint256 _evidenceGroupID
);

// Emitted on each evidence submission
event Evidence(
    IArbitrator indexed _arbitrator,
    uint256 indexed _evidenceGroupID,
    address indexed _party,
    string _evidence
);
```

***

## 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.

| Tasa | La fija | La paga | Se paga a |
| - | - | - | - |
| Recompensa de la pregunta | Quien pregunta | Quien pregunta | Quien dio la respuesta correcta con la fianza más alta\* |
| Fianza de la respuesta | Quien responde | Quien responde | Se devuelve si es correcta; si no, a la siguiente respuesta correcta |
| Tasa de sustitución | La fianza anterior | La respuesta siguiente | Quien respondió antes (se deduce de las recompensas) |
| Tasa de arbitraje | El árbitro | Cualquiera que lo solicite | El árbitro |
| Tasa de reclamación (2,5%) | El sistema | Quien reclama | Se quema (se deduce del importe reclamado, Reality.eth v2.1+) |

\*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](https://cdn.kleros.link/ipfs/QmaUr6hnSVxYD899xdcn2GUVtXVjXoSXKZbce3zFtGWw4H/Question_Resolution_Policy.pdf). 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](https://seer.pm) necesitaba una [política de resolución personalizada](https://cdn.kleros.link/ipfs/QmPmRkXFUmzP4rq2YfD3wNwL8bg3WDxkYuvTP9A9UZm9gJ/seer-markets-resolution-policy.pdf) 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 `integrations@kleros.io`.

***

## 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](https://docs.kleros.io/es/products/safesnap.md)** para saber qué es y cómo funciona el flujo, y el **[ejemplo de gobernanza de DAO](https://docs.kleros.io/es/developers/examples/dao-governance.md)** 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:

| Cadena | Ruta en el repositorio |
| - | - |
| Ethereum Mainnet | `chains/deployments/1/` |
| Gnosis Chain | `chains/deployments/100/` |
| Arbitrum One | `chains/deployments/42161/` |
| Polygon | `chains/deployments/137/` |

Datos completos de los despliegues: [monorepo de Reality.eth](https://github.com/RealityETH/reality-eth-monorepo/tree/main/packages/contracts/chains/deployments).

***

## Integraciones en producción

El oráculo Reality.eth + Kleros se usa en producción en:

* **Mercados de predicción**: [Seer](https://seer.pm), Polkamarkets/Foreland y [Omen](https://omen.eth.limo) 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](https://docs.kleros.io/es/legacy/retired/moderate.md) 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:

```bash theme={null} theme={null}
# Clone the Reality.eth monorepo
git clone https://github.com/RealityETH/reality-eth-monorepo.git
cd reality-eth-monorepo/packages/contracts

# Deploy to a local network or testnet
npx hardhat deploy --network <your-network>
```

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 `integrations@kleros.io` 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.