Gas Station reference

Use this page to understand the main deployment settings and runtime interfaces for the Gas Station Service. The example shows one possible configuration shape; your release package, database, secrets, and telemetry pipeline can differ.

This page applies to on-premise deployments only. Ripple manages the Gas Station Service for SaaS.

What this config controls

Gas Station is a background service that funds transaction fees for sponsored accounts on supported ledgers. It connects to the Ripple Custody API gateway, authenticates as a service caller registered in Keycloak, submits automated funding intents as system-signed intents, stores processing state in PostgreSQL, and exports telemetry when configured.

Migration from bot users

Earlier releases used a bot-user private key for automated funding intents. Gas Station now uses system-signed intents instead. Existing deployments must migrate before they upgrade, or automated funding stops. See Migrate from a bot user.

Migrate from a bot user

If you funded Gas Station with a bot-user private key in an earlier release, migrate to system-signed intents in this order so that funding does not stop:

Activate system-signed intents for the deployment. See System-signed intent configuration.
Register the Gas Station service caller in Keycloak and issue it a custody_roles claim. See Obtain a token for a service caller.
Create a policy with intentOrigin: "SystemSigned" that allows the service caller to submit v0_CreateTransactionOrder. See System-signed intents and policies.
Redeploy Gas Station with the service-caller credentials. Remove the PRIVATE_KEY environment variable and the gasStation.credentials.privateKeyKey value.
Confirm that new funding intents execute, then decommission the bot user.

Configuration fields

Configure the service through environment variables or deployment values, depending on how your release packages Gas Station.

The HMZ_FEATURE_GAS_STATION deployment flag controls whether the console displays the Gas station pages, including gas station creation.

Parameter	Description	Default	Required
`GATEWAY_SERVER_URL`	Ripple Custody API gateway URL.	-	Yes
Service-caller credentials	Client credentials for the Gas Station service caller registered in Keycloak. The exact parameters depend on your release package; contact your Customer Partner Engineer (CPE) for the specifics.	-	Yes
`POLLING_INTERVAL_MS`	Interval for checking pending transactions, in milliseconds.	`5000`	No
`MAX_RETRY_ATTEMPTS`	Maximum immediate retry attempts for failed funding.	`3`	No
`RETRY_INTERVAL_MINUTES`	Interval between queued retry attempts.	`5`	No
`FEE_SAFETY_MARGIN_PERCENT`	Safety margin added to estimated fees.	`10`	No
`POSTGRES_URL`	PostgreSQL connection string.	-	Yes
`LOG_LEVEL`	Logging verbosity. Possible values: `debug`, `info`, `warn`, `error`.	`info`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry collector endpoint.	-	No

Deployment values

The following fields show a possible values-file shape for the Gas Station Service:

Field	Description
`gasStation.enabled`	Turns on the Gas Station Service when the release package supports it.
`gasStation.gatewayUrl`	Ripple Custody API gateway URL.
`gasStation.pollingIntervalMs`	Polling interval in milliseconds.
`gasStation.maxRetryAttempts`	Maximum immediate retry attempts.
`gasStation.retryIntervalMinutes`	Queue retry interval in minutes.
`gasStation.feeSafetyMarginPercent`	Fee safety margin percentage.
`gasStation.database.*`	Database host, port, database name, username, and secret reference.
`gasStation.credentials.*`	Secret reference for the Gas Station service-caller (Keycloak client) credentials.
`gasStation.telemetry.*`	Telemetry enablement and OTLP endpoint.

If your release exposes Gas Station through component selection, include gas-station in harmonize.included_components.

Database reference

Gas Station uses PostgreSQL for event deduplication, retry tracking, sponsorship configuration, alert thresholds, and audit data.

Table	Purpose
`processed_event`	Event deduplication and distributed locking.
`failed_funding_job`	Failed funding attempts for queue-based retry.
`dead_letter_queue`	Permanently failed jobs requiring investigation.
`sponsor`	Sponsorship configuration.
`alert`	Low-balance alert thresholds.
`event`	Audit trail for configuration changes.

If you are using the shared Ripple Custody PostgreSQL instance, the Gas Station Service creates its own schema (gas_station) within the shared database. The database user must have CREATE SCHEMA privileges. See PostgreSQL configuration for details on schema isolation across components.

Health endpoints

Endpoint	Purpose
`/v1/health`	Liveness probe.
`/v1/ready`	Readiness probe.

Metrics and traces

Gas Station exports metrics and traces through OpenTelemetry when you configure telemetry.

Metric	Type	Description
`failed_jobs_queue_size`	Gauge	Number of jobs in the failed funding queue.
`processed_events_count`	Gauge	Number of processed event rows.
`sponsor_balance_<ticker>`	Gauge	Current balance of each sponsor account.
`funding_attempts_total{status, chain}`	Counter	Funding attempts by status and chain.
`events_processed_total{outcome}`	Counter	Events processed by outcome.
`retry_attempts_total{attempt}`	Counter	Retry attempts before success or failure.
`funding_duration_seconds`	Histogram	Time from event detection to funding completion.
`job_age_at_success_hours`	Histogram	Time jobs spend in the queue before success.
`api_latency_seconds{endpoint}`	Histogram	API latency by endpoint.

Constraints and relationships

Store the service-caller credentials in a Kubernetes secret or external secret-management system.
Point POSTGRES_URL to a PostgreSQL database or schema that the service can access.
Ensure GATEWAY_SERVER_URL resolves from the Gas Station runtime environment.
Configure telemetry fields only when your deployment has an OpenTelemetry collector.
Scope the Gas Station system-signed policy narrowly enough for funding operations.

Example

This example shows one possible Gas Station configuration shape:

harmonize:
  included_components:
    - gas-station

gasStation:
  enabled: true
  gatewayUrl: "https://gateway.example.com"
  pollingIntervalMs: 5000
  maxRetryAttempts: 3
  retryIntervalMinutes: 5
  feeSafetyMarginPercent: 10

  database:
    host: "postgres.example.com"
    port: 5432
    name: "gas_station"
    username: "gas_station_user"
    existingSecret: "gas-station-db-credentials"

  credentials:
    existingSecret: "gas-station-credentials"

  telemetry:
    enabled: true
    otlpEndpoint: "http://otel-collector:4317"