10. Trae usuarios y fondos desde otras cadenas
Lleva usuarios y sus fondos a tu app de Rome desde otras cadenas y desde Solana, con el puente, su API y la CLI, y mantén la pantalla de tu app en vivo.
Tu app funciona con ambos tipos de billetera. Ahora los usuarios necesitan una forma de llegar. La mayoría tiene USDC en otra cadena o en Solana, y no deberían tener que aprender a usar Rome primero. En esta lección se usa la API de Rome Bridge para traer USDC desde una cadena compatible, hacer seguimiento de la transferencia y permitir que los usuarios retiren sus fondos, mientras tu app se mantiene al día. 2. Qué puedes crear muestra dónde encaja esto.
Qué aprenderás
Cómo un usuario de otra cadena puede acceder a tu app de Rome sin salir de su entorno habitual.
Cómo llegan a Rome los USDC de un usuario desde una cadena EVM y desde Solana.
Por qué una transferencia llega como gas o como wUSDC y cómo elegir.
Los cuatro pasos de una transferencia entrante.
Por qué salir de Rome requiere más pasos que llegar.
Cómo mostrar el estado en tiempo real en tu app y consultar una transferencia en el explorador.
Antes de empezar
Completa 9. Crear una app de doble vía. Necesitas la bóveda o cualquier app a la que quieras que accedan los usuarios.
Ten instalado Rome CLI (Rome CLI + MCP).
Ten USDC de prueba en una cadena de origen y el token nativo de esa cadena para pagar la comisión. Puedes obtenerlos en Faucets.
La lección
Paso 1. Comprende las dos formas de llegar
Con Rome Bridge, tus usuarios llegan desde uno de dos lugares. Una cadena EVM envía USDC mediante CCTP de Circle. Una billetera de Solana envía SOL o USDC mediante transferencias SPL simples. En ambos casos, la transferencia se realiza en la cadena y se liquida con la firma del propio usuario. La API de Bridge, que funciona fuera de la cadena, cotiza la ruta, verifica la transacción de origen y patrocina la comisión de liquidación. No custodia fondos ni claves, así que solo puede activar lo que el usuario ya firmó.
Las cadenas y los activos compatibles varían entre la testnet y la mainnet, así que consulta las listas en lugar de dar nada por sentado. Están en Rome Bridge, y la lista actual está disponible en /v1/routes. El patrón para acceder a tu app desde la cadena de origen del usuario se explica en Desde tu entorno habitual.
Paso 2. Elige entre gas y wUSDC
Por defecto, los USDC que llegan mediante el puente se reciben como gas. El gas es lo que paga en comisiones un usuario de MetaMask. El token que acepta tu bóveda es wUSDC. Son dos formas del mismo USDC, y el usuario puede convertir una en la otra.
Configura la intención en la cotización. Una app que acepta wUSDC, como tu bóveda, necesita que los usuarios lleguen con wUSDC. Si un usuario llega como gas, primero envuelve una parte, como en la lección 9. Quien tenga previsto volver a salir necesita wUSDC, porque para transferir hacia fuera se quema wUSDC, no gas. Puede llegar con wUSDC o envolver parte del gas más adelante con withdraw_to_ata.
Paso 3. Realiza una transferencia entrante
Una transferencia entrante consta de cuatro pasos. La subruta /bridge del SDK agrupa las llamadas a la API como requestQuote, registerTransfer, getTransfer y reportStep. Su registerTransfer (v0.4.0) sigue enviando la cotización completa, algo que la API actual rechaza, así que registra la transferencia tú mismo con el quoteId , como hace Rome CLI.
Cotiza la ruta. Envía la cadena de origen, el activo, el importe, el remitente y el destinatario. Las cadenas se indican mediante identificadores CAIP-2, y los importes son cadenas de enteros en unidades base.
El usuario firma las transacciones del primer paso, en orden y exactamente tal como se devuelven. En una transferencia CCTP, se trata de la aprobación de USDC y la quema. En la ruta de gas, el usuario también firma una autorización de liquidación EIP-712 después de que completes el hash de la quema.
Registra la transferencia. Envía el
quoteIdde la cotización y el hash de la quema comostep1TxHashaPOST /v1/transfersen un plazo de 15 minutos desde la cotización. En la ruta de gas, añade la firma de liquidación comouserSettleSig. La API comprueba que la transacción coincida con la cotización almacenada y devuelve un ID de transferencia.Consulta el estado de la transferencia hasta que
outcomeseacomplete, y gestiona los estadosfailedyexpired. Una transferencia completada puede incluir una nota dedegradation, así que compruébala antes de decirle al usuario que han llegado el gas o wUSDC.
Las transferencias entrantes a Solana siguen el mismo esquema, pero con pasos distintos. El usuario envía una transferencia SPL a su cuenta de Rome. Con la intención de gas, si USDC está en una cadena cuyo token de gas es USDC, el usuario debe realizar una transacción adicional para convertir el token envuelto en gas. La cotización enumera todas las firmas que requiere la ruta. Estructuras de solicitud y respuesta: Desde el entorno local.
Paso 4. Pruébalo primero desde la CLI
Antes de escribir código para el puente, ejecuta el flujo con la CLI. rome fund introduce USDC como gas, rome bridge acepta una intención de gas o de token envuelto, y rome verify --path from-home verifica un ciclo completo de ida y vuelta: entrada por el puente, operación en Rome y salida por el puente. Así tendrás una referencia funcional con la que comparar tu integración. Comandos y opciones: CLI de Rome + MCP.
Paso 5. Gestiona la salida
La salida por el puente no es el flujo de entrada a la inversa. Para transferir USDC mediante CCTP, el usuario firma dos pasos. El paso 1 consta de dos transacciones en Rome: una autorización que permite al contrato del puente mover el importe exacto que se va a quemar y, después, la quema. Registra la transferencia con el hash de la quema. El paso 2 es la reclamación. Cuando el paso 2 de la transferencia indique ready, incluirá el mensaje y la atestación, y el usuario los enviará a la cadena de destino mediante receiveMessage . La reclamación no está patrocinada, así que el usuario necesita gas en esa cadena. Comunica el hash de la reclamación a la API (reportStep en el SDK). Llamadas y estructuras: Retira los activos.
Retirar a una dirección de Solana no requiere un paso de reclamación. Para USDC, basta con una transacción en Rome que lo retire a la cuenta de Solana del usuario.
La autorización es importante para tu aplicación. Una cuenta de tokens solo puede tener un delegado, por lo que la autorización del puente reemplaza la del token envuelto hasta que el usuario vuelva a autorizarlo. Comprueba isEnabled antes del siguiente depósito, como se explica en la lección 9.
Paso 6. Mantén tu aplicación activa
Los endpoints de Rome admiten eth_subscribe para newHeads y logs, en el mismo host que el RPC HTTPS. Con ethers, provider.on("block") y contract.on(event) funcionan igual que en cualquier otro lugar. Con viem, el webSocket transporte descarta los ID de suscripción numéricos de Rome, así que pasa poll: true a watchBlocks y watchEvent o usa ethers para recibir actualizaciones push. newPendingTransactions nunca emite nada porque Rome no tiene una mempool pública. Código: Suscripciones de WebSocket.
Al consultar el historial, limita cada llamada a eth_getLogs a un rango de bloques. El RPC de Rome rechaza los rangos que superan aproximadamente los 12 000 bloques. En el caso de una transacción que interactúa con Solana, la fila «Liquidada en» de Via enlaza con la transacción de Solana que la liquidó, y el explorador de Solana muestra sus instrucciones y unidades de cómputo. Así puedes responder a un usuario que pregunta dónde está su transferencia. Consulta Via y Compatibilidad con JSON-RPC.
Solgate: activos de Solana y cadenas EVM de AggLayer
En la testnet, Solgate conecta activos de Solana con cadenas EVM de AggLayer en ambas direcciones y transmite mensajes entre contratos. USDC usa CCTP. Los pasos anteriores utilizan la API de Rome Bridge.
Para transferir otros tokens o enviar mensajes, consulta 13. Desarrolla en Solgate.
Comprueba tus conocimientos
Realiza una transferencia real y obsérvala.
Añade fondos a una billetera Hadrian nueva con algo de USDC para gas y luego transfiere más USDC con
rome bridgey la intención del wrapper. Reserva suficiente gas para las aprobaciones, las llamadas a la bóveda y la quema de salida.Consulta el saldo de wUSDC de la billetera en Hadrian, por ejemplo, con
rome callen el wrapper, usandobalanceOf. Con la intención del wrapper, la llegada corresponde a la transacción de Solana del puente (el mensaje de recepción de Circle), no a una transacción de Rome; por tanto, no esperes ver una transacción de llegada en el explorador de Hadrian.Repite la transferencia mediante la API: cotiza, firma, registra y luego consulta periódicamente
GET /v1/transfers/{id}hasta queoutcomemuestrecomplete.Ejecuta
rome verify hadrian --path from-homecon--from(tu cadena de origen) y--amount(una cantidad pequeña, como 0.2) y luego consulta el resultado. Tarda unos 20 minutos.
Después, responde:
¿De qué saldo se descuentan los USDC que se queman en una transferencia de salida y cómo puede obtenerlo un usuario?
¿Quién paga la reclamación en la cadena de destino?
Siguiente
Última actualización
¿Te fue útil?