Sistema de Disputas

Visión General

El sistema de disputas permite la resolución descentralizada de conflictos entre usuarios y merchants, con Circle Admins actuando como árbitros de primera instancia.

Flujo de Disputa

┌─────────────────────────────────────────────────┐
│                 APERTURA                        │
│  Usuario abre disputa con evidencias            │
│  → La transacción queda bloqueada               │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                 RESPUESTA                       │
│  El merchant tiene 48h para responder           │
│  → Puede adjuntar contra-evidencias             │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                 ANÁLISIS                        │
│  El Circle Admin tiene 7 días para decidir      │
│  → Analiza evidencias de ambos lados            │
└─────────────────────┬───────────────────────────┘
                      │
              ┌───────┴───────┐
              │               │
              ▼               ▼
┌─────────────────┐   ┌─────────────────┐
│ FAVOR USUARIO   │   │ FAVOR MERCHANT  │
│ → Reembolso     │   │ → Libera fondos │
│ → Slash merch.  │   │ → Caso cerrado  │
└────────┬────────┘   └────────┬────────┘
         │                     │
         └──────────┬──────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│               CONTESTACIÓN (opcional)           │
│  La parte perdedora puede contestar en 48h      │
│  → El protocolo revisa la decisión              │
└─────────────────────────────────────────────────┘

Tipos de Disputa

1. No recepción

• Alegación: El usuario pagó pero no recibió cripto
• Evidencia esperada: Comprobante de pago
• Resolución típica: Reembolso del fondo de protección

2. Valor incorrecto

• Alegación: Recibió menos de lo que debía
• Evidencia esperada: Captura de la transacción + comprobante
• Resolución típica: Diferencia cubierta por el fondo

3. Demora excesiva

• Alegación: El merchant no completó a tiempo
• Evidencia esperada: Timeline de la transacción
• Resolución típica: Cancelación + posible slashing

4. Fraude

• Alegación: Comportamiento malicioso deliberado
• Evidencia esperada: Documentación completa
• Resolución típica: Ban + slashing total + reembolso

---

Plazos

Etapa	Plazo	Consecuencia si no cumple
Respuesta del merchant	48h	Decisión automática en contra
Decisión del admin	7 días	Slashing del admin
Contestación	48h	La decisión se vuelve final
Revisión del protocolo	14 días	Se mantiene la decisión anterior

---

Penalidades

Para Merchants

Resultado	Penalidad
Pierde 1ª disputa	Valor de la transacción (del stake)
Pierde 3+ disputas	Stake retenido para análisis
Fraude comprobado	Ban permanente + 100% stake

Para Admins del Circle

Resultado	Penalidad
Decisión revertida (1x)	Advertencia
Decisión revertida (2x+)	Slashing parcial
Ignora disputa	0.5% stake por ocurrencia
Colusión comprobada	Ban + 100% stake

---

Evidencias

Tipos aceptados

• Capturas de pantalla con metadata
• Comprobantes bancarios (PDF)
• Historial de chat (de la app)
• Transacciones on-chain (hash)
• Videos (casos especiales)

Validación

• Metadata verificada cuando sea posible
• Cruce con datos on-chain
• El historial de chat es oficial (grabado)

---

Implementación Técnica

Estados de la disputa

enum DisputeState {
    Open,           // Esperando respuesta
    UnderReview,    // Admin analizando
    Resolved,       // Decisión tomada
    Contested,      // En contestación
    Final           // Caso cerrado
}

Estructura de datos

struct Dispute {
    uint256 transactionId;
    address claimant;      // Quien abrió
    address respondent;    // Contra quien
    DisputeState state;
    uint256 openedAt;
    uint256 resolvedAt;
    bytes32 evidenceHash;  // IPFS hash
    address resolver;      // Admin que decidió
    bool claimantWon;
}

Eventos

event DisputeOpened(uint256 indexed disputeId, uint256 transactionId);
event DisputeResolved(uint256 indexed disputeId, bool claimantWon);
event DisputeContested(uint256 indexed disputeId);
event DisputeFinalized(uint256 indexed disputeId);

---

Métricas de Admin

El protocolo rastrea el rendimiento de los admins:

Métrica	Impacto
% disputas resueltas en menos de 48h	Ranking
% decisiones contestadas	Score negativo
% decisiones revertidas	Slashing potencial
Tiempo promedio de resolución	Ranking

Admins con buenas métricas:

• Aparecen mejor en el ranking
• Atraen más merchants
• Pueden recibir bonos del protocolo