The Gas Station Service automatically funds transaction fees for sponsored accounts.
- Eliminates the need for end-user accounts to hold native tokens for gas fees.
- Supports account-level and domain-level sponsorship with subdomain inheritance.
- Works with Ethereum and EVM-compatible blockchains.
- Uses Just-in-Time (JIT) funding to transfer exact fee amounts when needed.
- Provides low-balance alerts to ensure sponsor accounts remain funded.
For operators: Gas Station removes friction from end-user transactions. Users don't need to acquire native tokens (e.g., ETH) just to pay fees—your organization sponsors those costs from designated accounts. This is essential for onboarding users who hold only stablecoins or other tokens.
For architects: The service integrates with existing Ripple Custody policies and intents. A dedicated bot user handles automated approvals, so you maintain full audit trails while eliminating manual fee-funding steps.
- Chain support: Ethereum and EVM-compatible chains only. Support for additional chains (Solana, XRPL) will be added in the future.
- Alert delivery: Low-balance alerts are delivered through your monitoring infrastructure. Configure alerts in your monitoring system (e.g., Grafana) to receive email or Slack notifications.
- Cross-chain sponsorship: A sponsor account can only fund accounts on the same blockchain network.
- Implementation approach: The current Gas Station implementation uses a mechanical funding approach: the service detects pending transactions and transfers gas fees from sponsor accounts to sponsored accounts as standard blockchain transactions. This release does not leverage native gas abstraction mechanisms such as ERC-4337 Paymasters. Support for native paymaster integration (including EIP-7701 Native Account Abstraction) will be added in the future.
Prerequisites: Familiarity with Ripple Custody accounts, domains, and transaction processing.
Further reading:
- Gas Station reference — On-premise deployment configuration
- Configure bot users — Set up bot users for automated operations
- Configure gas sponsorship — API guide with step-by-step instructions
The Gas Station Service is a background service that monitors transaction events and automatically funds accounts that lack sufficient native tokens to cover gas fees. When a sponsored account initiates a transaction, the service:
- Detects the pending transaction
- Estimates the required fee using a dry-run API call
- Transfers the exact amount (plus a safety margin) from the sponsor account
- Allows the original transaction to proceed
The Gas Station Service continuously monitors Ripple Custody for transaction events and automatically funds accounts that need gas. The following state diagram shows the decision logic at each step:
The Gas Station Service continuously polls Ripple Custody for transaction events using the /v1/domains/{domainId}/events endpoint. The polling interval is configurable (default: 5 seconds).
When an event is received, the service identifies outbound transactions by checking the orderReference field. Inbound transactions (where orderReference is null) are ignored.
The service retrieves the account's native token balance using /v1/domains/{domainId}/accounts/{accountId}/balances. If the account already has sufficient funds for the estimated fee, no sponsorship is needed.
For accounts with insufficient balance, the service looks up sponsorship configuration:
- Account-level first: Check if the specific account has a dedicated sponsor
- Domain-level second: Check if the account's domain has a sponsor (with optional subdomain inheritance)
If no sponsor is found, the transaction remains in "Preparing" state until funds are manually added.
The service uses Ripple Custody's dry-run API to calculate the exact gas amount required for the transaction. A configurable safety margin (default: 10%) is applied to account for fee volatility.
The service generates a transaction order payload to transfer the required gas amount from the sponsor account to the sponsored account. This payload is signed by the bot user's private key.
Before submitting, the service verifies the sponsor account has sufficient funds via a dry-run check. If the sponsor lacks funds, the funding transaction is not submitted.
After successful funding (or if funding fails due to low balance), the service checks the sponsor's remaining balance against configured alert thresholds. If the balance falls below the threshold, a notification is sent to the monitoring system.
The following diagram shows the complete API interactions between the Gas Station Service and Ripple Custody, including the specific endpoints called at each step:
The Gas Station Service supports flexible sponsorship configurations:
| Level | Description |
|---|---|
| Account-level | A sponsor account funds a specific list of accounts |
| Domain-level | A sponsor account funds all accounts within a domain |
| Subdomain inheritance | When includeSubDomains is enabled, sponsorship extends to all child domains |
When determining which sponsor to use, the service follows this hierarchy:
- Direct account sponsor: Check if the account has a dedicated sponsor
- Domain sponsor: Check if the account's domain has a sponsor
- Parent domain sponsor: If
includeSubDomainsis enabled, walk up the domain hierarchy
Each account can have only one sponsor. If you configure both account-level and domain-level sponsorship, the account-level sponsor takes precedence.
The Gas Station Service currently supports Ethereum and EVM-compatible blockchains:
| Chain type | Networks | Fee token |
|---|---|---|
| EVM-compatible | Ethereum, Polygon, Avalanche, BSC | ETH, MATIC, AVAX, BNB |
Support for additional chains (Solana, XRPL) will be added in the future.
The service uses Ripple Custody's dry-run API to estimate fees. All chain-specific fee calculations are handled automatically.
The Gas Station Service uses a dedicated bot user to sign and submit funding transactions automatically:
- No manual approval required: Once you configure the bot user with auto-approval policies, gas funding transactions are approved automatically without human intervention
- Full audit trail: All bot user actions are logged in the Ripple Custody intent system
- Secure key storage: The bot user's private key is stored in a secure vault (Kubernetes Secret or HashiCorp Vault)
If your organization adds additional approval requirements to the bot user's transactions, automatic sponsorship will be blocked. Funding transactions will require manual approval, defeating the purpose of the Gas Station.
Configure alert thresholds to receive notifications when sponsor account balances fall below specified levels.
When you configure a sponsor, you can set alert thresholds for each native token the sponsor holds:
| Field | Description |
|---|---|
| tickerId | The UUID of the native token to monitor (e.g., ETH, MATIC, AVAX) |
| amount | The balance threshold—alerts trigger when the balance falls to or below this amount |
You can configure multiple alert thresholds per sponsor, one for each token type.
The Gas Station Service checks the sponsor account balance after each funding transaction:
- After successfully funding a sponsored account, the service retrieves the sponsor's current balance
- For each configured alert threshold, it compares the current balance to the threshold amount
- If the balance is at or below the threshold, the service emits an alert event
Alerts are delivered through your monitoring infrastructure:
- Grafana integration: All alerts are sent to Grafana as log events and metrics
- Configure notifications: Set up Grafana alerting rules to receive notifications via email, Slack, PagerDuty, or other channels
- Monitor the metric:
gas_station_sponsor_low_balanceindicates when a sponsor balance is below threshold
Configure Grafana alerts to notify your operations team before sponsor accounts run out of funds. This ensures uninterrupted sponsorship for your users.
The service estimates transaction fees using the Ripple Custody dry-run API:
- Retrieve the original transaction intent
- Execute a dry-run to simulate the transaction
- Apply a configurable safety margin (default: 10%)
- Transfer the total amount to the sponsored account
The safety margin accounts for fee volatility between estimation and actual transaction broadcast.
The Gas Station Service implements a two-tier retry mechanism to handle transient failures:
For transient failures during event processing, the service performs immediate in-memory retries:
| Parameter | Value |
|---|---|
| Max attempts | 3 retries per operation |
| Backoff strategy | Exponential [1s, 2s, 4s] |
| Timeout | 10 seconds per attempt |
| Total time | ~17 seconds worst case |
When immediate retries are exhausted, jobs are persisted to a database queue for background processing:
| Parameter | Value |
|---|---|
| Retry interval | Fixed 5 minutes between cycles |
| Maximum age | 24 hours from job creation |
| Maximum retry count | 20 attempts |
Jobs exceeding these limits are moved to a dead letter queue for manual investigation.
The two-tier retry mechanism ensures that temporary failures (network issues, API timeouts) don't cause permanent funding failures while preventing infinite retry loops.
The Gas Station Service is designed to meet strict performance requirements:
| Metric | Target |
|---|---|
| End-to-end funding time | < 2 minutes |
| Polling interval | 5 seconds (configurable) |
| Happy path | ~35 seconds (including blockchain confirmation) |
| Worst case with retries | ~72 seconds (well within SLA) |
- Event polling interval: 5 seconds
- Dry-run API call: 1-3 seconds
- Funding transaction submission: 1-2 seconds
- Blockchain confirmation: varies by chain (EVM: 12-15s)
| Topic | Description |
|---|---|
| Gas Station reference | Configuration parameters and deployment options |
| Configure bot users | Set up bot users for automated operations |
| Configure gas sponsorship | Set up sponsor accounts and configure sponsorship rules |