Saltar al contenido principal

Hacer Que Tu Billetera Sea Compatible con SDP

Recuerda que cualquier instancia de SDP necesitará un acuerdo con un proveedor de billetera antes de enviar desembolsos a esa billetera. Esto asegura que las billeteras se sientan cómodas recibiendo fondos de tu organización y regula cualquier acuerdo comercial entre las organizaciones. La billetera necesitará permitir la lista blanca del dominio de SDP antes de que el SDP pueda enviar desembolsos a esa billetera. Cuando el dominio de la billetera es añadido a un SDP, efectivamente está siendo incluido en la lista blanca por el SDP. Ambas partes listando la otra les permite recuperar el archivo stellar.toml y verificar la clave de firma necesaria para el apretón de manos SEP-10.

En esta página, cubriremos los aspectos técnicos de la integración de SDP-Billetera, incluyendo cómo añadir una billetera en la base de datos de SDP, cómo validar y admitir los enlaces de registro utilizando el deep linking de la aplicación móvil, cómo iniciar el flujo de registro de usuario en la billetera usando SEP-24, y un enfoque recomendado para manejar [deferred deep linking].

Añadir una Billetera a un SDP​

La lista predeterminada de billeteras SDP depende de qué red se esté utilizando (testnet o pubnet). La red se pasa como una variable de entorno y luego la lista de billeteras puede ser sembrada apropiadamente al iniciar SDP a través del comando de CLI ./stellar-disbursement-platform db setup-for-network, de acuerdo con una lista codificada de billeteras conocidas. Alternativamente, las billeteras pueden ser insertadas directamente en la base de datos de SDP a través de un comando SQL. Ambos métodos requieren agregar el nombre de la billetera, la página de inicio, el dominio del cliente SEP-10 y el esquema del enlace profundo.

Para insertarlo directamente en la base de datos, actualiza tus valores y ejecuta la siguiente consulta de Postgres. Asegúrate de verificar tu base de datos y espacio de nombres primero.

INSERT INTO wallets (name, homepage, deep_link_schema, sep_10_client_domain)
VALUES ('Vibrant Assist', 'https://vibrantapp.com', 'https://vibrantapp.com/sdp', 'api.vibrantapp.com');

Para configurar una billetera a través del código, añádela a la sección de testnet o pubnet de DefaultWalletsNetworkMap. Esto se usará cuando ejecutes el comando CLI ./stellar-disbursement-platform db setup-for-network, que actualiza la base de datos de SDP y hace que la billetera esté disponible para nuevos desembolsos. Añade tu nueva billetera siguiendo el mismo formato que ya está presente en el código.

var DefaultWalletsNetworkMap = WalletsNetworkMapType{
	utils.PubnetNetworkType: {
		{
			Name:              "Vibrant Assist",
			Homepage:          "https://vibrantapp.com/assist",
			DeepLinkSchema:    "https://vibrantapp.com/sdp",
			SEP10ClientDomain: "api.vibrantapp.com",
		},
	},
	utils.TestnetNetworkType: {
		{
			Name:              "Vibrant Assist",
			Homepage:          "https://vibrantapp.com",
			DeepLinkSchema:    "https://vibrantapp.com/sdp-dev",
			SEP10ClientDomain: "api-dev.vibrantapp.com",
		},
		{
			Name:              "Demo Wallet",
			Homepage:          "https://demo-wallet.stellar.org",
			DeepLinkSchema:    "https://demo-wallet.stellar.org",
			SEP10ClientDomain: "demo-wallet-server.stellar.org",
		},
	},
}
advertencia

Por favor asegúrate de actualizar la configuración apropiada en el lado de Anchor Platform, de acuerdo con la guía de Anchor Platform Integration Points.

Experiencia de Registro del Destinatario​

La experiencia de registro del destinatario es primordial para que esta aplicación sea fluida y fácil de usar. Esto requiere que la billetera admita [deferred deep linking], que se discutirá en una sección posterior. Una buena descripción de la experiencia de registro es la siguiente:

  1. El destinatario recibe un mensaje de invitación notificándole que tiene un pago esperando de la organización y le solicita hacer clic en un deep link para abrir o instalar y abrir una aplicación de billetera

  2. Cuando el destinatario abre la aplicación de billetera, la billetera a bordo inmediatamente al destinatario, crea una cuenta Stellar y una línea de confianza para el activo deseado, inicia una transacción de depósito SEP-24 con el SDP, y abre la página de registro del SDP como una pantalla de superposición/iframe dentro de la aplicación.

  3. El usuario confirma su número de teléfono y fecha de nacimiento directamente con el SDP, sin compartir ningún dato con la billetera, y después de que finaliza el registro, el usuario es enviado de nuevo a la aplicación de billetera. Aquí están las pantallas que demuestran estos pasos:

    Flujo de Registro

  4. El usuario recibe el pago en cuestión de segundos

Enlace Profundo de Registro​

Una vez que el usuario ha instalado la aplicación de billetera, la billetera debería ser capaz de interpretar un deep link que sigue el formato registrado en el SDP para iniciar el Procedimiento de Registro de Billetera. El formato de enlace profundo admitido por el SDP sigue este formato:

https://<host-with-optional-path>?asset=<asset>&domain=<domain>&name=<name>&signature=<signature>
  • asset: el activo Stellar.
  • domain: el dominio que aloja el archivo stellar.toml de SDP. La billetera necesitará usarlo tanto para obtener el archivo stellar.toml, como para poblar el campo home_domain en la transacción de GET de desafío SEP-10.
  • name: el nombre de la organización que envía pagos.
  • signature: una firma de la clave de firma de SEP-10 de SDP.
información

Ten en cuenta que el enlace profundo es específico para cada SDP, organización pagadora y activo. No es específico por receptor individual. No hay riesgo en compartir el enlace con receptores que forman parte del mismo desembolso. El enlace será el mismo para múltiples receptores y demostrarán su identidad como parte del flujo de depósito SEP-24.

A continuación se muestra un ejemplo de un enlace de registro (firmado)

https://vibrantapp.com/sdp-dev?asset=USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5&domain=ap-stellar-disbursement-platform-backend-dev.stellar.org&name=Stellar+Test&signature=fea6c5e805a29b903835bea2f6c60069113effdf1c5cb448d4948573c65557b1d667bcd176c24a94ed9d54a1829317c74f39319076511512a3e697b4b746ae0a

En este ejemplo, el host es https://vibrantapp.com/sdp-dev y la firma es el resultado de firmar la siguiente url (sin firmar) utilizando la clave de firma SEP-10 SBUSPEKAZKLZSWHRSJ2HWDZUK6I3IVDUWA7JJZSGBLZ2WZIUJI7FPNB5, siendo la clave pública GBFDUUZ5ZYC6RAPOQLM7IYXLFHYTMCYXBGM7NIC4EE2MWOSGIYCOSN5F:

https://vibrantapp.com/sdp-dev?asset=USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5&domain=ap-stellar-disbursement-platform-backend-dev.stellar.org&name=Stellar+Test

En este ejemplo, la firma es fea6c5e805a29b903835bea2f6c60069113effdf1c5cb448d4948573c65557b1d667bcd176c24a94ed9d54a1829317c74f39319076511512a3e697b4b746ae0a.

A continuación se muestra un fragmento de JavaScript que demuestra cómo verificar la firma:

#!/usr/bin/env node

const { Keypair } = require("stellar-sdk");

// The SDP's stellar.toml SIGNING_KEY
//
// For security, this should ideally be fetched from
// https://<domain>/.well-known/stellar.toml on demand
const keypair = Keypair.fromPublicKey(
  "GBFDUUZ5ZYC6RAPOQLM7IYXLFHYTMCYXBGM7NIC4EE2MWOSGIYCOSN5F",
);
console.log("public key:", keypair.publicKey());

let url =
  "https://vibrantapp.com/sdp-dev?asset=USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5&domain=ap-stellar-disbursement-platform-backend-dev.stellar.org&name=Stellar%20Test";
let signature =
  "fea6c5e805a29b903835bea2f6c60069113effdf1c5cb448d4948573c65557b1d667bcd176c24a94ed9d54a1829317c74f39319076511512a3e697b4b746ae0a";

console.log(
  "verified:",
  keypair.verify(
    Buffer.from(url.toString(), "utf8"),
    Buffer.from(signature, "hex"),
  ),
);

Procedimiento de Registro de Billetera​

Al abrir el deep link de registro, estos son los pasos que la billetera debería seguir para hacer cumplir las medidas de seguridad y privacidad esperadas en este flujo, y permitir que el usuario ingrese su información directamente con el SDP:

  1. 🚨 Confirma que el domain del enlace profundo está en la lista blanca de la billetera. Esto es crucial para autenticar desde una billetera de confianza.🚨
  2. Obtén el archivo toml de SDP en {domain}/.well-known/stellar.toml y confirma que la variable SIGNING_KEY esté poblada.
  3. Verifica que la firma del enlace de registro se haya realizado utilizando SIGNING_KEY similar a la función keypairPk.verify(...) en el fragmento anterior, y que la firma sea válida con el contenido del enlace.
  4. Verifica el asset del enlace y confirma que el usuario destinatario tenga una línea de confianza para ese activo. Crea una si no existe.
  5. (Opcional) Usa el name del enlace para actualizar la interfaz de usuario de la billetera.
  6. Inicia el flujo de depósito SEP-24 con ese activo usando el valor de TRANSFER_SERVER_SEP0024 del archivo toml de SDP.
    • Esto incluye utilizar SEP-10 para autenticar al usuario con el servidor SDP. Por favor nota que el SDP requiere que tanto el campo client_domain como el home_domain sean proporcionados en la solicitud GET <WEB_AUTH_ENDPOINT>, y deben establecerse de la siguiente manera:
      • client_domain: el dominio del servidor de billetera que expone el archivo stellar.toml del servidor de billetera.
    • home_domain: el dominio del servidor de SDP que estaba presente en el enlace de registro.
    • account: la cuenta Stellar de la billetera del receptor.
  7. Lanza el flujo de depósito en un navegador in-app interactivo dentro de tu aplicación móvil, siguiendo las instrucciones en la especificación SEP-24.
    • ATENCIÓN: la billetera no debe, bajo ninguna circunstancia, extraer o intentar extraer el contenido del navegador in-app para obtener la información del destinatario.
    • NOTA: se recomienda encarecidamente usar un navegador in-app en lugar de una webview.
  8. 🎉 ¡Felicidades! El usuario destinatario puede ahora completar los formularios en el navegador in-app y registrarse para recibir su pago 🎉.

Además, la billetera debería guardar el enlace y/o atributos del enlace y asociarlo con el usuario receptor individual por estas razones:

  1. Así es como la billetera sabrá que el usuario está asociado con una cierta organización o SDP.
  2. Guardar los datos es útil para reportar y solucionar problemas, especialmente si la billetera necesita justificar la fuente de fondos por motivos regulatorios o fiscales.
  3. Si la organización pagadora quiere pagar cualquier tarifa de retiro cobrada por la billetera o el serviciador, la billetera necesitará saber qué usuarios y transacciones deberían ser facturadas hacia arriba.

Enlaces Profundos Diferidos​

Es muy probable que el destinatario previsto no tenga instalada la aplicación de billetera necesaria en su dispositivo. Por esta razón, las billeteras deberían soportar el concepto de [deferred deep linking], que habilita el siguiente flujo:

  1. La acción inicial del destinatario de hacer clic en el enlace profundo debería redirigirlo a la tienda de aplicaciones correspondiente para descargar la aplicación de billetera.
  2. Después de instalar y abrir la aplicación, el destinatario debería ser redirigido al flujo de incorporación típico de la billetera.
  3. Una vez que el usuario se haya incorporado con éxito, la billetera debería usar la información incluida en el enlace profundo para iniciar el Procedimiento de Registro de Billetera.

El deep linking diferido es una característica comúnmente soportada por numerosas soluciones de deep linking móvil, existen servicios de terceros que pueden ser usados para implementar esta funcionalidad, como Singular, Branch, AppsFlyer, Adjust y otros. Aquí hay una publicación de blog con más información sobre cómo implementar [deferred deep linking].

El SDP soporta un formato de enlace básico, como https://<host-with-optional-path>. Si el sistema de deep linking de tu billetera necesita una estructura más compleja, tendrás que gestionar esto con una aplicación web. Esta aplicación debería ser propiedad del proveedor de la billetera, y debería ser capaz de recibir el enlace profundo, interpretarlo y dirigir al usuario a la ubicación correcta.