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
/// # Gas Handler Interface
///
/// This module provides the interface for the gas handler contract.
use soroban_sdk::{contractclient, symbol_short, Address, Env, Symbol};
pub const HANDLER_OWNER_KEY: Symbol = symbol_short!("owner");
#[contractclient(name = "GasHandlerClient")]
pub trait GasHandlerInterface {
/// Initializes the gas handler contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `owner` - The address that will own the contract
///
/// # Returns
///
/// Returns `Ok(())` if successful, or an error if the owner is already set
fn __constructor(env: &Env, owner: Address) -> Result<(), crate::errors::Error>;
/// Verifies that the caller is the owner
///
/// # Returns
///
/// Returns `Ok(())` if the caller is the owner, or an error otherwise
fn only_owner(env: &Env) -> Result<(), crate::errors::Error>;
/// Retrieves the owner address
///
/// # Arguments
///
/// * `env` - The Soroban environment
///
/// # Returns
///
/// Returns the owner address, or an error if not set
fn get_owner(env: &Env) -> Result<Address, crate::errors::Error>;
/// Processes gas refunds for a relayer
///
/// This function transfers gas tokens from the client contract to the relayer as a refund
/// for processing a cross-chain message. It validates the gas amount, checks authorization
/// and balance, and transfers the gas tokens to the relayer.
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address that initiated the cross-chain message
/// * `relayer` - The relayer address to receive the gas refund
/// * `gas_amount` - The gas amount to refund
///
/// # Returns
///
/// Returns `true` if gas refund processing was successful or skipped
///
/// # Panics
///
/// Panics if:
/// - The gas amount exceeds the maximum gas amount
/// - The gas amount is not authorized
/// - The client contract has insufficient balance
fn process_gas_refund(
env: &Env,
client_contract: Address,
relayer: Address,
gas_amount: u64,
) -> bool;
/// Sets the maximum gas amount for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being refunded for gas
/// * `max_gas_amount` - The maximum gas amount allowed
///
/// # Returns
///
/// Returns `Ok(())` if successful, or an error if the caller is not the owner
fn set_max_gas_amount(
env: &Env,
client_contract: Address,
max_gas_amount: u64,
) -> Result<(), crate::errors::Error>;
/// Retrieves the maximum gas amount for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being refunded for gas
///
/// # Returns
///
/// Returns the maximum gas amount, or 0 if not set
fn get_max_gas_amount(env: &Env, client_contract: Address) -> u64;
/// Sets the gas token contract for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being refunded for gas
/// * `token_contract` - The token contract address for gas refunds
///
/// # Returns
///
/// Returns `Ok(())` if successful, or an error if the caller is not the owner
fn set_token_contract(
env: &Env,
client_contract: Address,
token_contract: Address,
) -> Result<(), crate::errors::Error>;
/// Retrieves the gas token contract for a client contract
///
/// # Arguments
///
/// * `env` - The Soroban environment
/// * `client_contract` - The client contract address being refunded for gas
///
/// # Returns
///
/// Returns the gas token contract address
///
/// # Panics
///
/// Panics if the gas token contract is not set for the client contract.
fn get_token_contract(env: &Env, client_contract: Address) -> Address;
}