Saltar al contenido principal

Configuración avanzada

En esta guía, aprenderás sobre las opciones avanzadas de configuración para el Stellar Disbursement Platform (SDP). Estas configuraciones te permiten adaptar el SDP para cumplir con requisitos específicos, como multi-arrendamiento, selección de red y ajuste de rendimiento.

Configuración de Testnet a Mainnet​

Al aprovisionar una nueva instancia de SDP, esta se configura para operar en modo Mainnet o Testnet según las variables de entorno establecidas durante la configuración. La mayoría de los usuarios comenzarán con Testnet para desarrollo y pruebas antes de pasar a Mainnet para uso en producción.

advertencia

Una instancia de SDP está diseñada para operar en Testnet o Mainnet. No se admite cambiar entre estas redes en una instancia existente y podría causar comportamientos inesperados. Si necesitas cambiar la red, se recomienda crear una nueva instancia de SDP con la configuración deseada.

Una vez valides tu configuración en Testnet, puedes desplegar una nueva instancia configurada para Mainnet estableciendo las variables de entorno apropiadas durante el proceso de aprovisionamiento.

Variables de entorno​

Al cambiar de Testnet a Mainnet, debes actualizar las siguientes variables de entorno para cada servicio para apuntar a los recursos de la red pública.

Servicio principal de SDP​

VariableValor para TestnetValor para MainnetDescripción
NETWORK_PASSPHRASETest SDF Network ; September 2015Public Global Stellar Network ; September 2015La frase de contraseña para la red Stellar.
HORIZON_URLhttps://horizon-testnet.stellar.orghttps://horizon.stellar.orgLa URL del servidor Horizon.
DISABLE_MFAxfalseDesactiva la autenticación multifactor. Debe ser false para Mainnet.

Servicio de envío de transacciones (TSS)​

VariableValor para TestnetValor para MainnetDescripción
NETWORK_PASSPHRASETest SDF Network ; September 2015Public Global Stellar Network ; September 2015La frase de contraseña para la red Stellar.
HORIZON_URLhttps://horizon-testnet.stellar.orghttps://horizon.stellar.orgLa URL del servidor Horizon.

Panel de control​

VariableValor para TestnetValor para MainnetDescripción
HORIZON_URLhttps://horizon-testnet.stellar.orghttps://horizon.stellar.orgLa URL del servidor Horizon usado por el frontend.
STELLAR_EXPERT_URLhttps://stellar.expert/explorer/testnethttps://stellar.expert/explorer/publicLa URL para el explorador Stellar Expert.

Consideraciones críticas​

Antes de desplegar en Mainnet, debes atender los siguientes requisitos críticos para asegurar que tu instancia funcione correctamente.

Debes generar un nuevo par de claves seguro para tu Cuenta de Distribución en Mainnet. No reutilices las claves de Testnet.

  • Generar claves: Crea un nuevo par de claves y configura DISTRIBUTION_PUBLIC_KEY y DISTRIBUTION_SEED.
  • Generar frase de cifrado: Debes generar nuevas frases de cifrado para las cuentas de distribución de arrendatarios y cuentas de canal configurando DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE y CHANNEL_ACCOUNTS_ENCRYPTION_PASSPHRASE.
  • Financiar la cuenta: La Cuenta de Distribución requiere un saldo inicial de XLM para funcionar. Es responsable de:
    1. Crear cuentas de canal: El sistema creará automáticamente NUM_CHANNEL_ACCOUNTS (por defecto: 2).
    2. Bootstrapear arrendatarios: Cuando se aprovisiona un nuevo arrendatario, el sistema transfiere una cantidad de arranque de XLM desde la Cuenta de Distribución a la Cuenta de Distribución del arrendatario. Esto se controla mediante TENANT_XLM_BOOTSTRAP_AMOUNT (por defecto: 5 XLM).

Métodos de configuración​

Puedes configurar el SDP para Mainnet usando Helm Charts (para despliegues en Kubernetes) o Docker Compose (para despliegues locales o simples).

Helm Charts​

Si despliegas con Helm, el chart proporciona un ajuste global que configura automáticamente los parámetros de red necesarios.

En tu archivo values.yaml, configura global.isPubnet como true. Esto establecerá automáticamente el NETWORK_PASSPHRASE, HORIZON_URL y STELLAR_EXPERT_URL correctos para todos los servicios.

global:
  # Set to true for Mainnet
  isPubnet: true

Docker Compose​

Actualiza tu archivo .env con los siguientes valores:

# Network Configuration
NETWORK_TYPE="pubnet"
NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
HORIZON_URL="https://horizon.stellar.org"

# Security
DISABLE_MFA=false

# Distribution Account (Mainnet Keys)
DISTRIBUTION_PUBLIC_KEY="G..."
DISTRIBUTION_SEED="S..."

# Encryption Passphrases
DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE="S..."
CHANNEL_ACCOUNTS_ENCRYPTION_PASSPHRASE="S..."

Configuración de un solo arrendatario a multi-arrendatarios​

El Stellar Disbursement Platform (SDP) soporta multi-arrendamiento, permitiendo que una sola instancia sirva a varias organizaciones (arrendatarios). Cada arrendatario tiene sus propios datos aislados, usuarios y cuenta de distribución (fuente de fondos).

Configuración​

Para habilitar multi-arrendamiento, debes actualizar tu configuración para desactivar el modo de arrendatario único y asegurar el acceso a la API de administración.

  1. Desactivar modo de arrendatario único: Establece la variable de entorno SINGLE_TENANT_MODE a false.
  2. Exponer puerto de administración: Asegura que el puerto de la API de administración (por defecto 8003) esté expuesto en el servicio backend del SDP.

Enrutamiento e ingreso​

El SDP identifica al arrendatario para cada solicitud usando uno de los siguientes métodos, en orden de prioridad:

  1. Encabezado HTTP: El encabezado SDP-Tenant-Name.
  2. Subdominio: El prefijo del nombre de host (por ejemplo, tenant1 en tenant1.sdp.stellar.org).

Encabezado HTTP​

Puedes especificar explícitamente el arrendatario configurando el encabezado SDP-Tenant-Name en tus solicitudes HTTP.

curl -H "SDP-Tenant-Name: tenant1" https://sdp.stellar.org/ ...

Enrutamiento por subdominio​

En un entorno de producción, es común usar enrutamiento por subdominio. Por ejemplo, tenant1.sdp.stellar.org y tenant2.sdp.stellar.org apuntarán a la misma instancia de SDP.

Helm Charts​

Al desplegar con Helm, configuras el dominio wildcard usando el valor sdp.route.mtnDomain. Esto crea una regla de Ingress que coincide con todos los subdominios.

En tu archivo values.yaml:

sdp:
  route:
    # The wildcard domain for multi-tenancy
    mtnDomain: "*.sdp.stellar.org"
nota

Asegúrate de que tu proveedor DNS tenga un registro A wildcard (por ejemplo, *.sdp.stellar.org) apuntando a la IP del Load Balancer de tu Ingress Controller.

Docker Compose (desarrollo local)​

Para desarrollo local con Docker Compose debes mapear subdominios específicos de arrendatarios a 127.0.0.1 en el archivo /etc/hosts de tu máquina (para usuarios de Windows, el archivo está en C:\Windows\System32\drivers\etc\hosts).

Ejemplo de /etc/hosts:

127.0.0.1   localhost
127.0.0.1   sdp.local           # Default/Admin domain
127.0.0.1   tenant1.sdp.local   # First tenant
127.0.0.1   tenant2.sdp.local   # Second tenant

Aprovisionamiento de arrendatarios​

En modo multi-arrendatario, aprovisionas nuevos arrendatarios usando la API de administración (puerto 8003 por defecto). Cada arrendatario tendrá sus propios datos aislados.

Endpoint: POST /tenants Ejemplo de solicitud:

curl --location 'http://localhost:8003/tenants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64 Admin Credentials>' \
--data '{
    "name": "tenant1",
    "organization_name": "Tenant One Organization",
    "base_url": "https://tenant1.sdp-api.stellar.org",
    "sdp_ui_base_url": "https://tenant1.sdp-dashboard.stellar.org",
    "owner_email": "[email protected]",
    "owner_first_name": "Jane",
    "owner_last_name": "Doe",
    "distribution_account_type": "DISTRIBUTION_ACCOUNT.STELLAR.DB_VAULT"
}'

Cuentas de distribución multi-arrendatario​

Este es el campo más importante, ya que determina la fuente de fondos (cuenta de distribución) para el arrendatario, así como cómo se almacena el secreto de esta cuenta.

Esto se determina por el campo distribution_account_type en la llamada API mencionada arriba. Los valores posibles se describen a continuación:

  • DISTRIBUTION_ACCOUNT.STELLAR.DB_VAULT

  • Plataforma: Stellar

  • Ubicación de almacenamiento del secreto: Base de datos, cifrada con DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE

  • Activos soportados: Cualquier activo Stellar

  • Aislamiento de clave/secreto: Segregado por arrendatario

  • Adecuado para: Multi-arrendatario y arrendatario único

  • ¿Cómo se configura?: La cuenta de distribución se genera aleatoriamente y se financia durante el proceso de aprovisionamiento, y el secreto se cifra y almacena de forma segura en la base de datos. La cuenta se financia desde la cuenta HOST de distribución por una cantidad definida en TENANT_XLM_BOOTSTRAP_AMOUNT.

  • DISTRIBUTION_ACCOUNT.CIRCLE.DB_VAULT

  • Plataforma: Circle

  • Ubicación de almacenamiento del secreto: Base de datos, cifrada con DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE

  • Activos soportados: USDC/EURC

  • Aislamiento de clave/secreto: Segregado por arrendatario

  • Adecuado para: Multi-arrendatario y arrendatario único

  • ¿Cómo se configura?: La clave API de Circle la proporciona el propio arrendatario una vez que tiene acceso al panel de control. El secreto se cifra y almacena de forma segura en la base de datos.

  • 🔴 DISTRIBUTION_ACCOUNT.STELLAR.ENV

  • Plataforma: Stellar

  • Ubicación de almacenamiento del secreto: Variable de entorno DISTRIBUTION_SEED

  • Activos soportados: Cualquier activo Stellar

  • Aislamiento de clave/secreto: 🚨 Mismo cuenta de distribución que la HOST

  • Adecuado para: Solo arrendatario único

  • ¿Cómo se configura?: El arrendatario usará la cuenta HOST tal cual. El host es responsable de crear la cuenta y configurarla con el secreto DISTRIBUTION_SEED.

advertencia

Una vez creado un arrendatario, no se puede cambiar el tipo de cuenta de distribución. Si deseas usar un tipo diferente de cuenta de distribución, tendrás que crear un nuevo arrendatario.