docs: add docs to contract interfaces

contracts/stellar-axelar-gas-service/src/interface.rs

@@ -14,22 +14,18 @@ pub trait AxelarGasServiceInterface: OperatableInterface {
     ///
     /// # Arguments
     /// * `sender` - The address initiating the gas payment. It's the address that sent the cross-chain message via the `axelar_gateway`.
-    /// * `destination_chain` - The name of the destination chain where the transaction will be executed.
-    /// * `destination_address` - The address on the destination chain where the transaction will be executed.
-    /// * `payload` - The payload data associated with the transaction.
-    /// * `spender` - The address of the spender paying for the gas. Might differ from the `sender`.
+    /// * `destination_chain` - The destination chain for the message.
+    /// * `destination_address` - The destination contract address for the message.
+    /// * `payload` - The payload data associated with the message.
+    /// * `spender` - The address of the spender paying for the gas. Might differ from the `sender`. Excess gas will be refunded to this address.
     /// * `token` - The token used to pay for the gas, including the address and amount.
     /// * `metadata` - Additional metadata associated with the gas payment.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::InvalidAmount`: If the token amount is zero or negative.
-    /// - Any error propagated from the token transfer operation.
+    /// - [`ContractError::InvalidAmount`]: If the token amount is zero or negative.
     ///
     /// # Authorization
-    /// - The `spender` address must authenticate.
+    /// - The `spender` address must authorize the token transfer to the gas service.
     fn pay_gas(
         env: Env,
         sender: Address,
@@ -47,20 +43,16 @@ pub trait AxelarGasServiceInterface: OperatableInterface {
     /// e.g. the `sender` is a contract, but the `spender` can be the user signing the transaction.
     ///
     /// # Arguments
-    /// * `sender` - The address of the sender initiating the gas addition. It's the address that sent the cross-chain message via the `axelar_gateway`.
+    /// * `sender` - The address that sent the cross-chain message.
     /// * `message_id` - The identifier of the message for which gas is being added.
     /// * `spender` - The address of the spender paying for the gas.
     /// * `token` - The token used to pay for the gas, including the address and amount.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::InvalidAmount`: If the token amount is zero or negative.
-    /// - Any error propagated from the token transfer operation.
+    /// - [`ContractError::InvalidAmount`]: If the token amount is zero or negative.
     ///
     /// # Authorization
-    /// - The `spender` address must authenticate.
+    /// - The `spender` address must authorize.
     fn add_gas(
         env: Env,
         sender: Address,
@@ -74,19 +66,15 @@ pub trait AxelarGasServiceInterface: OperatableInterface {
     /// Allows the `gas_collector` to collect accumulated fees from the contract.
     ///
     /// # Arguments
-    /// * `receiver` - The address of the receiver to whom the collected fees will be transferred.
-    /// * `token` - The token used for the fee collection, including the address and amount.
-    ///
-    /// # Returns
-    /// - `Ok(())`
+    /// * `receiver` - The address that will receive the collected feeds.
+    /// * `token` - The token address and amount for the fee collection.
     ///
     /// # Errors
-    /// - `ContractError::InvalidAmount`: If the token amount is zero or negative.
-    /// - `ContractError::InsufficientBalance`: If the contract's token balance is insufficient to cover the transfer.
-    /// - Any error propagated from the token transfer operation.
+    /// - [`ContractError::InvalidAmount`]: If the token amount is zero or negative.
+    /// - [`ContractError::InsufficientBalance`]: If the contract's token balance is insufficient to cover the transfer.
     ///
     /// # Authorization
-    /// - The gas collector must authenticate.
+    /// - The `operator` must authorize.
     fn collect_fees(env: Env, receiver: Address, token: Token) -> Result<(), ContractError>;
 
     /// Refunds gas payment to the specified receiver in relation to a specific cross-chain message.
@@ -96,13 +84,7 @@ pub trait AxelarGasServiceInterface: OperatableInterface {
     /// * `receiver` - The address of the receiver to whom the gas fees will be refunded.
     /// * `token` - The token used for the refund, including the address and amount.
     ///
-    /// # Returns
-    /// - `Ok(())`: Returns `Ok` if the refund is successful.
-    ///
-    /// # Errors
-    /// - Any error propagated from the token transfer operation.
-    ///
     /// # Authorization
-    /// - The `gas_collector` must authenticate.
+    /// - The `operator` must authorize.
     fn refund(env: Env, message_id: String, receiver: Address, token: Token);
 }

contracts/stellar-axelar-gateway/src/interface.rs

@@ -9,6 +9,15 @@ use crate::AxelarGatewayMessagingInterface;
 pub trait AxelarGatewayInterface:
     AxelarGatewayMessagingInterface + UpgradableInterface + OwnableInterface + OperatableInterface
 {
+    /// Returns the domain separator.
+    fn domain_separator(env: &Env) -> BytesN<32>;
+
+    /// Returns the number of epochs that previous signers are retained for after rotations.
+    fn previous_signers_retention(env: &Env) -> u64;
+
+    /// Returns the minimum delay between rotations.
+    fn minimum_rotation_delay(env: &Env) -> u64;
+
     /// Approves a collection of messages with the provided proof.
     ///
     /// This function allows the approval of multiple messages using a cryptographic proof.
@@ -19,38 +28,30 @@ pub trait AxelarGatewayInterface:
     /// * `messages` - A vector of messages to be approved.
     /// * `proof` - The cryptographic proof used to validate the approval.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::EmptyMessages`: If the provided messages vector is empty.
-    /// - Any error propagated from `auth::validate_proof`.
+    /// - [`ContractError::EmptyMessages`]: If the provided messages vector is empty.
+    /// - Any error from `auth::validate_proof` due to an invalid proof.
     fn approve_messages(
         env: &Env,
         messages: Vec<Message>,
         proof: Proof,
     ) -> Result<(), ContractError>;
 
-    /// Rotates the signers for the contract.
+    /// Rotates to `signers` if the `proof` is valid.
     ///
-    /// This function allows the rotation of signers for the contract.
-    /// It validates the provided proof and ensures that the signers are the latest.
     /// If `bypass_rotation_delay` is set to true, the `operator` must authorize the rotation.
     ///
     /// # Arguments
     /// * `signers` - The new set of weighted signers to be rotated in.
     /// * `proof` - The cryptographic proof used to validate the rotation.
     /// * `bypass_rotation_delay` - A boolean indicating whether to bypass the rotation delay.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::NotLatestSigners`: If the provided signers are not the latest and `bypass_rotation_delay` is false.
-    /// - Any error propagated from `auth::validate_proof`.
+    /// - [`ContractError::NotLatestSigners`]: If the provided signers are not the latest and `bypass_rotation_delay` is false.
+    /// - Any error from `auth::validate_proof` due to invalid proof.
     ///
     /// # Authorization
-    /// - The `operator` must authenticate if `bypass_rotation_delay` is true.
+    /// - The `operator` must authorize if `bypass_rotation_delay` is true.
     fn rotate_signers(
         env: &Env,
         signers: WeightedSigners,

contracts/stellar-axelar-operators/Cargo.toml

@@ -10,9 +10,11 @@ publish = true
 crate-type = ["cdylib", "rlib"]
 
 [features]
+library = [] # Only export the contract interface
 testutils = ["stellar-axelar-std/testutils"]
 
 [dependencies]
+cfg-if = { workspace = true }
 soroban-sdk = { workspace = true }
 stellar-axelar-std = { workspace = true }
 

contracts/stellar-axelar-operators/src/interface.rs

@@ -1,48 +1,45 @@
 use soroban_sdk::{contractclient, Address, Env, Symbol, Val, Vec};
+use stellar_axelar_std::interfaces::OwnableInterface;
 
 use crate::error::ContractError;
 
 #[allow(dead_code)]
 #[contractclient(name = "AxelarOperatorsClient")]
-pub trait AxelarOperatorsInterface {
+pub trait AxelarOperatorsInterface: OwnableInterface {
     /// Return whether specified account is an operator.
     fn is_operator(env: Env, account: Address) -> bool;
 
     /// Add an address as an operator.
     ///
-    /// The operator is authorized to execute specific functions (e.g. setting flow limits) for a contract.
+    /// The operator is authorized to execute any third party contract via this contract.
+    /// An app can give a privileged role to this contract, which can then allow multiple operators
+    /// to call it, e.g. `refund` on the gas service.
     ///
     /// # Arguments
     /// * `account` - The address to be added as an operator.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::OperatorAlreadyAdded`: If the specified account is already an operator.
+    /// - [`ContractError::OperatorAlreadyAdded`]: If the specified account is already an operator.
     ///
     /// # Authorization
-    /// - Must be called by [`Self::owner`].
+    /// - [`Self::owner`] must authorize.
     fn add_operator(env: Env, account: Address) -> Result<(), ContractError>;
 
     /// Remove an address as an operator.
     ///
-    /// The address is no longer authorized to execute specific operator functions (e.g. setting flow limits) for a contract.
+    /// The address is no longer authorized to execute apps via this contract.
     ///
     /// # Arguments
     /// * `account` - The address to be removed as an operator.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
     /// # Errors
-    /// - `ContractError::NotAnOperator`: If the specified account is not an operator.
+    /// - [`ContractError::NotAnOperator`]: If the specified account is not an operator.
     ///
     /// # Authorization
-    /// - Must be called by [`Self::owner`].
+    ///  - [`Self::owner`] must authorize.
     fn remove_operator(env: Env, account: Address) -> Result<(), ContractError>;
 
-    /// Execute a function on a contract as an operator.
+    /// Execute a function on any contract as the operators contract.
     ///
     /// # Arguments
     /// * `operator` - The address of the operator executing the function.
@@ -54,11 +51,10 @@
     /// - `Ok(Val)`: Returns the result of the function execution.
     ///
     /// # Errors
-    /// - `ContractError::NotAnOperator`: If the specified operator is not authorized.
-    /// - Any error propagated from `env.invoke_contract`.
+    /// - [`ContractError::NotAnOperator`]: If the specified operator is not authorized.
     ///
     /// # Authorization
-    /// - The `operator` must authenticate.
+    /// - The `operator` must authorize.
     fn execute(
         env: Env,
         operator: Address,

contracts/stellar-axelar-operators/src/lib.rs

@@ -3,14 +3,21 @@
 #[cfg(any(test, feature = "testutils"))]
 extern crate std;
 
-pub mod event;
-mod storage_types;
-
-mod contract;
 pub mod error;
-pub mod interface;
 
-pub use contract::{AxelarOperators, AxelarOperatorsClient};
+mod interface;
 
 #[cfg(test)]
 mod tests;
+
+cfg_if::cfg_if! {
+    if #[cfg(all(feature = "library", not(feature = "testutils")))] {
+        pub use interface::{AxelarOperatorsClient, AxelarOperatorsInterface};
+    } else {
+        pub mod event;
+        mod storage_types;
+        mod contract;
+
+        pub use contract::{AxelarOperators, AxelarOperatorsClient};
+    }
+}

contracts/stellar-example/src/interface.rs

@@ -1,9 +1,10 @@
 use soroban_sdk::{Address, Bytes, BytesN, Env, String};
+use stellar_axelar_gateway::executable::AxelarExecutableInterface;
 use stellar_axelar_std::types::Token;
 
 use crate::contract::ExampleError;
 
-pub trait ExampleInterface {
+pub trait ExampleInterface: AxelarExecutableInterface {
     /// Retrieves the address of the gas service.
     fn gas_service(env: &Env) -> Address;
 
@@ -18,14 +19,8 @@ pub trait ExampleInterface {
     /// * `message` - The message to be sent.
     /// * `gas_token` - The token used to pay for gas during the transaction.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
-    /// # Errors
-    /// - Any error propagated from the `pay_gas` or `call_contract` functions.
-    ///
     /// # Authorization
-    /// - The `caller` address must authenticate.
+    /// - The `caller` address must authorize.
     fn send(
         env: &Env,
         caller: Address,
@@ -48,14 +43,8 @@ pub trait ExampleInterface {
     /// * `recipient` - An optional recipient address on the destination chain.
     /// * `gas_token` - The token used to pay for gas during the transaction.
     ///
-    /// # Returns
-    /// - `Ok(())`
-    ///
-    /// # Errors
-    /// - Any errors propagated during the `interchain_transfer` function.
-    ///
     /// # Authorization
-    /// - The `caller` address must authenticate.
+    /// - The `caller` address must authorize.
     fn send_token(
         env: &Env,
         caller: Address,