Struct StellarTransactionValidator

pub struct StellarTransactionValidator;

Validator for Stellar transactions and policies

Implementations

impl StellarTransactionValidator

pub fn validate_fee_token_structure( fee_token: &str, ) -> Result<(), StellarTransactionValidationError>

Validate fee_token structure

Validates that the fee_token is in a valid format:

• “native” or “XLM” for native XLM
• “CODE:ISSUER” for classic assets (CODE: 1-12 chars, ISSUER: 56 chars starting with ‘G’)
• Contract address starting with “C” (56 chars) for Soroban contract tokens

pub fn validate_allowed_token( asset: &str, policy: &RelayerStellarPolicy, ) -> Result<(), StellarTransactionValidationError>

Validate that an asset identifier is in the allowed tokens list

pub fn validate_max_fee( fee: u64, policy: &RelayerStellarPolicy, ) -> Result<(), StellarTransactionValidationError>

Validate that a fee amount doesn’t exceed the maximum allowed fee

pub fn validate_token_max_fee( asset_id: &str, fee: u64, policy: &RelayerStellarPolicy, ) -> Result<(), StellarTransactionValidationError>

Validate that a specific token’s max_allowed_fee is not exceeded

pub fn extract_relayer_payments( envelope: &TransactionEnvelope, relayer_address: &str, ) -> Result<Vec<(String, u64)>, StellarTransactionValidationError>

Extract payment operations from a transaction envelope that pay to the relayer

Returns a vector of (asset_id, amount) tuples for payments to the relayer

pub fn validate_token_payment( envelope: &TransactionEnvelope, relayer_address: &str, expected_fee_token: &str, expected_fee_amount: u64, policy: &RelayerStellarPolicy, ) -> Result<(), StellarTransactionValidationError>

Validate token payment in transaction

Checks that:

1. Payment operation to relayer exists
2. Token is in allowed_tokens list
3. Payment amount matches expected fee (within tolerance)

pub async fn validate_sequence_number<P>( envelope: &TransactionEnvelope, provider: &P, ) -> Result<(), StellarTransactionValidationError>

where P: StellarProviderTrait + Send + Sync,

Validate sequence number

Validates that the transaction sequence number is valid for the source account. Note: The relayer will fee-bump this transaction, so the relayer’s sequence will be consumed. However, the inner transaction (user’s tx) must still have a valid sequence number.

The transaction sequence must be strictly greater than the account’s current sequence number. Future sequence numbers are allowed (user can queue transactions), but equal sequences are rejected.

pub async fn gasless_transaction_validation<P>( envelope: &TransactionEnvelope, relayer_address: &str, policy: &RelayerStellarPolicy, provider: &P, max_validity_duration: Option<Duration>, ) -> Result<(), StellarTransactionValidationError>

where P: StellarProviderTrait + Send + Sync,

Comprehensive validation for gasless transactions

Performs all security and policy validations on a transaction envelope before it’s processed for gasless execution.

This includes:

• Validating source account is not relayer
• Validating transaction type
• Validating operations don’t target relayer (except fee payment)
• Validating operations count
• Validating operation types
• Validating sequence number
• Validating transaction validity duration (if max_validity_duration is provided)

Arguments

• envelope - The transaction envelope to validate
• relayer_address - The relayer’s Stellar address
• policy - The relayer policy
• provider - Provider for Stellar RPC operations
• max_validity_duration - Optional maximum allowed transaction validity duration. If provided, validates that the transaction’s time bounds don’t exceed this duration. This protects against price fluctuations for user-paid fee transactions.

pub fn validate_time_bounds_not_expired( envelope: &TransactionEnvelope, ) -> Result<(), StellarTransactionValidationError>

Validate that transaction time bounds are valid and not expired

Checks that:

1. Time bounds exist (if envelope has them)
2. Current time is within the bounds (min_time <= now <= max_time)
3. Transaction has not expired (now <= max_time)

Arguments

• envelope - The transaction envelope to validate

Returns

Ok(()) if validation passes, StellarTransactionValidationError if validation fails

pub fn validate_transaction_validity_duration( envelope: &TransactionEnvelope, max_duration: Duration, ) -> Result<(), StellarTransactionValidationError>

Validate that transaction validity duration is within the maximum allowed time

This prevents price fluctuations and protects the relayer from losses. The transaction must have time bounds set and the validity duration must not exceed the maximum allowed duration.

Arguments

• envelope - The transaction envelope to validate
• max_duration - Maximum allowed validity duration

Returns

Ok(()) if validation passes, StellarTransactionValidationError if validation fails

pub async fn validate_user_fee_payment_transaction<P, D>( envelope: &TransactionEnvelope, relayer_address: &str, policy: &RelayerStellarPolicy, provider: &P, dex_service: &D, max_validity_duration: Option<Duration>, ) -> Result<(), StellarTransactionValidationError>

where P: StellarProviderTrait + Send + Sync, D: StellarDexServiceTrait + Send + Sync,

Comprehensive validation for user fee payment transactions

This function performs all validations required for user-paid fee transactions. It validates:

1. Transaction structure and operations (via gasless_transaction_validation)
2. Fee payment operations exist and are valid
3. Allowed token validation
4. Token max fee validation
5. Payment amount is sufficient (compares with required fee including margin)
6. Transaction validity duration (if max_validity_duration is provided)

This function is used by both fee-bump and sign-transaction flows. For sign-transaction flows, pass max_validity_duration to enforce time bounds. For fee-bump flows, pass None as transactions may not have time bounds set yet.

Arguments

• envelope - The transaction envelope to validate
• relayer_address - The relayer’s Stellar address
• policy - The relayer policy containing fee payment strategy and token settings
• provider - Provider for Stellar RPC operations
• dex_service - DEX service for fetching quotes to validate payment amounts
• max_validity_duration - Optional maximum allowed transaction validity duration. If provided, validates that the transaction’s time bounds don’t exceed this duration. This protects against price fluctuations for user-paid fee transactions when signing. Pass None for fee-bump flows where time bounds may not be set yet.

Returns

Ok(()) if validation passes, StellarTransactionValidationError if validation fails

pub async fn validate_user_token_balance<P>( envelope: &TransactionEnvelope, fee_token: &str, required_fee_amount: u64, provider: &P, ) -> Result<(), StellarTransactionValidationError>

where P: StellarProviderTrait + Send + Sync,

Validate that user has sufficient token balance to pay the transaction fee

This function checks that the user’s account has enough balance of the specified fee token to cover the required transaction fee. This prevents users from getting quotes or building transactions they cannot afford.

Arguments

• envelope - The transaction envelope to extract source account from
• fee_token - The token identifier (e.g., “native” or “USDC:GA5Z…”)
• required_fee_amount - The required fee amount in token’s smallest unit (stroops)
• provider - Provider for Stellar RPC operations to fetch balance

Returns

Ok(()) if validation passes, StellarTransactionValidationError if validation fails