1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/// # Fee Handler Interface
///
/// This module provides the interface for the fee handler contract.
use soroban_sdk::{contractclient, symbol_short, Address, Env, Symbol};
use crate::errors::Error;
pub const HANDLER_OWNER_KEY: Symbol = symbol_short!("owner");
#[contractclient(name = "FeeHandlerClient")]
pub trait FeeHandlerInterface {
/// Initializes the fee handler contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `owner` - The address that will own the contract
fn __constructor(env: &Env, owner: Address) -> Result<(), Error>;
/// Processes fees for a cross-chain transaction
///
/// This function collects fees from the sender address if fees are enabled and configured.
/// It validates the fee amount, checks authorization and balance, and transfers the fee
/// to the fee handler contract.
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `sender_address` - The address that sent the cross-chain message
///
/// # Returns
///
/// Returns `true` if fee processing was successful or skipped
///
/// # Panics
///
/// Panics if:
/// - The source fee exceeds the maximum fee amount
/// - The fee amount is not authorized
/// - The sender has insufficient balance
fn process_fee(env: &Env, sender_address: Address) -> Result<bool, Error>;
/// Sets the fees offline status
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `status` - Whether fees should be offline (disabled)
fn set_fees_offline(env: &Env, status: bool) -> Result<(), Error>;
/// Checks if fees are offline
///
/// # Arguments
///
/// * `env` - The Soroban environment
///
/// # Returns
///
/// Returns `true` if fees are offline, `false` otherwise
fn is_fees_offline(env: &Env) -> bool;
/// Sets a custom source fee for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
/// * `amount` - The custom fee amount
fn set_custom_source_fee(env: &Env, client_contract: Address, amount: u64) -> Result<(), Error>;
/// Retrieves the custom source fee for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
///
/// # Returns
///
/// Returns the custom source fee amount, or 0 if not set
fn get_source_fee(env: &Env, client_contract: Address) -> u64;
/// Sets the maximum fee amount for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
/// * `amount` - The maximum fee amount
fn set_max_fee(env: &Env, client_contract: Address, amount: u64) -> Result<(), Error>;
/// Retrieves the maximum fee amount for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
///
/// # Returns
///
/// Returns the maximum fee amount, or 0 if not set
fn get_max_fee(env: &Env, client_contract: Address) -> u64;
/// Sets the fee token contract for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
/// * `contract` - The token contract address for fee payments
fn set_fee_token_contract(
env: &Env,
client_contract: Address,
contract: Address,
) -> Result<(), Error>;
/// Retrieves the fee token contract for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being processed for fees
///
/// # Returns
///
/// Returns the fee token contract address
///
/// # Panics
///
/// Panics if the fee token contract is not set for the client contract.
fn get_fee_token_contract(env: &Env, client_contract: Address) -> Result<Address, Error>;
}