Saltar al contenido principal

Guía de migración

Esta guía explica qué hacer, y qué esperar, mientras OrcaRail despliega la pila no custodial. El despliegue es por fases y opcional por cadena; no se obliga a migrar a ningún enlace ni suscripción existente.

Para comercios​

Qué cambia en tu integración​

No hace falta nada. La forma de las respuestas de la API para enlaces de pago y suscripciones es aditiva durante la transición:

  • Los enlaces de pago reciben un nuevo campo receiver.contract_address (el mismo valor que la dirección de depósito existente en los enlaces con receptor on-chain).
  • Las suscripciones reciben auto_charge.approval_spender_address, que apunta al SubscriptionHub on-chain en lugar de a una hot wallet. Este campo ya existe en Cobro automático; solo cambia el valor.
  • Los webhooks se disparan en los mismos momentos (payment.succeeded, subscription.charge.*, etc.).

Qué cambia en el panel​

  • Aparece una insignia «No custodial» en los enlaces de pago y las suscripciones que usan la nueva pila.
  • Un banner en las suscripciones activas existentes te invita a ofrecer la migración a tu pagador en la próxima renovación.
  • Un interruptor por cadena en la configuración te permite activar los receptores no custodiales cadena a cadena cuando la cadena supera el canary (Base primero).

Cuándo actuar​

  • Fase 1 (Base): no hace falta nada. Los enlaces nuevos en Base usan automáticamente el nuevo receptor en cuanto se activa el flag de tu organización.
  • Fase 2: cuando aparezca el banner, reenvía el aviso de renovación a tus suscriptores para que vuelvan a firmar approve hacia el nuevo SubscriptionHub. La plantilla de email viene rellenada.
  • Fase 3 (otras cadenas EVM): el mismo patrón que en Base, cadena a cadena.
  • Fase 4 (Solana): el mismo patrón, activado en el siguiente ciclo de suscripción en SOL de tu comercio.
  • Fase 5 (Bitcoin): registra un firmante BTC (xpub) en el panel para que los nuevos enlaces BTC puedan usar el multisig 2 de 2. Consulta Consideraciones sobre Bitcoin.
  • Fase 7: si alguno de tus suscriptores sigue en la ruta custodial heredada, contacta con él con el aviso final de 30 días que te proporcionamos.

Rutas heredadas​

Los enlaces de pago heredados existentes se liquidan como antes hasta que caducan. Las suscripciones heredadas existentes siguen extrayendo desde la hot wallet custodial hasta que se migran o se cancelan. Sin migración forzosa.

Para pagadores​

Pagos únicos​

No cambia nada. Ves el mismo enlace de pago, la misma dirección y la misma interfaz de wallet. Por debajo, el receptor es un smart contract en lugar de una wallet del servidor, pero tu flujo es idéntico.

Suscripciones​

El flujo de alta es el mismo que hoy: conecta tu wallet, firma approve (EVM) o Approve de SPL (Solana) y listo. La única diferencia visible es que el autorizado es una dirección de contrato (SubscriptionHub) en lugar de una hot wallet de OrcaRail. Tu wallet indicará claramente que el autorizado es un contrato.

Revócalo en cualquier momento retirando el allowance en la interfaz de aprobaciones de tokens de tu wallet. Tras revocarlo, el siguiente cobro programado fallará y recibirás un email. Puedes reanudarla firmando un nuevo approve.

Si ya eres suscriptor​

Cuando aparezca el banner de migración en tu página de gestión de la suscripción, verás una oferta para migrar. Al hacer clic:

  1. Se te pide revocar el allowance antiguo (opcional; queda inerte tras la migración).
  2. Se te pide firmar un nuevo approve hacia el contrato SubscriptionHub.

Eso es todo. Tu suscripción continúa sin interrupciones.

Si no migras, tu suscripción continúa en la ruta heredada hasta que la canceles o hasta el final de la ventana de migración definitiva anunciada en la Fase 7.

Para integradores (usuarios del SDK)​

Campos añadidos​

La forma de las respuestas de la API es totalmente retrocompatible. Campos nuevos:

  • payment_intent.receiver.contract_address
  • subscription.auto_charge.approval_spender_address (el valor puede cambiar a una dirección de contrato)
  • subscription.on_chain.* (dirección del hub de suscripciones, chain id, id bytes32 de la suscripción)
  • Los webhooks añaden un flag non_custodial: true cuando aplica.

Obsolescencias​

No se elimina ningún campo durante la transición. En la Fase 7, los campos que describen direcciones de firmantes custodiales se marcarán como obsoletos en la referencia de la API y se eliminarán en una versión mayor posterior del SDK (@orcarail/[email protected]) con 90 días de aviso.

Compatibilidad de webhooks​

Los tipos de evento y la forma de los payloads de payment.*, subscription.* y webhook.* no cambian. La ruta no custodial emite los mismos eventos en los mismos momentos.

Revocar a mitad de ciclo​

Si un pagador revoca su allowance entre ciclos:

  1. El siguiente charge() emite ChargeSkipped(InsufficientAllowance) on-chain.
  2. El indexador pasa la suscripción a past_due.
  3. Se envía al pagador la plantilla de email existente subscription-insufficient-allowance.hbs.
  4. Se dispara el webhook subscription.payment_failed del comercio.
  5. El pagador puede reanudar la suscripción volviendo a aprobar desde la página de gestión de la suscripción.

El comportamiento coincide con el actual de Cobro automático. Solo cambió la fontanería.

Consideraciones entre cadenas​

Si un pagador paga en una cadena distinta de la cadena de liquidación del comercio, Relay se encarga del puente (consulta Estrategia de retiros). La pila no custodial cambia quién llama a Relay (el receptor o la EOA keeper, no un firmante custodial) sin cambiar la ruta del puente en sí.

Referencia de calendario​

Consulta la Hoja de ruta para el estado actual. Las fechas son objetivos, no compromisos.

FaseQué puedes esperar
1Los enlaces de pago en Base pasan a ser no custodiales (canary opcional y después por defecto)
2Las suscripciones EVM migran en la renovación
3Ethereum, Arbitrum, Optimism y Polygon entran en producción
4Migran los enlaces de pago y las suscripciones de Solana
5Bitcoin pasa a multisig 2 de 2 (las suscripciones en BTC siguen sin soporte)
6Opcional: keeper descentralizado. Sin cambios para comercios ni pagadores.
7Se eliminan las rutas custodiales heredadas; aviso final de migración para los rezagados

Consulta también​