> ## 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 Escrow V2: estructuras de las transacciones, ciclo de vida de las disputas, gestión de los decimales de los tokens y funciones de integración.

> [!NOTE]
>
> Los contratos de V2 gestionan ahora correctamente los tokens que no tienen 18 decimales (USDC = 6 decimales, USDT = 6 decimales). El documento de la política de disputa General Escrow se finalizó y se subió a IPFS (marzo de 2026).

## Estructuras de datos principales

### Estructura Transaction

```solidity theme={null}
struct Transaction {
    address payable buyer;          // Payment sender
    address payable seller;         // Payment recipient
    uint256 amount;                 // Remaining escrow amount
    uint256 settlementBuyer;        // Buyer's proposed settlement amount
    uint256 settlementSeller;       // Seller's proposed settlement amount
    uint256 deadline;               // Initial delivery deadline
    uint256 disputeID;              // Kleros dispute identifier
    uint256 buyerFee;               // Arbitration fees paid by buyer
    uint256 sellerFee;              // Arbitration fees paid by seller
    uint256 lastFeePaymentTime;     // Last interaction timestamp
    Status status;                  // Current transaction state
    IERC20 token;                   // Token contract (address(0) for ETH)
}
```

### Enumeración Status

```solidity theme={null}
enum Status {
    NoDispute,               // Initial state
    WaitingSettlementBuyer,  // Waiting for buyer settlement response
    WaitingSettlementSeller, // Waiting for seller settlement response
    WaitingBuyer,            // Waiting for buyer arbitration fee
    WaitingSeller,           // Waiting for seller arbitration fee
    DisputeCreated,          // Active Kleros dispute
    TransactionResolved      // Final state
}
```

### Enumeraciones Party y Resolution

```solidity theme={null}
enum Party {
    None,   // No winner (split decision)
    Buyer,  // Buyer wins dispute
    Seller  // Seller wins dispute
}

enum Resolution {
    TransactionExecuted,  // Normal completion
    TimeoutByBuyer,       // Seller didn't pay arbitration fees
    TimeoutBySeller,      // Buyer didn't pay arbitration fees
    RulingEnforced,       // Dispute resolved by jurors
    SettlementReached     // Settlement accepted by parties
}
```

***

## Crear transacciones

### Transacción en ETH nativo

```solidity theme={null}
function createNativeTransaction(
    uint256 _deadline,              // Unix timestamp for automatic execution
    string memory _transactionUri,  // Data URI for transaction metadata
    address payable _buyer,         // Payment sender address
    address payable _seller         // Payment recipient address
) external payable returns (uint256 transactionID)
```

### Transacción en tokens ERC20

```solidity theme={null}
function createERC20Transaction(
    uint256 _amount,                // Token amount (in token's base units)
    IERC20 _token,                  // ERC20 token contract address
    uint256 _deadline,              // Unix timestamp for automatic execution
    string memory _transactionUri,  // Data URI for transaction metadata
    address payable _buyer,         // Payment sender address
    address payable _seller         // Payment recipient address
) external returns (uint256 transactionID)
```

> [!WARNING]
>
> Ambas funciones aplican límites de importe por token mediante el modificador `shouldNotExceedCap`. Las transacciones que superan el límite se revierten con el error `AmountExceedsCap()`.

***

## Gestionar las transacciones

### Funciones de pago

```solidity theme={null}
// Buyer releases payment to seller
function pay(uint256 _transactionID, uint256 _amount) external

// Seller reimburses buyer
function reimburse(uint256 _transactionID, uint256 _amountReimbursed) external

// Execute transaction after deadline
function executeTransaction(uint256 _transactionID) external
```

> [!NOTE]
>
> **Comportamientos clave:**
>
> * `pay()` y `reimburse()` pueden llamarse varias veces con importes parciales
> * Cuando se paga o se reembolsa el importe completo, el estado cambia a `TransactionResolved`
> * `executeTransaction()` transfiere todos los fondos restantes al vendedor una vez vencido el plazo
> * Las tres funciones exigen que el estado sea `NoDispute`; de lo contrario, se revierten con `TransactionDisputed()`

***

## Sistema de acuerdos

### Funciones de acuerdo

```solidity theme={null}
// Propose settlement amount (seller receives this amount, buyer gets remainder)
function proposeSettlement(uint256 _transactionID, uint256 _amount) external

// Accept the other party's proposed settlement
function acceptSettlement(uint256 _transactionID) external
```

### Flujo del acuerdo

**1. Inicia la propuesta**

Cualquiera de las partes propone un importe de acuerdo con `proposeSettlement()`.

**2. Cambio de estado**

El estado cambia a `WaitingSettlementBuyer` o `WaitingSettlementSeller`.

**3. Respuesta**

La otra parte puede aceptar el acuerdo o proponer una contraoferta.

**4. Contraofertas**

Las contraofertas reinician `lastFeePaymentTime` y cambian el estado de espera.

**5. Opción de disputa**

La parte que no propuso el acuerdo puede abrir una disputa de inmediato pagando la tasa de arbitraje. La parte que lo propuso debe esperar a que transcurra `settlementTimeout` antes de poder abrir una disputa.

> [!NOTE]
>
> **Aceptación del acuerdo:** al aceptarse, los fondos se reparten de inmediato. El vendedor recibe el importe de acuerdo propuesto y el comprador, el resto. En los tokens ERC20, la biblioteca SafeERC20 garantiza que ambas transferencias se realicen de forma atómica.

***

## Gestión de las disputas

### Funciones de las tasas de arbitraje

```solidity theme={null}
// Pay arbitration fee as buyer
function payArbitrationFeeByBuyer(uint256 _transactionID) external payable

// Pay arbitration fee as seller
function payArbitrationFeeBySeller(uint256 _transactionID) external payable

// Claim win if seller doesn't pay fee
function timeOutByBuyer(uint256 _transactionID) external

// Claim win if buyer doesn't pay fee
function timeOutBySeller(uint256 _transactionID) external
```

### Proceso de creación de la disputa

```mermaid theme={null}
sequenceDiagram
    participant Buyer as Comprador
    participant Contract as Contrato
    participant Seller as Vendedor
    participant Kleros
    
    Buyer->>Contract: payArbitrationFeeByBuyer()
    Contract-->>Buyer: Estado: WaitingSeller
    Seller->>Contract: payArbitrationFeeBySeller()
    Contract->>Kleros: createDispute()
    Kleros-->>Contract: disputeID
    Contract-->>Seller: Estado: DisputeCreated
```

### Cálculo de las tasas

```solidity theme={null}
uint256 arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData);
```

> [!WARNING]
>
> **Reglas de tiempo límite:**
>
> * Quienes proponen un acuerdo deben esperar `settlementTimeout` antes de pagar las tasas
> * Si una de las partes no paga dentro de `feeTimeout`, la otra parte gana por defecto
> * La parte ganadora recibe todos los fondos depositados y el reembolso de su tasa

***

## Funciones de consulta

### Consultas de transacciones

```solidity theme={null}
// Get count of all transactions
function getTransactionCount() external view returns (uint256)

// Get detailed transaction information
function transactions(uint256 _index) external view returns (
    address payable buyer,
    address payable seller,
    uint256 amount,
    uint256 settlementBuyer,
    uint256 settlementSeller,
    uint256 deadline,
    uint256 disputeID,
    uint256 buyerFee,
    uint256 sellerFee,
    uint256 lastFeePaymentTime,
    Status status,
    IERC20 token
)
```

### Cálculo de los pagos

```solidity theme={null}
// Get payout distribution for different outcomes
function getPayouts(
    uint256 _transactionID,
    Party _winningParty
) public view returns (
    uint256 buyerPayout,
    uint256 buyerPayoutToken,
    uint256 sellerPayout,
    uint256 sellerPayoutToken
)
```

**Lógica de los pagos:**

| Ganador | El comprador recibe | El vendedor recibe |
| - | - | - |
| **Comprador** | Reembolso de la tasa + importe - acuerdo del vendedor (si lo hay) | La propuesta de acuerdo del vendedor |
| **Vendedor** | El resto tras el acuerdo del vendedor | Reembolso de la tasa + acuerdo (o importe completo) |
| **Ninguno** | Mitad de las tasas + mitad del importe | Mitad de las tasas + mitad del importe |

### Otras consultas

```solidity theme={null}
// Check per-token amount cap (0 means unlimited)
function amountCaps(IERC20 _token) external view returns (uint256)

// Get current arbitrator contract
function arbitrator() external view returns (IArbitratorV2)

// Get current governor address
function governor() external view returns (address)

// Get arbitration fee timeout
function feeTimeout() external view returns (uint256)

// Get settlement response timeout
function settlementTimeout() external view returns (uint256)

// Get dispute ID to transaction ID mapping
function disputeIDtoTransactionID(uint256 _disputeID) external view returns (uint256)
```

***

## Funciones del governor

> [!NOTE]
>
> Todas las funciones del governor están restringidas a la dirección del governor actual.

```solidity theme={null}
// Change contract governor
function changeGovernor(address _governor) external onlyByGovernor

// Update arbitrator contract address
function changeArbitrator(IArbitratorV2 _arbitrator) external onlyByGovernor

// Modify arbitrator extra data (court ID, juror count)
function changeArbitratorExtraData(bytes calldata _arbitratorExtraData) external onlyByGovernor

// Update arbitration fee payment timeout
function changeFeeTimeout(uint256 _feeTimeout) external onlyByGovernor

// Update settlement response timeout
function changeSettlementTimeout(uint256 _settlementTimeout) external onlyByGovernor

// Set per-token amount cap (0 for unlimited, address(0) for native ETH)
function changeAmountCap(IERC20 _token, uint256 _amountCap) external onlyByGovernor

// Update dispute template and data mappings
function changeDisputeTemplate(
    string memory _templateData,
    string memory _templateDataMappings
) external onlyByGovernor

// Update template registry contract
function changeTemplateRegistry(IDisputeTemplateRegistry _templateRegistry) external onlyByGovernor
```

***

## Eventos

### Eventos de transacciones

```solidity theme={null}
event NativeTransactionCreated(
    uint256 indexed _transactionID,
    string _transactionUri,
    address indexed _buyer,
    address indexed _seller,
    uint256 _amount,
    uint256 _deadline
)

event ERC20TransactionCreated(
    uint256 indexed _transactionID,
    string _transactionUri,
    address indexed _buyer,
    address indexed _seller,
    IERC20 _token,
    uint256 _amount,
    uint256 _deadline
)
```

### Eventos de gestión

```solidity theme={null}
// Payment event
event Payment(uint256 indexed _transactionID, uint256 _amount, address _party)

// Fee payment notification
event HasToPayFee(uint256 indexed _transactionID, Party _party)

// Settlement proposal
event SettlementProposed(uint256 indexed _transactionID, Party _party, uint256 _amount)

// Transaction resolution
event TransactionResolved(uint256 indexed _transactionID, Resolution indexed _resolution)

// Dispute creation
event DisputeRequest(
    IArbitratorV2 indexed _arbitrator, 
    uint256 _disputeID, 
    uint256 indexed _externalDisputeID, 
    uint256 _templateId, 
    string _template
)
```

***

## Formato de los metadatos de las transacciones

Las transacciones almacenan los metadatos en la cadena mediante data URI. La estructura JSON de los metadatos:

```json theme={null}
{
  "title": "Transaction Title",
  "description": "Detailed description of the deliverables and terms",
  "extraDescriptionUri": "ipfs://QmAttachmentDocumentHash"
}
```

Para las transacciones de cripto a cripto:

```json theme={null}
{
  "title": "Cross-chain Token Swap",
  "description": "ETH to SOL exchange",
  "otherChain": "Solana",
  "otherChainAddress": "SolanaWalletAddress", 
  "otherAsset": "SOL",
  "otherAmount": "5"
}
```

### Crear data URI

```javascript theme={null}
const metadata = {
  title: "Website Development Project",
  description: "Build responsive website with React",
  extraDescriptionUri: "ipfs://QmDocumentHash"
};

const dataUri = `data:application/json;base64,${btoa(JSON.stringify(metadata))}`;

// Use this dataUri when creating the transaction
await createNativeTransaction(deadline, dataUri, buyerAddress, sellerAddress);
```

> [!TIP]
>
> **Pautas para los metadatos:**
>
> * Los metadatos se almacenan directamente en la cadena mediante data URI, lo que elimina las dependencias de IPFS
> * Mantén concisos los metadatos principales, ya que la codificación base64 aumenta el tamaño de la transacción
> * Usa `extraDescriptionUri` para los adjuntos grandes o los documentos de evidencia


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