vialabs_stellar_common/
fee.rs

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

vialabs_stellar_common/
fee.rs
