Visión general no custodial

OrcaRail está pasando de un modelo custodial de barrido (una wallet HD en el servidor por enlace de pago, con fondos que se barren y se reparten tras observarlos) a un modelo de contratos no custodial (los fondos llegan a un smart contract por enlace que los reparte de forma atómica, y las suscripciones extraen de un allowance que controla el pagador). Esta sección es la referencia principal de la transición.

El anuncio narrativo está en /blog/non-custodial-roadmap. Esta página es el punto de entrada estable; las entradas de cada fase y las páginas de la documentación enlazan aquí.

A quién afecta

• Comercios: tu superficie de API no cambia. Las URL de los enlaces de pago, los webhooks y los objetos de suscripción mantienen su forma. Lo que cambia por debajo es dónde están los fondos en tránsito.
• Pagadores: los pagos únicos son idénticos. Las suscripciones mantienen su approve on-chain único (EVM) o el delegado SPL (Solana), pero el autorizado pasa a ser un smart contract auditable en lugar de una hot wallet de OrcaRail.
• Integradores: solo campos añadidos (direcciones de contratos, metadatos del allowance). No se elimina nada existente sin un periodo de obsolescencia.

Planteamiento del problema

En el sistema actual, cada enlace de pago recibe una EOA derivada de HD o una smart account de Alchemy. Los depósitos llegan ahí y después un keeper en api/src/withdrawals/ los barre y hace el reparto entre comercio, plataforma y referidos. El keeper guarda el material de claves (un mnemónico cifrado en hd_wallet_seed) y los fondos en tránsito.

Esa ventana de custodia es el problema. Eliminarla supone una mejora de seguridad, una simplificación de cumplimiento normativo y una mejora operativa (se acabó el gas de los barridos y la clave de cifrado del mnemónico que proteger).

Estado objetivo

• EVM: PaymentLinkFactory calcula una dirección CREATE2 por enlace; los clones de PaymentLinkReceiver aceptan los fondos y los reparten de forma atómica mediante FeeSplitter. Las suscripciones funcionan sobre SubscriptionHub con approve de ERC-20.
• Solana: el programa Anchor payment_link posee una PDA por enlace; el programa subscription extrae mediante la autoridad de delegado SPL.
• Bitcoin: multisig taproot 2 de 2 por enlace con un firmante del comercio y PSBT de reembolso prefirmadas. Los cobros recurrentes en BTC quedan fuera de alcance hasta que Lightning BOLT12 madure.
• Keeper: puntos de entrada charge() públicos; NestJS como principal, Chainlink Automation o Gelato como respaldo; un AVS de EigenLayer opcional si alguna vez hace falta.

Consulta Arquitectura para ver el diagrama completo.

Ruta de lectura

• Empieza por Arquitectura para la visión de sistema.
• Lee Modelo de seguridad para los supuestos de confianza y la custodia de claves.
• Consulta Referencia de contratos para las funciones y los ABI.
• Lee la Guía de migración si tienes enlaces o suscripciones existentes.
• Usa Estrategia de keepers para entender cómo se disparan los cobros y cuáles son los SLO.
• Revisa Consideraciones sobre Bitcoin para el alcance real en BTC.
• Lee la Evaluación de EigenLayer para nuestra postura sobre keepers descentralizados.
• Sigue la Hoja de ruta para el estado fase a fase.

Estado de las fases (resumen)

La lista completa de fases con su estado está en la Hoja de ruta. Índice rápido:

• Fase 0: diseño y estrategia de auditoría
• Fase 1: contratos de enlaces de pago en EVM
• Fase 2: suscripciones en EVM (extracción por allowance)
• Fase 3: despliegue multi-EVM y redundancia de keepers
• Fase 4: Solana (programas Anchor)
• Fase 5: Bitcoin (custodia reducida)
• Fase 6: keepers descentralizados (EigenLayer)
• Fase 7: retirada de la infraestructura custodial

Documentación relacionada

• Suscripciones: cobro automático: flujo de approve/revoke del lado del pagador (compatible con el nuevo autorizado no custodial).
• Retiros: estrategia: cómo funcionan las rutas de liquidación por familia de cadenas.
• Referencia: multichain: redes compatibles y cobertura de tokens.