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", "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 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.

The remaining configurations related to distribution accounts are detailed in the Stellar accounts configuration section of 1.x to 2.x Migration Guide.

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.

Anchor Platform Configuration​

Anchor Platform Configuration allows configuring the anchor platform used by the SDP Core Service.

  • ANCHOR_PLATFORM_BASE_PLATFORM_URL - The base URL of the anchor platform.
  • ANCHOR_PLATFORM_BASE_SEP_URL - The base URL of the anchor platform's SEP-24 implementation.
  • ANCHOR_PLATFORM_OUTGOING_JWT_SECRET - 🔑 The JWT secret used to create a JWT token used to send requests to the anchor platform.

Event Broker and Scheduled Jobs Configuration​

For asynchronous processing, the SDP Core Service gives user the choice to use either the Event Broker or Scheduled Jobs.

The configurations for this section are detailed in the Event Broker and Scheduler Configurations of the 1.x to 2.x Migration Guide.

Multi-tenancy Configuration​

The configurations for this section are detailed in General Environment Variables of the 1.x to 2.x Migration Guide.

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-compliant ed25519 private key 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. For more details, refer to the Stellar accounts configuration section of 1.x to 2.x Migration Guide.

  • DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE - 🔑 A Stellar-compliant ed25519 private key 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 create channel accounts.
  • DISTRIBUTION_SEED - 🔑 The private key of the HOST's Stellar distribution account, used to create channel accounts.

Event Broker Configuration​

If an Event Broker is used for asynchronous processing, the TSS will need to be configured to use it. For more details, refer to the Event Broker and Scheduler Configurations of the 1.x to 2.x Migration Guide.

  • EVENT_BROKER_TYPE - The type of event broker to use. Options: "KAFKA", "NONE". Default: "KAFKA".
  • BROKER_URLS - List of Message Broker URLs comma-separated.
  • CONSUMER_GROUP_ID - Message Broker Consumer Group ID.
  • KAFKA_SASL_USERNAME - 🔑 Kafka SASL Username.
  • KAFKA_SASL_PASSWORD - 🔑 Kafka SASL Password.
  • KAFKA_SECURITY_PROTOCOL - Kafka Security Protocol. Options: PLAINTEXT, SASL_PLAINTEXT, SASL_SSL, SSL.
  • KAFKA_SSL_ACCESS_CERTIFICATE - 🔑 Kafka SSL Access Certificate in PEM format that matches with the Kafka Access Key.
  • KAFKA_SSL_ACCESS_KEY - 🔑 The Kafka Access Key (keystore) in PEM format.

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​