Builders - IBX Token Billing Mechanism

This page explains how the IBX token billing system works for Builders who sponsor their users' onchain transactions.

Overview

Within a given Builder's rpId (dApp domain name - e.g. app.ibexwallet.org), end-user onchain transactions are sponsored by the Builder's wallet using IBX tokens. This sponsorship covers gas and execution fees for permitted operations, ensuring a smooth user experience without requiring users to hold native gas tokens.

The Builder funds and manages the IBX balance that backs these sponsored operations. Each operation type has a configurable price in EUR, which is automatically converted to IBX tokens and charged to the Builder's billing wallet.

Billing Flow

The billing process is triggered automatically after a Safe operation is successfully executed:

Operation Execution : User's Safe operation is executed on-chain via the bundler
Billing Trigger : After successful execution, the billing service is automatically triggered
Price Lookup : System looks up the EUR price for the operation type
IBX Conversion : EUR price is converted to IBX using the current IBX/EUR exchange rate
Transaction Creation : A billing transaction is created with status PENDING
Token Transfer : IBX tokens are transferred from Builder's billing wallet to the billing destination
Status Updates : Transaction status is updated to SENT, then CONFIRMED after blockchain confirmation

Configuration Requirements

1. Billing Wallet

Each Builder must configure a billing wallet address. This wallet will be charged IBX tokens for sponsored operations.

⚠️ Note : If no billing wallet is configured, billing transactions will be created with status PENDING but no token transfer will occur. The operation will still succeed, but billing will be skipped.

2. IBX Price (EUR per IBX)

The IBX/EUR exchange rate is configured globally via the BILLING_IBX_PRICE environment variable. This rate is used to convert EUR prices to IBX amounts.

Formula: ibxAmount = priceEur / eurPerIbx

3. Operation Pricing

Each operation type can have a custom price in EUR, configured per Builder:

rpId : The Builder's rpId
operationType : The type of operation (e.g., TRANSFER_TOKEN, SWAP_FROM_QUOTE, ENABLE_RECOVERY)
priceEur : The price in EUR for this operation type

If no pricing is configured for an operation type, the billing amount defaults to 0 (free operation).

Billing Transaction Status

Each billing transaction progresses through the following statuses:

Status	Description
`PENDING`	Billing transaction created, awaiting token transfer. This occurs when: No billing wallet is configured Billing amount is 0 (free operation) Before the token transfer is initiated
`SENT`	Token transfer transaction has been submitted to the blockchain, awaiting confirmation
`CONFIRMED`	Token transfer transaction has been confirmed on the blockchain. Billing is complete.
`FAILED`	Billing transaction failed. Common reasons: Insufficient IBX balance in billing wallet Insufficient allowance (billing wallet must approve the billing executor to spend IBX tokens) IBX price not configured Transaction reverted on-chain

Token Transfer Mechanism

The billing system uses ERC20 transferFrom to move IBX tokens:

From : Builder's billing wallet
To : Billing destination address (configured via BILLING_DESTINATION environment variable)
Executor : Billing executor wallet (configured via BILLING_EXECUTOR private key)
Token : IBX token address (configured via BILLING_TOKEN environment variable)

⚠️ Important : The Builder's billing wallet must approve the billing executor address to spend IBX tokens. The required allowance must be at least equal to the total amount of IBX to be charged for operations.

Operation Types and Pricing

Common operation types that can be billed include:

TRANSFER_TOKEN : Token transfer operations
SWAP_FROM_QUOTE : Token swap operations
ENABLE_RECOVERY : Wallet recovery setup
CANCEL_RECOVERY : Wallet recovery cancellation
MONERIUM_CREATE_IBAN : IBAN creation
SIGN_MESSAGE : Message signing operations

Each Builder can configure custom prices for each operation type, allowing for flexible pricing models.

Error Handling

If billing fails, the following diagnostics are performed:

Balance Check : Verifies that the billing wallet has sufficient IBX balance
Allowance Check : Verifies that the billing executor has sufficient allowance to transfer tokens
Error Logging : Detailed error messages are stored for each billing transaction

Failed billing transactions do not prevent the user's operation from succeeding. The operation is executed on-chain, but billing is marked as FAILED for later resolution.

Best Practices

Monitor Balance : Regularly check your billing wallet's IBX balance to ensure sufficient funds
Set Allowance : Approve a sufficient allowance for the billing executor (consider setting a high allowance or using unlimited approval)
Configure Pricing : Set appropriate EUR prices for each operation type based on your cost structure
Monitor Transactions : Track billing transactions to identify any failed billing attempts
Handle Failures : Review failed billing transactions and resolve issues (insufficient balance, allowance, etc.)

Technical Implementation

The billing mechanism is implemented in src/services/billingService.ts:

BillingService.triggerBilling() : Main entry point, called after operation execution
BillingService.executeBillingTransaction() : Executes the ERC20 transferFrom transaction
BillingService.waitAndFinalizeBilling() : Waits for blockchain confirmation and updates status
BillingService.getBillingDiagnostics() : Provides balance and allowance diagnostics

Billing is triggered automatically in src/routes/v1/safesOperations.ts after a Safe operation is successfully executed via the bundler.

← Back to API Documentation