Saltar al contenido principal

Comenzar

En esta guía, aprenderás a:

  • crear y financiar una cuenta de distribución de host que puede ser utilizada para financiar cuentas de distribución a nivel de inquilino o directamente para hacer pagos
  • configurar una instancia de la Stellar Disbursement Platform (SDP) localmente
  • provisionar un nuevo inquilino y crear credenciales de inicio de sesión para los usuarios pertenecientes al inquilino
  • configurar una cuenta Stellar para aceptar fondos como receptor
  • realizar tu primera distribución
  • registrar tu cuenta receptora en la SDP
  • verifica tu saldo después de recibir el pago

Al final de esta guía, tendrás una comprensión clara de la funcionalidad de la Stellar Disbursement Platform y una configuración local funcional lista para el desarrollo o las pruebas.

Ten en cuenta que, aunque estaremos usando USDC y la Demo Wallet en esta guía, otros activos y billeteras de Stellar pueden ser utilizados en el desarrollo o producción.

Crear y financiar una cuenta de distribución de host​

Necesitarás un mínimo de dos cuentas al usar la Stellar Disbursement Platform, una cuenta de distribución y una cuenta receptora. Crearemos la cuenta de distribución ahora y crearemos la cuenta receptora mientras hacemos nuestra primera distribución.

  1. Ve a la Stellar Demo Wallet y selecciona 'Generar keypair para nueva cuenta'
  2. Selecciona el botón 'Crear cuenta' junto a la clave pública para financiar tu cuenta con XLM
  3. Selecciona el botón 'Seleccionar de activos preestablecidos' y selecciona USDC
  4. Finalmente, selecciona 'Agregar trustline' para habilitar pagos de USDC

Ahora que tenemos una cuenta que puede enviar y recibir USDC, vamos a financiarla con suficiente USDC para nuestra primera distribución. Puedes financiar tu cuenta de distribución desde cualquier fuente de liquidez de Stellar USDC, pero aquí te mostramos cómo hacerlo a través del Circle Sandbox y Stellar Lab.

  1. Crea una cuenta en Circle Sandbox
  2. Una vez que estés en el panel, selecciona 'Obtener clave API' y cópiala en tu portapapeles
  3. Ve a la Circle Sample App e introduce tu clave API después de seleccionar el ícono de configuración en la esquina superior derecha
  4. Selecciona 'Carga de flujo', luego 'Prefill Form', y selecciona una tarjeta para usar (no importa cuál)
  5. Introduce la cantidad que te gustaría comprar, luego selecciona 'Hacer pago'

Esto financiará tu cuenta de Circle Sandbox con USDC. Puedes repetir el proceso anterior cuando te quedes sin fondos o la red de pruebas se restablezca, lo que ocurre trimestralmente.

Tu USDC debería aparecer en tu cuenta dentro de unos minutos, que puedes verificar usando el endpoint de saldos. Una vez financiada, puedes enviarlo a tu cuenta de distribución creada anteriormente.

  1. Selecciona el ícono en la parte superior izquierda, luego 'Payouts API' y finalmente 'POST /transfers'
  2. Selecciona 'Obtener ID de billetera maestra' para cargar la billetera financiada con USDC
  3. Introduce la cantidad que te gustaría enviar
  4. Selecciona el tipo de destino 'blockchain' y luego 'XLM'
  5. Pega la clave pública de la cuenta que creaste con la billetera demo anteriormente
  6. Selecciona 'Hacer llamada a la API'

¡Circle enviará el pago de USDC a la red de pruebas Stellar y deberías recibir fondos en tu cuenta de billetera demo casi inmediatamente!

También puedes adquirir USDC a través del Stellar Lab si lo prefieres. Antes de comenzar, asegúrate de que tu cuenta demo esté financiada con XLM y tenga una trustline a USDC. Construir una transacción en el Lab con tu cuenta de billetera demo como la cuenta de origen. Crear una operación de Envío Estricto de Pago de Rutas con la misma cuenta como la cuenta de destino. Usa XLM (nativo) como el activo de envío y USDC emitido por GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 como el activo de destino. Puedes establecer tu cantidad mínima de destino preferida basada en cuánto XLM envías, pero la cantidad no es importante en la red de pruebas. Una cantidad mínima muy baja asegurará el intercambio. Firma la transacción y envíala a la red.

¡USDC llegará a tu cuenta de billetera demo en segundos! Actualiza la cuenta en la página de billetera demo para ver el nuevo saldo.

Ejecutar la SDP localmente​

Requisitos previos​

Docker​

Asegúrate de tener Docker instalado en tu sistema. Si no, puedes descargarlo aquí.

Cuentas Stellar​

Necesitaremos dos cuentas Stellar para configurar la SDP, una de las cuales creaste anteriormente.

  1. Una cuenta de distribución de host que será utilizada para enviar fondos a los receptores. Deberías haber creado esta cuenta utilizando el proceso de Crear y financiar una cuenta de distribución de host arriba.
  2. Una cuenta SEP-10 que será utilizada para autenticación. Puede ser creada de la misma manera que la cuenta de distribución, pero no necesita ser financiada. Asegúrate de crear esta cuenta ahora si aún no lo has hecho.

La clave pública y privada de estas dos cuentas serán utilizadas para configurar la SDP en el siguiente paso.

Ejecutar la SDP​

Primero, necesitarás clonar el proyecto.

git clone [email protected]:stellar/stellar-disbursement-platform-backend.git

Antes de ejecutar la SDP, necesitamos configurarla con las cuentas creadas en el paso anterior.

cd stellar-disbursement-platform-backend/dev

Crea un archivo .env en el directorio dev copiando el archivo .env.example:

cp .env.example .env

Actualiza el archivo .env con las claves pública y privada de las dos cuentas creadas en el paso anterior.

Ejecuta el siguiente comando para crear todos los contenedores Docker necesarios para ejecutar la SDP, así como provisionar inquilinos de muestra:

./main.sh

Esto iniciará los siguientes servicios:

  • sdp_v2_database: La base de datos principal de la SDP y TSS.
  • anchor-platform-postgres-db: Base de datos utilizada por la plataforma ancla.
  • anchor-platform: Una instancia local de la plataforma ancla.
  • sdp-api: Servicio SDP ejecutándose en el puerto 8000.
  • sdp-tss: Servicio de envío de transacciones.
  • sdp-frontend: Servicio frontend de la SDP ejecutándose en el puerto 3000.
  • kafka: Servicio Kafka ejecutándose en los puertos 9092, 9094(external).
  • kafka-init: Flujo de trabajo inicial para ejecutar el contenedor de Kafka y crear temas.
  • demo-wallet: El cliente de billetera demo que será utilizado como billetera receptora, ejecutándose en el puerto 4000.

Proceso de aprovisionamiento de nuevos inquilinos​

Cuando ejecutaste el archivo main.sh, ya creaste nuevos inquilinos: tenants=("redcorp" "bluecorp"). Para agregar más inquilinos, simplemente añádelos separados por espacios a esa variable de esta manera: tenants=("redcorp" "bluecorp" "greencorp") y ejecuta main.sh nuevamente.

Asegúrate de que los hosts de inquilino añadidos estén incluidos en el archivo de configuración de hosts. Para comprobarlo, puedes ejecutar el comando cat /etc/hosts. Para incluirlos, puedes ejecutar el comando sudo nano /etc/hosts e insertar las líneas a continuación:

127.0.0.1       bluecorp.sdp.local
127.0.0.1       redcorp.sdp.local

Configura la contraseña del usuario propietario para cada inquilino​

Pasa por el flujo de olvidé mi contraseña para poder iniciar sesión como un usuario propietario.

Ve a la página de olvidar contraseña en http://${tenant}.stellar.local:3000/forgot-password e introduce el inquilino y el correo electrónico del propietario owner@${tenant}.org.

Se generará un token y es posible verificarlo en los registros de sdp-api. Este token será necesario para Restablecer la Contraseña en http://${tenant}.stellar.local:3000/reset-password.

Iniciar sesión​

Una vez que la contraseña de tu usuario objetivo de la organización se haya restablecido a una de tu elección, navega al panel abriendo un navegador a localhost:3000 e inicia sesión con la cuenta de usuario. Login

Haz clic en el botón Iniciar sesión y se abrirá el panel de SDP. En este momento no tendrás datos de desembolsos. Dashboard

Crea tu primer desembolso​

Navega al servicio frontend abriendo un navegador y yendo a http://bluecorp.stellar.local:3000.

  • Haz clic en Nuevo Desembolso+ en la pantalla del Panel.
  • Usa Demo Wallet como tu billetera y elige un método de verificación.
  • Sube un archivo de desembolso. Un archivo de plantilla puede ser descargado en la página frontend al crear un desembolso, y la plantilla cambiará de acuerdo con las opciones establecidas para ese desembolso. También puedes encontrar los archivos de plantilla en public/resources/disbursementTemplates. Asegúrate de actualizar el archivo antes de usarlo cambiando la información de contacto a la tuya y eliminando la línea de comentario.
  • Finalmente, confirma el desembolso.

Disbursement Details

También tienes la opción de modificar el mensaje en la invitación al receptor. Disbursment Details 2

Depositar dinero​

Para depositar dinero en tu cuenta:

  • Accede a demo-wallet en tu navegador.
  • Haz clic en Generar Keypair para nueva cuenta para generar un nuevo keypair. Asegúrate de guardar tu clave pública y secreto si deseas usar esta cuenta más tarde.
  • Haz clic en Crear cuenta (frente a la clave pública) para crear la cuenta en la Stellar testnet.
  • Tu cuenta recién creada tendrá 10.000 XLM.
  • Agrega tu dominio principal a la cuenta haciendo clic en Agregar Dominio Principal e ingresando http://bluecorp.stellar.local:8000.
  • En el menú desplegable Seleccionar acción, selecciona SEP-24 Depositar.
  • En la nueva ventana, ingresa el número de teléfono del CSV de desembolso.
  • Introduce el código de acceso. Puedes usar el código de acceso 000000 o encontrar el código de acceso real en los registros del contenedor sdp-api.
  • Introduce la fecha de nacimiento que coincide con el número de teléfono en el CSV.
  • Mantén un ojo en el panel hasta que el estado del pago alcance Éxito. Si todo fue configurado correctamente, tu dinero debería distribuirse con éxito.

Resolución de problemas​

Cuenta de distribución sin fondos​

Los pagos comenzarán a fallar si la cuenta de distribución se queda sin fondos. Para solucionarlo, puedes escribir un script que financie la cuenta de distribución o utilizar las herramientas disponibles para agregar más fondos a la cuenta de distribución siguiendo estos pasos:

  • La dirección de la cuenta de distribución se puede encontrar bajo Cuenta de Distribución en la barra lateral del frontend. Copia esa dirección.
  • Accede a https://horizon-testnet.stellar.org/accounts/:accountId en tu navegador y verifica el saldo.
  • Si el saldo es realmente bajo, puedes agregar más fondos creando una nueva cuenta y enviando fondos a la cuenta de distribución.
    • Accede a demo-wallet.stellar.org en tu navegador.
    • Haz clic en Generar Keypair para nueva cuenta para crear una nueva cuenta de testnet. Tu cuenta viene con 10.000 XLM.
    • Haz clic en Enviar e introduce la clave pública de la cuenta de distribución y la cantidad que deseas enviar.
    • Usando Freighter o Stellar Lab, intercambia el XLM por USDC si deseas probar con USDC.

Verifica tu identidad​

Cuando se crea un desembolso, la SDP intenta enviar un mensaje a los receptores utilizando Twilio/AWS para SMS o correo electrónico, de acuerdo con el tipo de contacto asociado con el usuario. Este mensaje incluye un enlace a la aplicación de billetera seleccionada al crear el desembolso, y debe dirigir al receptor a instalar la aplicación de billetera, pasar por el flujo de incorporación de la billetera y, finalmente, registrarse en la SDP.

información

Nota que la configuración inicial tiene SMS_SENDER_TYPE=DRY_RUN y EMAIL_SENDER_TYPE=DRY_RUN, lo que significa que los mensajes serán impresos en los registros (del contenedor sdp-api) en lugar de ser enviados.

Consulta la sección Mensajes de correo electrónico y SMS para aprender cómo configurar la mensajería en la SDP. Cuando lo hagas, y se cree otro desembolso, deberías recibir un mensaje como el siguiente.

Verify Identity

Crear una cuenta receptora​

Hacer clic en el enlace del mensaje de iniciación llevará al receptor a la demo-wallet, donde necesitarán crear una cuenta que será utilizada para recibir el pago de USDC. Sigue el mismo proceso descrito anteriormente para crear la cuenta y agregar una trustline a USDC.

Iniciar flujo web SEP-24​

Ahora necesitaremos conectar la billetera demo a la instancia de la SDP que se ejecuta localmente. Para hacer esto, selecciona el ícono de lápiz junto a "centre.io" debajo de tu saldo de USDC e introduce "localhost:8080".

En el menú desplegable 'Seleccionar Acción', selecciona 'SEP-24 Depositar' para iniciar un flujo web SEP-24, que desencadena el proceso de Registro de Usuario para vincular la nueva billetera al número de teléfono en la SDP.

SEP-24

Aparecerá una ventana interactiva de SEP-24, donde el receptor puede seleccionar el tipo de información de contacto (por ejemplo, número de teléfono o correo electrónico) que está registrado para ellos en la base de datos de SDP.

Webflow1

En la siguiente pantalla de SEP-24 el usuario debe ingresar los datos de información de contacto (número de teléfono o correo electrónico) del CSV de desembolso.

Webflow2

A continuación, ingresa el código de acceso y el campo de verificación que utilizaste en el archivo de desembolso. Nota: usa 000000 para este ejemplo (o 999999 si quieres ver una respuesta de error).

Código de acceso y Cumpleaños

El webflow proporciona un mensaje que indica tu registro exitoso, que es el desencadenante para que el SDP envíe el pago. Deberías recibir tu pago del SDP en breve.

Mensaje

Verifica tu saldo​

Actualiza tu cuenta. La Demo Wallet ahora debería mostrar un saldo de 2 USDC enviados desde el SDP (o la cantidad que se definió en el archivo CSV).

Éxito

Mantén un ojo en el panel hasta que el estado del pago alcance Éxito. Si todo se configuró correctamente, tu dinero debería ser desembolsado exitosamente.

Desembolso

Siguiente: Actualización de secretos de aplicación​

Ahora que has podido hacer un desembolso, volvamos a nuestros archivos de docker compose y actualicemos algunos valores. Este es un paso importante antes de ir a producción. Actualizaremos claves de encriptación y secretos de aplicación.

Mensajes de Email y SMS​

La Stellar Disbursement Platform envía correos a los usuarios y SMS/correos a los receptores. Para mensajes SMS, la Stellar Disbursement Platform admite Twilio, AWS SNS, y un modo de prueba que solo registra los mensajes. Para correos electrónicos, admite AWS SES, Twilio SendGrid, y modo de prueba.

Estos servicios se pueden seleccionar a través de las configuraciones SMS_SENDER_TYPE y EMAIL_SENDER_TYPE. Al seleccionar servicios de Twilio o AWS, necesitarás completar su configuración específica del servicio también. A continuación hay algunas configuraciones de ejemplo, y puedes mezclar y combinar los servicios como mejor te parezca.

Configuración de Modo de Prueba​

El modo de prueba es útil para probar el SDP sin enviar mensajes reales. Registrarás los mensajes en la consola en lugar de enviarlos al receptor. Esta es la configuración predeterminada y funciona tanto para SMS como para Email.

EMAIL_SENDER_TYPE: DRY_RUN
SMS_SENDER_TYPE: DRY_RUN

Configuración de SMS de Twilio​

SMS_SENDER_TYPE: TWILIO_SMS

# Twilio specific configuration
TWILIO_ACCOUNT_SID:
TWILIO_AUTH_TOKEN:
TWILIO_SERVICE_SID:

Configuración de Email de Twilio (Send Grid)​

SMS_SENDER_TYPE: TWILIO_EMAIL

# Twilio specific configuration
TWILIO_SENDGRID_API_KEY:
TWILIO_SENDGRID_SENDER_ADDRESS:

Configuración de SMS de AWS​

SMS_SENDER_TYPE: AWS_SMS

# AWS specific configuration.
# This is needed for both AWS Email and SMS
AWS_ACCESS_KEY_ID:
AWS_REGION:
AWS_SECRET_ACCESS_KEY:

# AWS SNS configuration
AWS_SNS_SENDER_ID:

Configuración de Email de AWS​

EMAIL_SENDER_TYPE: AWS_EMAIL

# AWS specific configuration.
# This is needed for both AWS Email and SMS
AWS_ACCESS_KEY_ID:
AWS_REGION:
AWS_SECRET_ACCESS_KEY:

# AWS SNS configuration
AWS_SES_SENDER_ID:

Autenticación​

Las billeteras se autentican con la Stellar Disbursement Platform utilizando un protocolo de autenticación mutua, donde tanto el SDP como la billetera demuestran que poseen sus cuentas Stellar firmando una carga útil intercambiada entre sí. Una vez que este proceso esté completo, se proporciona un JWT a la billetera para usar en futuras solicitudes. Adicionalmente, los microservicios del SDP utilizan tokens de autenticación para comunicarse entre sí y para encriptar las contraseñas de los usuarios. Necesitamos proporcionar valores actualizados para todos estos casos de uso.

En docker-compose-sdp-anchor.yml, actualiza lo siguiente:

# The public key of the Stellar account used for SEP-10 authentication:
SEP10_SIGNING_PUBLIC_KEY:
#
# The private key of the Stellar account used for SEP-10 authentication. It
# should be the same secret key for both attributes below, for the Stellar
# Disbursement Platform and Anchor Platform:
SEP10_SIGNING_PRIVATE_KEY:
SECRET_SEP10_SIGNING_SEED:
#
# The encryption key used to sign the resulting SEP-10 JWT token:
SECRET_SEP10_JWT_SECRET:
#
# A shared encryption key used to sign JWT tokens in the SEP-24 from the Anchor
# Platform to the Stellar Disbursement Platform. The value needs to be the same
# for all three attributes below:
SEP24_JWT_SECRET:
SECRET_SEP24_INTERACTIVE_URL_JWT_SECRET:
SECRET_SEP24_MORE_INFO_URL_JWT_SECRET:
#
# A shared encryption key used to sign JWT tokens in the PlatformAPI
# communications from the Stellar Disbursement Platform to the Anchor Platform.
# The value needs to be the same for both attributes below:
ANCHOR_PLATFORM_OUTGOING_JWT_SECRET:
SECRET_PLATFORM_API_AUTH_SECRET:
#
# The private key is used to sign JWT tokens for authenticating the requests
# incoming to the Stellar Disbursement Platform. The Public key is used to
# validate that the JWT token was signed by the SDP's private key. They can be
# generated with these commands:
# openssl ecparam -name prime256v1 -genkey -noout -out ec_private_key.pem
# openssl pkcs8 -topk8 -nocrypt -in ec_private_key.pem -out ec_private_key_pkcs8.pem
# openssl ec -in ec_private_key.pem -pubout -out ec_public_key.pem
EC256_PUBLIC_KEY:
EC256_PRIVATE_KEY:
#

Hay muchos otros valores de configuración que actualizar al mover a un entorno de producción, como credenciales de base de datos, URLs, y más.

Sube de nivel​

Activos y Billeteras Personalizados​

El SDP contiene una lista de activos y billeteras disponibles para desembolsos listos para usar. Podrías querer personalizarlos, ya sea para limitar/ampliar opciones o para prepararte para ir en vivo en producción. Ahora que has hecho un desembolso y añadido secretos de aplicación, veamos cómo personalizar las nuevas opciones de desembolso.

Activos​

Puedes agregar y eliminar activos fácilmente en el panel del SDP. El backend del SDP maneja la solicitud sin problemas, incluyendo la verificación del saldo pendiente y la adición/eliminación de líneas de confianza en la red Stellar. Cuando se eliminan activos, el registro se conserva en la base de datos para preservar un historial completo. Sin embargo, el activo ya no estará disponible para desembolsos o mantener un saldo en la cuenta de distribución.

Dirígete a la página de Billeteras del panel del SDP para agregar y eliminar activos. Necesitarás el código de activo Stellar y la clave pública del emisor del activo.

advertencia

Por favor asegúrate de actualizar la configuración adecuada en el lado de Anchor Platform, de acuerdo con la guía de Puntos de Integración de Anchor Platform.

Billeteras​

Para una visión completa sobre cómo agregar billeteras y cómo hacer que una billetera sea compatible con SDP, consulta la guía de Preparar Tu Billetera para SDP.

Registro de Dirección de Billetera​

Desde la versión 3.0.0, el SDP puede pagar directamente a direcciones de billetera Stellar en lugar de dirigir a los receptores a través del flujo de registro. Esto es útil para organizaciones que están pagando a receptores que ya tienen billeteras Stellar y no necesitan crear una nueva.

Para usar esta función, sigue estos pasos:

  1. Asegúrate de que la Billetera Administrada por el Usuario esté habilitada en la sección de Proveedores de Billetera (también disponible en GET /wallets).
  2. Si no está habilitada, puedes actualizarla a través del panel de UI o con PATCH /wallets/{id}.
  3. Ahora puedes crear un desembolso y seleccionar del dropdown de Tipo de Contacto de registro una opción que contenga Dirección de Billetera en el nombre.
  4. Prepara el archivo CSV de acuerdo con el muestra de CSV asociado con tu configuración de desembolso.
  5. Sube el archivo CSV y confirma el desembolso como de costumbre. El SDP enviará el pago directamente a las direcciones de billetera proporcionadas en el CSV ✅.