Antes de desplegar
Usa esta lista de verificación antes de desplegar en mainnet. Cada punto ya le ha dado problemas a alguien.Seguridad del contrato inteligente
Control de acceso
-
rule()solo puede llamarlo el árbitro - La creación de disputas está restringida a las partes válidas
- El envío de evidencias está restringido adecuadamente
- Las funciones de administración están protegidas (si las hay)
Gestión del estado
- Las disputas no pueden recibir un fallo dos veces
- Se rechazan los valores de fallo no válidos
- El fallo
0(negarse a arbitrar) se gestiona explícitamente - Todas las transiciones de estado son válidas (sin saltarse estados)
Protección frente a la reentrada
- El estado se actualiza antes de las llamadas externas en
rule() - Usa el patrón checks-effects-interactions
- Considera
ReentrancyGuardpara la lógica compleja
Seguridad de los fondos
- Ningún fondo puede quedar bloqueado de forma permanente
- Las transferencias fallidas no inutilizan el contrato
- Considera el patrón pull en lugar de push para las retiradas
- Prueba con contratos como destinatarios (no solo con EOA)
Configuración del arbitraje
Selección del tribunal
ID de los tribunales de Kleros V2 (Arbitrum One):
Los parámetros de los tribunales (minStake, feeForJuror, plazos de las sesiones) los rige la gobernanza y pueden cambiar mediante propuestas de gobernanza. Consúltalos con el getter
courts(courtID) de KlerosCore en lugar de codificarlos de forma fija.
Datos adicionales
-
extraDatacodifica correctamente el ID del tribunal y el número de jurados - El número de jurados es impar (evita los empates)
- El número de jurados es adecuado al valor de la disputa
Gestión de las tasas
- Obtén siempre un
arbitrationCost()actualizado antes de crear la disputa - Gestiona los aumentos de la tasa entre la comprobación y la ejecución
- Reembolsa el exceso de la tasa a quien la envía
- Documenta quién paga las tasas de arbitraje
- Si pagas en ERC20: verifica que el token está en
acceptedFeeTokensen KlerosCore - Si pagas en ERC20: llama a
arbitrationCost(extraData, feeToken)(no a la sobrecarga en ETH) - Si pagas en ERC20: aprueba que KlerosCore gaste el importe de la tasa antes de
createDispute() - Ten en cuenta los costes de apelación: cada ronda de apelación duplica aproximadamente el número de jurados y el coste
- En las disputas entre cadenas: el Foreign Gateway replica
arbitrationCost()en local, pero la sincronización puede retrasarse tras los cambios de gobernanza; añade un margen o un mecanismo de reintento
Plantilla de disputa
Calidad del contenido
- La pregunta es clara y no tiene ambigüedades
- Todas las opciones de fallo son mutuamente excluyentes
- Las descripciones de los fallos explican sus consecuencias
- Ninguna opción puede interpretarse de varias formas
- El escenario de “negarse a arbitrar” está documentado
Aspectos técnicos
- El JSON de la plantilla es válido
- La plantilla está en un almacenamiento permanente (IPFS fijado / Arweave)
- La URI de la plantilla es accesible y se resuelve correctamente
-
policyURIapunta a un documento de política válido -
arbitratorAddresscoincide con el despliegue -
arbitratorChainIDcoincide con el despliegue
Ejemplo de validación de una plantilla
Documento de política
Cada disputa debe hacer referencia a un documento de política que los jurados usan para decidir. Es distinto de la plantilla: la plantilla define la interfaz; la política define las reglas.- El documento de política establece claramente los criterios de cada opción de fallo
- La política cubre los casos límite (cumplimiento parcial, evidencias ambiguas)
- La política indica qué ocurre con “Negarse a arbitrar” (fallo 0)
- La política está redactada para un público no técnico (los jurados son el público general)
- La política está alojada en IPFS fijado o en Arweave (no en una URL que pueda cambiar)
- Alguien que no conoce tu protocolo ha revisado la política en busca de ambigüedades
Plazos del ciclo de vida de la disputa
Las disputas de Kleros siguen una secuencia de fases fija. Comprende el impacto de los plazos en tu aplicación:- Tu aplicación tolera los plazos de resolución de disputas (normalmente de 1 a 4 semanas)
- Los fondos o el estado permanecen bloqueados durante la disputa sin causar problemas
- Tu interfaz informa a los usuarios de los plazos previstos
- Gestionas el caso en el que las apelaciones alargan considerablemente los plazos
Eventos e indexación
-
DisputeRequestse emite con los parámetros correctos -
Rulingse emite tras ejecutar el fallo - Los eventos
Evidenceusan elevidenceGroupIDcorrecto - Los eventos están indexados para consultas eficientes
- El subgraph indexa tu contrato (si usas uno)
Optimización del gas
Referencias
Optimizaciones aplicadas
- Usa
immutablepara la dirección del árbitro - Empaqueta las estructuras de forma eficiente
- Evita lecturas de almacenamiento redundantes
- Usa
calldataen lugar dememorycuando sea posible
Despliegue
Verificación del contrato
- Código fuente verificado en el explorador de bloques
- Argumentos del constructor documentados
- Todas las dependencias verificadas
- Licencia especificada en el código fuente
Verificación de las direcciones
Inicialización
- La dirección del árbitro es la correcta para la red
- Los datos adicionales codifican el tribunal correcto
- La URI de la plantilla se resuelve correctamente
- Los roles de administración se han asignado correctamente
- El contrato está financiado si es necesario
Preparación operativa
Supervisión
- Alertas sobre los eventos
DisputeRequest - Alertas sobre los eventos
Ruling - Supervisión de los cambios de la tasa de arbitraje
- Seguimiento de los tiempos de resolución de las disputas
- Panel de las disputas activas
- Supervisa los eventos
AppealDecisionde KlerosCore: las apelaciones cambian los plazos y el coste - Suscríbete a los cambios de los parámetros de los tribunales mediante los eventos
CourtModified: los cambios de tasas afectan a tus cálculos de coste - Sigue tus disputas en court.kleros.io: filtra por la dirección de tu contrato
- En las disputas entre cadenas: supervisa el estado de las afirmaciones e impugnaciones del puente Vea en veascan.io
- Configura alertas para el evento
Pausedde KlerosCore: un árbitro pausado bloquea las nuevas disputas y los fallos
Documentación
- Guía del usuario para crear disputas
- Instrucciones para presentar evidencias
- Explicación de los resultados de los fallos
- Preguntas frecuentes
- Contacto de soporte para los problemas
Respuesta a incidentes
- Plan para el escenario de árbitro pausado
- Plan para un fallo inesperado
- Contacto de emergencia en Kleros (si es necesario)
- Vía de actualización documentada (si es actualizable)
- Árbitro pausado: KlerosCore tiene un mecanismo de pausa de emergencia controlado por el rol Guardian. Si está pausado, no se pueden crear nuevas disputas ni entregar fallos. Tu contrato debe gestionar correctamente que
createDispute()se revierta e informar a los usuarios. - Fallo 0 (Negarse a arbitrar): este fallo significa que los jurados consideraron no válida la disputa. Tu contrato debe gestionar este caso explícitamente: no lo trates igual que si ganara alguna de las partes.
- Empate: en el DisputeKitClassic actual, un empate da por defecto el fallo 0 (negarse a arbitrar) salvo que una apelación lo cambie. Diseña tu gestor del fallo 0 para que ofrezca una alternativa razonable (por ejemplo, reembolsar a ambas partes).
- Cambio de la dirección del contrato: los contratos de V2 son proxies actualizables. Tras las auditorías de seguridad, las direcciones pueden mantenerse pero cambiar la implementación. Si almacenas la dirección del árbitro como
immutable, no podrás adaptarte: considera usar una dirección que pueda actualizar un governor. - Retraso del puente Vea (solo entre cadenas): en el camino infeliz, la entrega del fallo puede tardar ~7 días mediante el puente nativo de Arbitrum. Asegúrate de que tu estado bloqueado puede mantenerse al menos 2 semanas sin causar problemas a los usuarios.
Kleros V2 en mainnet
Kleros V2 (Neo) está activo en la red principal de Arbitrum One. El acceso al tribunal está abierto a todos: los usuarios pueden hacer staking de PNK y participar como jurados. Estos puntos siguen siendo relevantes para los integradores:- Actualizaciones de los contratos: los contratos de V2 usan patrones de proxy UUPS y pueden actualizarse mediante la gobernanza. Suscríbete al blog de Kleros y a Discord para recibir los anuncios.
- Estabilidad del subgraph: fija en producción una versión concreta del despliegue del subgraph. Consulta el README del subgraph de kleros-v2 para ver los ID de los últimos despliegues estables.
-
Estado del SDK:
@kleros/kleros-sdkestá en desarrollo activo. Para la máxima estabilidad, puedes interactuar directamente con los contratos mediante las ABI de@kleros/kleros-v2-contracts. - Primero en testnet: despliega y prueba siempre un ciclo de vida completo de una disputa en Arbitrum Sepolia antes de mainnet. Las disputas de testnet pueden tardar más en resolverse debido a la participación limitada de jurados.
Contacta con el equipo de Kleros por Discord o en
[email protected] antes de tu primer despliegue en producción. El equipo puede revisar tu plantilla de disputa y aconsejarte sobre la selección del tribunal.Aprobación final
Referencia rápida
Direcciones de los contratos en mainnet (Arbitrum One)
Enlaces útiles
- Interfaz de Kleros Court: supervisa las disputas
- Despliegues en GitHub: direcciones de los contratos
- Discord de Kleros: soporte para desarrolladores
Problemas habituales de última hora
Direcciones de la red equivocada
Direcciones de la red equivocada
Comprueba dos veces que no usas direcciones de testnet en mainnet o viceversa. KlerosCore tiene una dirección distinta en Arbitrum Sepolia y en Arbitrum One.
Plantilla no fijada
Plantilla no fijada
El contenido de IPFS desaparece si no está fijado. Usa Pinata, Infura o Arweave para garantizar su permanencia. Kleros ofrece un servicio de pinning en
cdn.kleros.link, pero también deberías fijarlo de forma independiente.Tasas codificadas de forma fija
Tasas codificadas de forma fija
Nunca codifiques de forma fija las tasas de arbitraje. Obtenlas siempre de forma dinámica. Las tasas cambian mediante la gobernanza y varían según el tribunal.
Falta la lógica de reembolso
Falta la lógica de reembolso
Si el usuario paga de más la tasa de arbitraje, reembolsa el exceso.
Codificación de extraData incorrecta
Codificación de extraData incorrecta
V2 usa
abi.encodePacked(uint96(courtID), uint256(jurorCount)): fíjate en el uint96 del ID del tribunal, no uint256 como en V1. Usar uint256 codificará un tribunal distinto del previsto.Número de jurados par o impar
Número de jurados par o impar
Usa siempre un número impar de jurados (3, 5, 7) para evitar los empates. En DisputeKitClassic, los empates dan por defecto el fallo 0 (negarse a arbitrar), lo que puede no ser lo que esperan tus usuarios.
Plantilla de disputa no registrada
Plantilla de disputa no registrada
Si usas
templateId, asegúrate de que se llamó a setDisputeTemplate() en el DisputeTemplateRegistry y de que almacenaste el templateId devuelto. Si el ID es incorrecto, la interfaz de Court no mostrará correctamente tu disputa y los jurados verán que falta contexto.