Skip to main content

Configuring the SDP

Stellar Disbursement Platform services can be configured using a set of configuration options that are passed to the command line or set as environment variables. Depending on how you're using and deploying the SDP, these configurations can be set in a ConfigMap in Kubernetes, as environment variables in a Docker container, passed in as command line arguments, etc.

In this section we will discuss the different configuration options available for the SDP.

Notes:

  • Configurations that are tagged with 🔑 are sensitive and should be stored securely.
  • These configurations are valid for version 2.x of the SDP.
  • All configurations can be passed in as either environment variables or CLI flags. For instance, the env var BASE_URL could be passed in through the --base-url flag. CLI flags take priority over env vars, even though env vars are more convenient.

SDP Core Service​

For the most up-to-date configuration, you can run the following command in the stellar-disbursement-platform-backend git repository:

./stellar-disbursement-platform serve --help

Operational Configuration​

Operational Configuration allows controlling metrics, logging, and other operational aspects of the SDP Core Service.

  • PORT - The port on which the SDP Core Service will listen for incoming HTTP requests. Default: 8000.
  • LOG_LEVEL - Determines the verbosity level of logs. Options: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", or "PANIC". Default: "TRACE".
  • METRICS_PORT - The port on which the SDP Core Service will expose its metrics. Default: 8002.
  • METRICS_TYPE - The type of metrics to expose. Options: "PROMETHEUS". Default: "PROMETHEUS".
  • CRASH_TRACKER_TYPE - The crash tracker type to use. Options: "SENTRY", "DRY_RUN". Default: "DRY_RUN".
  • SENTRY_DSN - 🔑 The DSN (client key) of the Sentry project. If not provided, Sentry will not be used.
  • ENVIRONMENT - The environment where the application is running. Example: "development", "staging", "production". Default: "development".
  • DATABASE_URL - 🔑 The connection string for the PostgreSQL database. Format is postgres://username:password@host:port/database?sslmode=disable. Default: "postgres://localhost:5432/sdp?sslmode=disable".
  • BASE_URL - The SDP backend server's base URL. Default: "http://localhost:8000". Tenant-specific URLs will be configured during the tenant provisioning process.
  • SDP_UI_BASE_URL - The SDP UI/dashboard Base URL used to send the invitation link when a new user is created. Tenant-specific URLs will be configured during the tenant provisioning process.

Messaging Configuration​

Messaging Configuration allows configuring the messaging service used to send messages to recipients and sdp dashboard users. The default configuration is set to "DRY_RUN" which means no messages will be sent and the messages will be logged to the console. This is recommended for testing purposes only.

  • EMAIL_SENDER_TYPE: The messenger type used to send invitations to new dashboard users. Options: "DRY_RUN", "TWILIO_EMAIL", "AWS_EMAIL". Default: "DRY_RUN".
  • SMS_SENDER_TYPE: The messenger type used to send SMS messages to recipients. Options: "DRY_RUN", "TWILIO_SMS", "TWILIO_WHATSAPP", "AWS_SMS". Default: "DRY_RUN".

AWS Configuration​

The following configurations are required when using AWS SES or SNS to send emails or SMS messages.

  • AWS_ACCESS_KEY_ID - 🔑 The AWS access key ID.
  • AWS_REGION - The AWS region where the SES service is available.
  • AWS_SECRET_ACCESS_KEY - 🔑 The AWS secret access key.
  • AWS_SES_SENDER_ID - The email that AWS SES will use as the sender when sending emails. Required when EMAIL_SENDER_TYPE is set to "AWS_EMAIL".
  • AWS_SNS_SENDER_ID - The sender ID to use when sending SMS messages using AWS SNS. Required when SMS_SENDER_TYPE is set to "AWS_SMS".

Twilio Configuration​

The following configurations are required when SMS_SENDER_TYPE=TWILIO_SMS.

  • TWILIO_ACCOUNT_SID - 🔑 The Twilio account SID.
  • TWILIO_AUTH_TOKEN - 🔑 The Twilio auth token.
  • TWILIO_SERVICE_SID - The Twilio service SID.

The following configurations are required when SMS_SENDER_TYPE=TWILIO_WHATSAPP.

  • TWILIO_ACCOUNT_SID - 🔑 The Twilio account SID.
  • TWILIO_AUTH_TOKEN - 🔑 The Twilio auth token.
  • TWILIO_SERVICE_SID - The Twilio service SID.
  • TWILIO_WHATSAPP_FROM_NUMBER - The WhatsApp Business number used to send messages (with whatsapp: prefix).
  • TWILIO_WHATSAPP_RECEIVER_INVITATION_TEMPLATE_SID - The Twilio Content SID for WhatsApp receiver invitation template (starts with HX).
  • TWILIO_WHATSAPP_RECEIVER_OTP_TEMPLATE_SID - The Twilio Content SID for WhatsApp receiver OTP template (starts with HX).

The following configurations are required when EMAIL_SENDER_TYPE=TWILIO_EMAIL.

  • TWILIO_SENDGRID_API_KEY - 🔑 The API key for the Twilio SendGrid (email) service.
  • TWILIO_SENDGRID_SENDER_ADDRESS - The email address used to send emails via Twilio SendGrid.

General Messaging Configuration​

  • MAX_INVITATION_RESEND_ATTEMPTS - The maximum number of attempts to (auto) resend the invitation to the Receiver Wallets. Default: 3.

Stellar Configuration​

Stellar Configuration allows configuring accounts, transactions, and other Stellar-related settings.

  • NETWORK_PASSPHRASE - The Stellar network passphrase. Default "Test SDF Network ; September 2015".
  • HORIZON_URL - The URL of the Horizon server to use for submitting transactions. Default "https://horizon-testnet.stellar.org/".
  • SEP10_SIGNING_PUBLIC_KEY - The public key of the Stellar account that signs the SEP-10 transactions. It's also used to sign URLs.
  • SEP10_SIGNING_PRIVATE_KEY - 🔑 The private key of the Stellar account that signs the SEP-10 transactions. It's also used to sign URLs.
  • MAX_BASE_FEE - The max base fee for submitting a Stellar transaction. Default: 10000.

Channel Accounts Configuration​

The following configurations are required for using channel accounts to submit transactions to the Stellar network.

  • NUM_CHANNEL_ACCOUNTS - Number of channel accounts to utilize for transaction submission. Default: 2. :- CHANNEL_ACCOUNT_ENCRYPTION_PASSPHRASE - 🔑 A Stellar ed25519 secret key (starting with S) used to encrypt/decrypt the channel accounts' private keys. When not set, it will default to the value of DISTRIBUTION_SEED.

Distribution Accounts Configuration​

The following configurations are related to the distribution accounts used to send funds to recipients. This configuration should match the configuration in the SDP Core Service.

  • DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE - 🔑 A Stellar ed25519 secret key (starting with S) used to encrypt/decrypt the in-memory distribution accounts' private keys.
  • DISTRIBUTION_PUBLIC_KEY - The public key of the HOST's Stellar distribution account. Used to disburse funds, create channel accounts and tenant distribution accounts.
  • DISTRIBUTION_SEED - 🔑 The private key of the HOST's Stellar distribution account. Used to disburse funds, create channel accounts and tenant distribution accounts.

Security Configuration​

Security Configuration allows configuring the security aspects of the SDP Core Service.

  • CORS_ALLOWED_ORIGINS - Specifies the domains allowed to make cross-origin requests. "" means all domains are allowed. Domains can contain wildcards, e.g., "https://.example.com".
  • SEP24_JWT_SECRET - 🔑 The secret used to sign the JWT token for SEP-24 transactions. This secret is used during the receiver wallet registration flow.

Dashboard Authentication Configuration​

The following configurations are related to dashboard user authentication and authorization.

  • RESET_TOKEN_EXPIRATION_HOURS - The expiration time in hours of the Reset Password Token. Default: 24 (hours).
  • EC256_PUBLIC_KEY - The EC256 Public Key used to validate the token signature. This EC key needs to be at least as strong as prime256v1 (P-256).
  • EC256_PRIVATE_KEY - 🔑 The EC256 Private Key used to sign the authentication token. This EC key needs to be at least as strong as prime256v1 (P-256).
  • DISABLE_MFA - Disables Multi-Factor Authentication (MFA) for the SDP dashboard users.
  • DISABLE_RECAPTCHA - Disables Google reCAPTCHA v2 for the SDP dashboard users. This flag doesn't affect the reCAPTCHA used during the SEP-24 flow.

Recaptcha Configuration​

The following configurations are required when using Google reCAPTCHA v2 to protect the SDP Core Service from bots. ReCaptcha is used both for dashboard users and receivers of funds during the SEP-24 flow.

  • RECAPTCHA_SITE_KEY - The Google reCAPTCHA v2 - I'm not a robot site key.
  • RECAPTCHA_SITE_SECRET_KEY - 🔑 The reCAPTCHA site secret key used to validate reCAPTCHA responses.

Background Jobs Configuration​

  • SCHEDULER_PAYMENT_JOB_SECONDS: Interval in seconds for the job that synchronizes payments between SDP and TSS. Minimum is 5s.
  • SCHEDULER_RECEIVER_INVITATION_JOB_SECONDS: Interval in seconds for the job that submits receiver invitations. Minimum is 5s.

Multi-tenancy Configuration​

  • ADMIN_ACCOUNT: The username of the admin account used to authenticate HTTP requests to the Admin server. The Admin-targeted requests should add the "Authorization" header, formatted as Base64-encoded "ADMIN_ACCOUNT:ADMIN_API_KEY".
  • ADMIN_API_KEY: The api key of the admin accountused to authenticate HTTP requests to the Admin server. The Admin-targeted requests should add the "Authorization" header, formatted as Base64-encoded "ADMIN_ACCOUNT:ADMIN_API_KEY".
  • ADMIN_PORT: the port of the Admin server used to create and manage tenants. Default is 8003.
  • INSTANCE_NAME: the name of the SDP instance to be displayed in the stellar.toml file. Example: "SDP Testnet".
  • SINGLE_TENANT_MODE: When set to "true", it enables the single-tenant mode, which is useful for local development or single-tenant setups. In addition to set it to true, you'll need to configure the default tenant by calling the POST /tenants/default-tenant request.
  • TENANT_XLM_BOOTSTRAP_AMOUNT: The amount of XLM that the HOST Stellar account will deposit deposited to the tenant distribution account for tenant bootstrap.

Transaction Submission Service (TSS)​

For the most up-to-date configuration, you can run the following command in the stellar-disbursement-platform-backend git repository:

./stellar-disbursement-platform tss --help

General Configuration​

  • QUEUE_POLLING_INTERVAL - Polling interval (seconds) to query the database for pending transactions to process. Default: 6.

Operational Configuration​

Operational Configuration allows controlling metrics, logging, and other operational aspects of the Transaction Submission Servic (TSS)

  • LOG_LEVEL - Determines the verbosity level of logs. Options: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", or "PANIC". Default: "TRACE".
  • TSS_METRICS_PORT - The port on which the TSS will expose its metrics. Default: 9002.
  • TSS_METRICS_TYPE - The type of metrics to expose. Options: "PROMETHEUS". Default: "PROMETHEUS".
  • CRASH_TRACKER_TYPE - The crash tracker type to use. Options: "SENTRY", "DRY_RUN". Default: "DRY_RUN".
  • SENTRY_DSN - 🔑 The DSN (client key) of the Sentry project. If not provided, Sentry will not be used.
  • ENVIRONMENT - The environment where the application is running. Example: "development", "staging", "production". Default: "development".
  • DATABASE_URL - 🔑 The connection string for the PostgreSQL database. Format is postgres://username:password@host:port/database?sslmode=disable. Default: "postgres://localhost:5432/sdp?sslmode=disable".

Stellar Configuration​

Stellar Configuration allows configuring accounts, transactions, and other Stellar-related settings.

  • NETWORK_PASSPHRASE - The Stellar network passphrase. Default "Test SDF Network ; September 2015".
  • HORIZON_URL - The URL of the Horizon server to use for submitting transactions. Default "https://horizon-testnet.stellar.org/".
  • MAX_BASE_FEE - The max base fee for submitting a Stellar transaction. Default: 10000.

Channel Accounts Configuration​

The following configurations are required for using channel accounts to submit transactions to the Stellar network.

  • NUM_CHANNEL_ACCOUNTS - Number of channel accounts to utilize for transaction submission. Default: 2.
  • CHANNEL_ACCOUNT_ENCRYPTION_PASSPHRASE - 🔑 A Stellar ed25519 secret key (starting with S) used to encrypt/decrypt the channel accounts' private keys. When not set, it will default to the value of the 'DISTRIBUTION_SEED' option.

Distribution Accounts Configuration​

The following configurations are related to the distribution accounts used to send funds to recipients. This configuration should match the configuration in the SDP Core Service.

  • DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE - 🔑 A Stellar ed25519 secret key (starting with S) used to encrypt/decrypt the in-memory distribution accounts' private keys.
  • DISTRIBUTION_PUBLIC_KEY - The public key of the HOST's Stellar distribution account. Used to disburse funds, create channel accounts and tenant distribution accounts.
  • DISTRIBUTION_SEED - 🔑 The private key of the HOST's Stellar distribution account. Used to disburse funds, create channel accounts and tenant distribution accounts.

Dashboard​

The SDP Dashboard is a web application that allows users to manage their accounts, view transaction history, and more. Environment variables can be set either on a global window._env_ object or as process.env variables. All environment variables used in this repo are in src/constants/envVariables.ts file, including types. The default location of the window._env_ object is public/settings/env-config.js.

General Configuration​