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

# Contratos inteligentes

> Referencia de los contratos inteligentes de Kleros Curate V2: estructuras de los elementos, ciclo de vida de las solicitudes, conexiones con el arbitraje y firmas de las funciones para integradores.

## Estructuras de datos principales

### Estructura Item

```solidity theme={null}
struct Item {
    Status status;                         // Current state
    uint256 sumDeposit;                    // Total locked deposits
    uint256 requestCount;                  // Number of requests
    mapping(uint256 => Request) requests;  // Request history
}
```

### Estructura Request

```solidity theme={null}
struct Request {
    RequestType requestType;         // Registration or Clearing
    uint64 submissionTime;           // When submitted
    uint24 arbitrationParamsIndex;   // Preserves original arbitrator settings
    address payable requester;       // Who submitted
    address payable challenger;      // Who challenged (if any)
}
```

### Parámetros de arbitraje

```solidity theme={null}
struct ArbitrationParams {
    IArbitratorV2 arbitrator;        // Kleros Court contract
    bytes arbitratorExtraData;       // Court ID + juror count
    EvidenceModule evidenceModule;   // Evidence storage contract
}
```

### Enumeraciones

```solidity theme={null}
enum Status {
    Absent,                // Item does not exist
    Registered,            // Item is active in registry
    RegistrationRequested, // Pending addition
    ClearingRequested      // Pending removal
}

enum RequestType {
    Registration,  // Adding item
    Clearing       // Removing item
}
```

***

## Inicialización

### Función Initialize

```solidity theme={null}
function initialize(
    address _governor,                       // Admin address
    IArbitratorV2 _arbitrator,              // Kleros Core
    bytes calldata _arbitratorExtraData,    // Court config
    EvidenceModule _evidenceModule,          // Evidence storage
    address _connectedList,                  // Optional parent list
    TemplateRegistryParams calldata _templateRegistryParams,
    uint256[4] calldata _baseDeposits,       // Deposit amounts
    uint256 _challengePeriodDuration,        // Challenge window
    address _relayerContract,                // Direct operations
    string calldata _listMetadata            // JSON string
) external
```

### Array de depósitos base

| Índice | Propósito |
| - | - |
| 0 | Depósito base de envío |
| 1 | Depósito base de retirada |
| 2 | Depósito de impugnación de un envío |
| 3 | Depósito de impugnación de una retirada |

### Ejemplo de inicialización

```javascript theme={null}
// Court ID must be uint96, juror count uint256 - matches IArbitratorV2 spec
const extraData = ethers.solidityPacked(
  ["uint96", "uint256"],
  [1, 3] // Court ID 1 (General Court), 3 jurors
);

await curate.initialize(
  governorAddress,
  klerosCore.target,
  extraData,
  evidenceModule.target,
  ethers.ZeroAddress,           // No connected list
  {
    templateRegistry: templateRegistry.target,
    registrationTemplateParameters: [template, mappings],
    removalTemplateParameters: [template, mappings]
  },
  [
    ethers.parseEther("0.001"), // submission
    ethers.parseEther("0.001"), // removal
    ethers.parseEther("0.001"), // submission challenge
    ethers.parseEther("0.001")  // removal challenge
  ],
  3600,                         // 1 hour challenge period
  relayerAddress,
  JSON.stringify(metadata)
);
```

> [!NOTE]
>
> **Pautas para el periodo de impugnación:**
>
> * Testnet: 3600 segundos (1 hora)
> * Mainnet: 259200-604800 segundos (3-7 días)

***

## Formato de los datos de los elementos

Los elementos de Curate V2 se almacenan como una cadena JSON. El `listMetadata` del registro define el esquema mediante un array `columns`, y cada elemento se ajusta a esas columnas:

```json theme={null}
{
  "columns": [
    { "label": "Name",        "description": "Token name",            "type": "text",    "isIdentifier": true },
    { "label": "Address",     "description": "Contract address",      "type": "address", "isIdentifier": true },
    { "label": "Symbol",      "description": "Token ticker symbol",   "type": "text" },
    { "label": "Decimals",    "description": "Number of decimals",    "type": "number" },
    { "label": "Logo",        "description": "IPFS URI of token logo","type": "image" }
  ]
}
```

Un elemento enviado debe ser un objeto JSON con una clave por cada etiqueta de columna:

```json theme={null}
{
  "Name": "Dai Stablecoin",
  "Address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
  "Symbol": "DAI",
  "Decimals": 18,
  "Logo": "/ipfs/QmDAI..."
}
```

El `itemID` es `keccak256(abi.encodePacked(itemJSON))`: el hash de la cadena JSON exacta enviada. El sistema de asignaciones de datos usa esta estructura de columnas para extraer las variables de plantilla `{{itemName}}` y `{{itemDescription}}`.

***

## `arbitrationParamsIndex`: versionado

Cada `Request` almacena un `uint24 arbitrationParamsIndex` que captura los parámetros de arbitraje del registro en el momento del envío. Esto es fundamental: si el governor actualiza el árbitro o el extraData después de enviar una solicitud, los **parámetros originales se conservan** para el ciclo de vida de impugnación y disputa de esa solicitud.

Esto significa que:

* Quienes impugnan deben usar el **mismo arbitrationParamsIndex** que el envío original: obtenlo de la solicitud antes de impugnar
* Los cálculos de coste deben usar los parámetros de arbitraje de `request.arbitrationParamsIndex`, no los parámetros actuales

```solidity theme={null}
// Get the arbitration params for a specific request
(uint256 reqCount,) = curate.getItemInfo(itemId);
(,, uint24 paramsIndex,,) = curate.getRequestInfo(itemId, reqCount - 1);
(IArbitratorV2 arb, bytes memory extraData,) = curate.arbitrationParamsAt(paramsIndex);
uint256 cost = arb.arbitrationCost(extraData);
```

***

## Registro frente a retirada: plantillas de disputa separadas

Curate V2 usa **dos plantillas de disputa separadas**: una para las solicitudes de registro y otra para las solicitudes de retirada (clearing). Tienen una lógica de respuesta distinta:

| Plantilla | Pregunta | Respuesta 0x01 | Respuesta 0x02 |
| - | - | - | - |
| Registro | "¿Cumple el elemento los criterios?" | Sí, añadir el elemento | No, rechazar el elemento |
| Retirada | "¿Debe retirarse el elemento?" | Sí, retirar el elemento | No, conservar el elemento |

Ambas se establecen en la inicialización mediante `TemplateRegistryParams.registrationTemplateParameters` y `removalTemplateParameters`. Debes aportar ambas, y deben ser coherentes con tu documento de política.

***

## Envío de elementos

### Añadir un elemento

```solidity theme={null}
function addItem(string calldata _item) external payable returns (bytes32 itemID)
```

**Parámetros:**

* `_item`: cadena JSON que se ajusta al esquema de columnas del registro (consulta Formato de los datos de los elementos más arriba)

**Devuelve:**

* `itemID`: hash keccak256 de la cadena del elemento

### Calcular el coste de envío

```javascript theme={null}
// Get required deposit
const deposit = await curate.submissionBaseDeposit();

// Get arbitration cost
const arbitrator = await curate.getArbitrator();
const extraData = await curate.getArbitratorExtraData();
const arbCost = await arbitrator.arbitrationCost(extraData);

// Total required
const totalCost = deposit + arbCost;
```

### Ejemplo de envío

```javascript theme={null}
const itemData = {
  address: "0x1234...",
  name: "Token Name",
  symbol: "TKN"
};
const itemString = JSON.stringify(itemData);

// Calculate item ID
const itemID = ethers.keccak256(ethers.toUtf8Bytes(itemString));

// Submit item
const tx = await curate.addItem(itemString, { value: totalCost });
await tx.wait();

console.log("Item ID:", itemID);
```

***

## Retirada de elementos

### Retirar un elemento

```solidity theme={null}
function removeItem(bytes32 _itemID, string calldata _evidence) external payable
```

**Parámetros:**

* `_itemID`: hash del elemento que se va a retirar
* `_evidence`: cadena JSON de evidencias que respalda la retirada

### Ejemplo de retirada

```javascript theme={null}
const evidence = JSON.stringify({
  name: "Removal Request",
  description: "This item violates the policy because...",
});

const deposit = await curate.removalBaseDeposit();
const arbCost = await arbitrator.arbitrationCost(extraData);
const totalCost = deposit + arbCost;

const tx = await curate.removeItem(itemID, evidence, { value: totalCost });
await tx.wait();
```

***

## Impugnar solicitudes

### Impugnar una solicitud

```solidity theme={null}
function challengeRequest(bytes32 _itemID, string calldata _evidence) external payable
```

**Parámetros:**

* `_itemID`: elemento con una solicitud pendiente
* `_evidence`: evidencias JSON que respaldan la impugnación

### Ejemplo de impugnación

```javascript theme={null}
// Determine challenge deposit based on request type
const [status] = await curate.getItemInfo(itemID);
const challengeDeposit = status === 2 // RegistrationRequested
  ? await curate.submissionChallengeBaseDeposit()
  : await curate.removalChallengeBaseDeposit();

const arbCost = await arbitrator.arbitrationCost(extraData);
const totalCost = challengeDeposit + arbCost;

// Prepare evidence
const evidence = JSON.stringify({
  name: "Invalid Submission",
  description: "This item violates the list policy because...",
  supportingInfo: "Reference: [link or details]"
});

// Submit challenge
const tx = await curate.challengeRequest(itemID, evidence, {
  value: totalCost
});
await tx.wait();
```

> [!WARNING]
>
> Las impugnaciones deben enviarse durante el periodo de impugnación. Comprueba los plazos antes de impugnar.

***

## Ejecutar solicitudes

### Ejecutar una solicitud

```solidity theme={null}
function executeRequest(bytes32 _itemID) external
```

Ejecuta una solicitud no impugnada una vez transcurrido el periodo de impugnación.

### Ejemplo de ejecución

```javascript theme={null}
// Check if challenge period has passed
const [status, requestCount] = await curate.getItemInfo(itemID);
const lastRequestIndex = requestCount - 1;

const requestInfo = await curate.getRequestInfo(itemID, lastRequestIndex);
const challengePeriod = await curate.challengePeriodDuration();
const now = Math.floor(Date.now() / 1000);

if (now > requestInfo.submissionTime + challengePeriod) {
  const tx = await curate.executeRequest(itemID);
  await tx.wait();
  console.log("Request executed - deposit refunded");
}
```

***

## Funciones de consulta

### Obtener la información de un elemento

```solidity theme={null}
function getItemInfo(bytes32 _itemID) external view returns (
    Status status,
    uint256 requestCount
)
```

### Obtener la información de una solicitud

```solidity theme={null}
function getRequestInfo(bytes32 _itemID, uint256 _requestID) external view returns (
    RequestType requestType,
    uint64 submissionTime,
    bool disputed,
    bool resolved,
    address requester,
    address challenger
)
```

### Funciones del contrato View

El contrato CurateView ofrece consultas por lotes mejoradas:

```solidity theme={null}
// Get complete registry configuration
function fetchArbitrable(address _curate) external view returns (
    address governor,
    address relayerContract,
    uint256 submissionBaseDeposit,
    uint256 removalBaseDeposit,
    uint256 submissionChallengeBaseDeposit,
    uint256 removalChallengeBaseDeposit,
    uint256 challengePeriodDuration,
    uint256 arbitrationCost
)

// Get item with latest request
function getItem(address _curate, bytes32 _itemID) external view returns (
    Status status,
    bool disputed,
    uint256 sumDeposit,
    address requester
)

// Get all requests for an item
function getItemRequests(address _curate, bytes32 _itemID) external view returns (
    Request[] memory
)
```

### Ejemplo del contrato View

```javascript theme={null}
const view = await ethers.getContractAt("CurateView", VIEW_ADDRESS);

// Get complete registry configuration
const config = await view.fetchArbitrable(curateAddress);
console.log("Challenge period:", config.challengePeriodDuration.toString());
console.log("Submission deposit:", ethers.formatEther(config.submissionBaseDeposit));

// Get item details
const item = await view.getItem(curateAddress, itemID);
console.log("Status:", ["Absent", "Registered", "RegRequested", "ClearRequested"][item.status]);
console.log("Disputed:", item.disputed);

// Get all requests
const requests = await view.getItemRequests(curateAddress, itemID);
requests.forEach((req, i) => {
  console.log(`Request ${i}:`, {
    disputed: req.disputed,
    resolved: req.resolved,
    requester: req.requester
  });
});
```

***

## Funciones del governor

### Actualizaciones de la configuración

```solidity theme={null}
// Change arbitrator settings
function changeArbitrator(
    IArbitratorV2 _arbitrator,
    bytes calldata _arbitratorExtraData
) external onlyGovernor

// Update base deposits
function changeBaseDeposits(uint256[4] calldata _baseDeposits) external onlyGovernor

// Modify challenge period
function changeChallengePeriodDuration(uint256 _challengePeriodDuration) external onlyGovernor

// Set connected list (for hierarchical registries)
function changeConnectedList(address _connectedList) external onlyGovernor

// Update list metadata
function changeListMetadata(string calldata _listMetadata) external onlyGovernor

// Change relayer contract
function changeRelayerContract(address _relayerContract) external onlyGovernor
```

### Gestión directa de los elementos

```solidity theme={null}
// Add item bypassing challenge period (governor/relayer only)
function addItemDirectly(string calldata _item) external onlyGovernorOrRelayer

// Remove item bypassing challenge period (governor/relayer only)  
function removeItemDirectly(bytes32 _itemID) external onlyGovernorOrRelayer
```

***

## Eventos

### Eventos del ciclo de vida de los elementos

```solidity theme={null}
// New item submitted
event NewItem(
    bytes32 indexed itemID,
    string data,
    bool addedDirectly
);

// Item status changed
event ItemStatusChange(
    bytes32 indexed itemID,
    bool updatedDirectly
);

// Request submitted
event RequestSubmitted(
    bytes32 indexed itemID,
    uint256 requestID
);
```

### Eventos de las disputas

```solidity theme={null}
// Dispute created in Kleros Court
event DisputeRequest(
    IArbitratorV2 indexed arbitrator,
    uint256 indexed disputeID,
    uint256 externalDisputeID,
    uint256 templateId,
    string templateUri
);

// Ruling received from arbitrator
event Ruling(
    IArbitratorV2 indexed arbitrator,
    uint256 indexed disputeID,
    uint256 ruling
);
```

### Eventos de configuración

```solidity theme={null}
// Connected list updated
event ConnectedListSet(address indexed connectedList);

// Metadata updated
event ListMetadataSet(string listMetadata);
```

***

## Control de acceso

### Modificador del governor

```solidity theme={null}
modifier onlyGovernor() {
    require(msg.sender == governor, "Must be governor");
    _;
}
```

### Modificador del relayer

```solidity theme={null}
modifier onlyRelayer() {
    require(msg.sender == relayerContract, "Must be relayer");
    _;
}
```

### Acceso combinado

```solidity theme={null}
modifier onlyGovernorOrRelayer() {
    require(
        msg.sender == governor || msg.sender == relayerContract,
        "Must be governor or relayer"
    );
    _;
}
```

***

## Consideraciones de seguridad

> [accordion] Protección frente a la reentrada
>
> * Usa `.send()` con un límite de 2300 de gas para los reembolsos
> * Las actualizaciones de estado se producen antes de las llamadas externas
> * No se usa `.call()` directamente para las transferencias de ETH

> [accordion] Desbordamiento de enteros
>
> * Solidity 0.8.24 tiene protección integrada frente al desbordamiento
> * `uint24 arbitrationParamsIndex` permite 16.777.215 cambios

> [accordion] Manipulación de las marcas de tiempo
>
> * Los periodos de impugnación usan `block.timestamp`
> * Los mineros pueden manipularlo en ±15 segundos
> * Usa periodos suficientemente largos (horas o días como mínimo)

### Buenas prácticas

```javascript theme={null}
// Always validate item doesn't exist before submission
const [status] = await curate.getItemInfo(itemID);
if (status !== 0) {
  throw new Error("Item already exists");
}

// Check challenge period before challenging
const [, requestCount] = await curate.getItemInfo(itemID);
const request = await curate.getRequestInfo(itemID, requestCount - 1);
const challengePeriod = await curate.challengePeriodDuration();
const now = Math.floor(Date.now() / 1000);

if (now > request.submissionTime + challengePeriod) {
  throw new Error("Challenge period expired");
}

// Handle transaction errors
try {
  const tx = await curate.addItem(itemData, { value: totalCost });
  await tx.wait();
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    console.error("Not enough ETH");
  } else if (error.message.includes("Item must be absent")) {
    console.error("Item already exists");
  }
  throw error;
}
```


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