|
| 1 | +--- |
| 2 | +title: Enviar y recibir pagos de Cuentas de Contrato |
| 3 | +description: Aprende a enviar pagos a y recibir pagos de Cuentas de Contrato en la red Stellar. |
| 4 | +sidebar_position: 7 |
| 5 | +--- |
| 6 | + |
| 7 | +import { CodeExample } from "@site/src/components/CodeExample"; |
| 8 | +import { Alert } from "@site/src/components/Alert"; |
| 9 | +import Details from "@theme/Details"; |
| 10 | + |
| 11 | +Los pagos entre Cuentas de Contrato (direcciones C) y Cuentas Clásicas (direcciones G) están admitidos a nivel de protocolo, pero existen diferencias en las implementaciones necesarias para admitirlas. Esta guía cubrirá implementaciones para aplicaciones que usan cuentas clásicas G y desean admitir transacciones con Cuentas de Contrato. |
| 12 | + |
| 13 | +## Recibir pagos de Cuentas de Contrato (de C a G) |
| 14 | + |
| 15 | +Si el emisor usa una Cuenta de Contrato y envía un [token SAC](https://developers.stellar.org/docs/tokens/stellar-asset-contract) (como XLM, USDC, etc.), la transacción será recibida normalmente por la cuenta G, dado que está admitida a nivel de protocolo. |
| 16 | + |
| 17 | +### Recibir pagos de Cuentas de Contrato que requieren un memo |
| 18 | + |
| 19 | +Entidades como exchange y emisores de activos suelen usar cuentas omnibus, utilizando una dirección de recepción compartida y un memo identificador único, como: |
| 20 | + |
| 21 | +- **Cuenta:** `GBLVHX33XGOBDOXK7ERDL34NVH6WW7VTT2OBAHPJ7G3D423HBG5NOMY7` |
| 22 | +- **ID de Memo:** `123456789` |
| 23 | + |
| 24 | +Las transacciones que involucran Cuentas de Contrato utilizan invocaciones de contrato para ejecutar una función 'transfer' en el contrato del activo. Este tipo de transacción no permite usar el campo 'memo'; en cambio, la aplicación emisora lo codificará en la dirección, generando una dirección multiplexada única que incluye la cuenta receptora (GBLVHX…) y el id proporcionado en el campo muxed id (123456789). |
| 25 | + |
| 26 | +Para admitir depósitos provenientes de Cuentas de Contrato, no es necesario cambiar la información mostrada a los clientes ni las cuentas de depósito usadas por el exchange. Las billeteras seguirán usando la cuenta G y el memo proporcionado para enviar un pago a la cuenta G del exchange incluyendo el memo con el ID único. |
| 27 | + |
| 28 | +Esa es la principal diferencia entre recibir de clientes usando cuentas G o de Contrato: en lugar de mirar el campo memo para identificar la cuenta individual, observarás el ID multiplexado. Todo lo demás permanece igual. |
| 29 | + |
| 30 | +#### Ejemplo usando Horizon |
| 31 | + |
| 32 | +**Recibiendo de una dirección G** |
| 33 | + |
| 34 | +Usando el endpoint `accounts/{acc_id}/transactions` de Horizon ([ejemplo](https://horizon-testnet.stellar.org/accounts/GBLVHX33XGOBDOXK7ERDL34NVH6WW7VTT2OBAHPJ7G3D423HBG5NOMY7/transactions)) |
| 35 | + |
| 36 | +El campo memo estará presente en la respuesta. |
| 37 | + |
| 38 | +**Ejemplo de respuesta desde una dirección G:** |
| 39 | + |
| 40 | +```json |
| 41 | +{ |
| 42 | + "memo": "123456789", |
| 43 | + "memo_bytes": "MTIzNDU2Nzg5", |
| 44 | + "source_account": "GCNG5JXJY3LNRMXCX23RIGKTURQACTSV5LL6NKL535BYRGOGWUX6J45Y", |
| 45 | + "memo_type": "text" |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +**Recibir desde una Cuenta de Contrato** |
| 50 | + |
| 51 | +Usando el endpoint `accounts/{acc_id}/payments` de Horizon ([ejemplo](https://horizon-testnet.stellar.org/accounts/GBLVHX33XGOBDOXK7ERDL34NVH6WW7VTT2OBAHPJ7G3D423HBG5NOMY7/payments)) |
| 52 | + |
| 53 | +Después de que se procesa la transacción, este detalle de pago estará presente en el endpoint '/payments', bajo una sección llamada 'asset_balance_changes', que mostrará el ID codificado y la dirección G subyacente por separado. |
| 54 | + |
| 55 | +Es importante notar que la sección 'asset_balance_changes' solo admite activos Stellar y transacciones que utilizan la función `transfer` en el [Contrato de Activos Stellar (SAC)](https://developers.stellar.org/docs/tokens/stellar-asset-contract). |
| 56 | + |
| 57 | +**Respuesta de ejemplo desde una Cuenta de Contrato:** |
| 58 | + |
| 59 | +```json |
| 60 | +{ |
| 61 | + "asset_balance_changes": [ |
| 62 | + { |
| 63 | + "asset_type": "native", |
| 64 | + "type": "transfer", |
| 65 | + "from": "CBP4GFAK4GDKCMVLNIHRZPEAPT7CFYTBKICOXCVMP2FEN3QFKCRZ27KS", |
| 66 | + "to": "GBLVHX33XGOBDOXK7ERDL34NVH6WW7VTT2OBAHPJ7G3D423HBG5NOMY7", |
| 67 | + "amount": "1.0000000", |
| 68 | + "destination_muxed_id": "123456789" |
| 69 | + } |
| 70 | + ] |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +Para un ejemplo de código detallado, consulta la sección 'Monitoreo de Pagos -> Usando la API de Horizon' de [los ejemplos de este repositorio](https://github.com/fazzatti/c-address-payment-examples#monitoring-payments). |
| 75 | + |
| 76 | +#### Ejemplo usando RPC |
| 77 | + |
| 78 | +Desde el lanzamiento de los Eventos de Activos Unificados ([CAP-67](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md)) en el Protocolo 23, varias transacciones que involucran activos Stellar emiten eventos estandarizados que pueden ser ingeridos tanto por la API de Horizon como por el Stellar RPC. Si los fondos se envían a través de una operación 'payment' o invocando la función 'transfer' del contrato de activos, se emite el mismo tipo de evento para ambos casos. |
| 79 | + |
| 80 | +Para monitorear estos pagos, se usa el método '[getEvents](https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getEvents)' del Stellar RPC para transmitir eventos emitidos por el Contrato de Activos Stellar. Se puede usar un filtro para especificar el activo objetivo (ID del contrato SAC) y las cuentas. |
| 81 | + |
| 82 | +**Desde una dirección G** |
| 83 | + |
| 84 | +Cuando el receptor es una dirección G normal, la parte valor del evento es simplemente la cantidad recibida. |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + "inSuccessfulContractCall": true, |
| 89 | + "topicJson": [ |
| 90 | + { |
| 91 | + "symbol": "transfer" |
| 92 | + }, |
| 93 | + { |
| 94 | + "address": "GD6MYLASTCZ3H4UFLH2YSIASHJNBFUCKC5YHGU44VCH2BGHN3WJQX6LG" |
| 95 | + }, |
| 96 | + { |
| 97 | + "address": "GA4PDUF3BLBSK47UTNY44AIZAP5EPHW2UIJRKB5HN76HHC55IWKSIHFD" |
| 98 | + }, |
| 99 | + { |
| 100 | + "string": "native" |
| 101 | + } |
| 102 | + ], |
| 103 | + "valueJson": { |
| 104 | + "i128": "10000000" |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +**Desde una Cuenta de Contrato** |
| 110 | + |
| 111 | +Cuando la transacción se envía usando una cuenta muxed, la parte valor del evento se desglosa en un objeto que contiene la cantidad y el ID único codificado en la dirección. |
| 112 | + |
| 113 | +```json |
| 114 | +{ |
| 115 | + "inSuccessfulContractCall": true, |
| 116 | + "topicJson": [ |
| 117 | + { |
| 118 | + "symbol": "transfer" |
| 119 | + }, |
| 120 | + { |
| 121 | + "address": "GD6MYLASTCZ3H4UFLH2YSIASHJNBFUCKC5YHGU44VCH2BGHN3WJQX6LG" |
| 122 | + }, |
| 123 | + { |
| 124 | + "address": "GA4PDUF3BLBSK47UTNY44AIZAP5EPHW2UIJRKB5HN76HHC55IWKSIHFD" |
| 125 | + }, |
| 126 | + { |
| 127 | + "string": "native" |
| 128 | + } |
| 129 | + ], |
| 130 | + "valueJson": { |
| 131 | + "map": [ |
| 132 | + { |
| 133 | + "key": { |
| 134 | + "symbol": "amount" |
| 135 | + }, |
| 136 | + "val": { |
| 137 | + "i128": "10000000" |
| 138 | + } |
| 139 | + }, |
| 140 | + { |
| 141 | + "key": { |
| 142 | + "symbol": "to_muxed_id" |
| 143 | + }, |
| 144 | + "val": { |
| 145 | + "u64": "123456789" |
| 146 | + } |
| 147 | + } |
| 148 | + ] |
| 149 | + } |
| 150 | +} |
| 151 | +``` |
| 152 | + |
| 153 | +Para un ejemplo de código detallado, consulta la sección ‘_Monitoreo de Pagos \-\> Uso del Stellar RPC_’ de [los ejemplos de este repositorio](https://github.com/fazzatti/c-address-payment-examples#using-the-stellar-rpc). |
| 154 | + |
| 155 | +### Envío de pagos desde Cuentas de Contrato a un destinatario que requiere un memo |
| 156 | + |
| 157 | +Si un remitente usa una Cuenta de Contrato y envía un [token SAC](https://developers.stellar.org/docs/tokens/stellar-asset-contract) (como XLM, USDC, etc.) a un destinatario que requiere un memo (por ejemplo, un exchange), debe crear una dirección muxed que incluya la cuenta receptora (GBLVHX…) y la id de memo proporcionada en el campo de id muxed (123456789). En la interfaz de usuario, la dirección de memo resultante no necesita mostrarse al usuario, debe usarse directamente en la transacción. |
| 158 | + |
| 159 | +Si la parte receptora ya proporciona una dirección M, debe utilizarse directamente, sin necesitar un campo de memo. Como este es el valor proporcionado por el usuario, debe usarse en la transacción y mostrarse al usuario. |
| 160 | + |
| 161 | +## Envío de pagos a Cuentas de Contrato (de G a C) |
| 162 | + |
| 163 | +### Envío de un ‘transfer’ vía Stellar RPC {#sending-a-‘transfer’-via-stellar-rpc} |
| 164 | + |
| 165 | +Este método es más sencillo pero requiere el uso de un RPC e implica un flujo de transacciones algo diferente al de una operación nativa tradicional. Para un ejemplo de código detallado, consulta la sección ‘_Enviando pagos a través del SAC \-\> Uso del Stellar RPC_’ de [los ejemplos de este repositorio](https://github.com/fazzatti/c-address-payment-examples#sending-payments-through-the-sac). |
| 166 | + |
| 167 | +**Armado de la operación y la transacción**\ |
| 168 | +Para realizar un ‘transfer’ a través de un SAC, es necesario armar una operación ‘_InvokeHostFunctionOp_’ con argumentos similares a una operación ‘payment’, junto con el identificador del contrato y el nombre de la función objetivo (‘transfer’). |
| 169 | + |
| 170 | +Esto puede verse en detalle en la función ‘[assembleTransferOperation](https://github.com/fazzatti/c-address-payment-examples/blob/main/src/core/assemble-transfer-operation.ts)’ del demo. Aunque el ejemplo muestra este proceso con mayor detalle, es posible usar el [js-stellar-sdk](https://github.com/stellar/js-stellar-sdk) y su cliente de Contrato de manera más simple. |
| 171 | + |
| 172 | +Luego la transacción se desarrolla añadiendo esta operación y configurando los parámetros adicionales como en cualquier otra transacción ‘payment’. |
| 173 | + |
| 174 | +**Simular la transacción**\ |
| 175 | +Después de construir la transacción, se usa el método RPC ‘simulateTransaction’ para simular la ejecución de esta transacción contra el estado actual de la red, identificar si se espera que tenga éxito y también proporcionar varios parámetros adicionales sobre esta ejecución. |
| 176 | + |
| 177 | +Este proceso es completamente manejado por el SDK en un paso muy simple usando la función ‘_prepareTransaction_’ del cliente del servidor RPC. Automáticamente simula y proporciona un objeto de transacción actualizado. Consulta este proceso en detalle [en el demo](https://github.com/fazzatti/c-address-payment-examples/blob/0e1c021e5afbefd5946878d53934b62cf5a8bb68/src/core/rpc-transaction.ts#L43). |
| 178 | + |
| 179 | +**Firmando**\ |
| 180 | +Cuando la misma cuenta se usa como ‘remitente’ de los fondos y también como ‘fuente’ de la transacción, el paso de firmar será exactamente igual. Una vez que se recibe el objeto de transacción actualizado del paso anterior, solo debes firmarlo con la cuenta fuente/remitente y estará listo. |
| 181 | + |
| 182 | +Cuando la cuenta ‘fuente’ de la transacción difiere de la cuenta ‘remitente’, será necesaria una entrada firmada adicional para autorizar explícitamente la invocación ‘transfer’. Consulta la [documentación del Marco de Autorización Soroban](https://developers.stellar.org/docs/learn/fundamentals/contract-development/authorization#soroban-authorization-framework) para más detalles. |
| 183 | + |
| 184 | +**Enviando la Transacción para procesamiento**\ |
| 185 | +Cuando una transacción se envía para procesamiento a través del Stellar RPC, a diferencia de la API de Horizon, resolverá inmediatamente confirmando su envío pero no su procesamiento. Es necesario consultar el estado de la transacción periódicamente hasta obtener una confirmación de que fue procesada exitosamente o una actualización del estatus en caso de falla. |
| 186 | + |
| 187 | +### Envío de un ‘transfer’ vía API Horizon |
| 188 | + |
| 189 | +Al enviar un ‘transfer’ vía API Horizon, este método introduce algunos pasos adicionales en comparación con el uso de un RPC. Para un ejemplo de código detallado, consulta la sección ‘_Enviando pagos a través del SAC \-\> Uso de la API Horizon_’ de [los ejemplos de este repositorio](https://github.com/fazzatti/c-address-payment-examples#using-the-horizon-api-1). |
| 190 | + |
| 191 | +**Armado de la operación y la transacción**\ |
| 192 | +Este proceso es casi el mismo que se describe en la sección anterior ‘[Enviando un ‘transfer’ vía Stellar RPC](#sending-a-‘transfer’-via-stellar-rpc)’ con algunas pequeñas modificaciones. Dado que la API de Horizon **no** provee un endpoint para simular la ejecución de una transacción, esto significa que cuando se arma la transacción necesitamos asegurarnos también de que contiene: |
| 193 | + |
| 194 | +- Las **entradas de autorización Soroban** que cumplen con los requisitos de autorización de los contratos inteligentes. |
| 195 | +- El objeto **Soroban data**, que detalla la huella, los recursos y la tarifa de recursos esperada para esta invocación de contrato. |
| 196 | + |
| 197 | +Estos normalmente se completan automáticamente basados en la salida de la simulación y simplemente firmando y agregando las entradas de autorización generadas por el RPC. Aquí, necesitamos incluirlos manualmente. |
| 198 | + |
| 199 | +Las **entradas de autenticación** pueden predecirse y armarse fácilmente según la configuración. Asumiendo que la cuenta ‘remitente’ es la misma que la cuenta ‘fuente’ de la transacción, se necesita agregar una credencial de cuenta fuente a la operación, indicando que esta invocación usará la misma firma del sobre para autorizar el ‘transfer’. Consulta este proceso en detalle en la función [‘assembleSourceAuthEntry’](https://github.com/fazzatti/c-address-payment-examples/blob/main/src/core/assemble-source-auth.ts) del demo. |
| 200 | + |
| 201 | +Una vez que las entradas de autenticación están armadas y firmadas (cuando no son entradas ‘source-account’), deben incluirse en la operación, en el parámetro ‘auth’. |
| 202 | + |
| 203 | +Por otro lado, el proceso para el **Soroban Data** puede ser un poco más difícil de ejecutar manualmente. Considerando que todos los contratos SAC usan la misma implementación nativa, podemos esperar que todas las invocaciones ‘transfer’ sean muy similares. |
| 204 | + |
| 205 | +La cantidad de recursos consumidos no debería variar mucho salvo algunos casos excepcionales como transacciones que involucran entradas archivadas o una autorización personalizada para una billetera inteligente como remitente. Consulta este proceso de armado manual del Soroban Data en la función [’getSorobanData’](https://github.com/fazzatti/c-address-payment-examples/blob/main/src/core/get-sorobandata.ts) del demo. |
| 206 | + |
| 207 | +Una vez armado el **Soroban Data**, se incluye en el **Constructor de Transacciones**. |
| 208 | + |
| 209 | +**Firmando**\ |
| 210 | +Después de construir la transacción, asumiendo que las ‘entradas auth’ del paso anterior fueron configuradas correctamente, la transacción puede firmarse normalmente por la cuenta fuente. |
| 211 | + |
| 212 | +**Enviando la Transacción para procesamiento**\ |
| 213 | +Este paso permanece igual que con cualquier transacción enviada a través de la API de Horizon. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments