vialabs-stellar-common 0.1.10

use crate::storage::ChainDetails;
/// # Message Gateway V4 Interface
///
/// This module provides the interface for the message gateway contract.
use soroban_sdk::{contractclient, contracttype, Address, Bytes, BytesN, Env, Vec};

/// Signature structure for message validation
///
/// Contains the signature and public key used to verify message authenticity.
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct Signature {
  /// The signature bytes (64 bytes)
  pub signature: BytesN<64>,
  /// The public key bytes (32 bytes)
  pub public_key: BytesN<32>,
}

/// Request structure for processing messages
///
/// Contains all the information needed to process a cross-chain message, including
/// transaction details, sender/recipient information, message data, and signatures.
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct ProcessRequest {
  /// Transaction ID for tracking
  pub tx_id: u128,
  /// Chain ID where the message originated
  pub source_chain_id: u64,
  /// Chain ID of the destination chain
  pub destination_chain_id: u64,
  /// Sender address in bytes format
  pub sender: Bytes,
  /// Recipient address on this chain
  pub recipient: Address,
  /// Relayer address that submitted the message
  pub relayer: Address,
  /// ABI-encoded data for processing on-chain
  pub on_chain_data: Bytes,
  /// Optional off-chain data
  pub off_chain_data: Bytes,
  /// Signatures for message validation
  pub signatures: Vec<Signature>,
  /// Gas amount for the transaction
  pub gas: u64,
}

/// Request structure for sending messages
///
/// Contains all the information needed to send a cross-chain message.
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct SendRequest {
  /// Recipient address on the destination chain (in bytes format)
  pub recipient: Bytes,
  /// Chain ID of the destination chain
  pub destination_chain: u64,
  /// Data to send to the destination chain
  pub chain_data: Bytes,
  /// Number of confirmations required
  pub confirmations: u32,
}

/// Request structure for initializing universal gateway settings
///
/// Contains all the configuration needed to initialize the gateway with universal settings
/// in a single transaction.
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct InitializeUniversalSettingsRequest {
  /// List of chain signer addresses
  pub chain_signers: Vec<Address>,
  /// Number of chain signatures required
  pub chain_signers_required: u32,
  /// List of VIA signer addresses
  pub via_signers: Vec<Address>,
  /// Number of VIA signatures required
  pub via_signers_required: u32,
  /// List of relayer addresses
  pub relayers: Vec<Address>,
  /// Whether relayers are required
  pub relayers_required: bool,
  /// Whether the system is enabled
  pub system_enabled: bool,
  /// Address of the POS handler contract
  pub pos_handler: Address,
  /// Address of the fee handler contract
  pub fee_handler: Address,
  /// Address of the gas handler contract
  pub gas_handler: Address,
}

use crate::errors::Error;

/// Interface for the message gateway contract
///
/// This trait defines the interface for the gateway contract that routes messages between chains.
/// The gateway handles message validation, signature verification, and routing to the appropriate
/// destination chain.
///
/// ## Key Functions
///
/// - `send`: Sends a message to a destination chain
/// - `process`: Processes an incoming message from another chain
/// - `set_chain_signers`: Configures chain signers for message validation
/// - `set_via_signers`: Configures VIA signers for message validation
/// - `set_relayers`: Configures relayers for message submission
///
/// ## Usage
///
/// ```rust,no_run
/// use vialabs_stellar_common::message_gateway_v4::MessageGatewayV4Client;
/// use soroban_sdk::{Env, Address};
///
/// let gateway = MessageGatewayV4Client::new(&env, &gateway_address);
/// let tx_id = gateway.send(&send_request)?;
/// ```
#[contractclient(name = "MessageGatewayV4Client")]
pub trait MessageGatewayV4Interface {
  /// Initializes the gateway contract
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `chain_id` - The chain ID for this gateway
  /// * `deployer` - The address of the deployer (owner)
  /// * `message_prefix` - The message prefix for transaction IDs
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the owner is already set
  fn __constructor(
    env: &Env,
    chain_id: u64,
    deployer: Address,
    message_prefix: u128,
  ) -> Result<(), Error>;

  /// Sets the chain signers and required signature count
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `chain_signers` - Vector of chain signer addresses
  /// * `required` - Number of chain signatures required
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_chain_signers(env: &Env, chain_signers: Vec<Address>, required: u32) -> Result<(), Error>;

  /// Sets the VIA signers and required signature count
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `via_signers` - Vector of VIA signer addresses
  /// * `required` - Number of VIA signatures required
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_via_signers(env: &Env, via_signers: Vec<Address>, required: u32) -> Result<(), Error>;

  /// Sets the relayers and whether relayers are required
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `relayers` - Vector of relayer addresses
  /// * `required` - Whether relayers are required
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_relayers(env: &Env, relayers: Vec<Address>, required: bool) -> Result<(), Error>;

  /// Enables or disables the system
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `system_enabled` - Whether the system should be enabled
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_system_enabled(env: &Env, system_enabled: bool) -> Result<(), Error>;

  /// Checks if the system is enabled
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns `true` if the system is enabled, `false` otherwise
  fn is_system_enabled(env: &Env) -> bool;

  /// Initializes all gateway settings in a single transaction
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `request` - The initialization request containing all settings
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn initialize_universal_settings(
    env: &Env,
    request: InitializeUniversalSettingsRequest,
  ) -> Result<(), Error>;

  /// Sends a message to a destination chain
  ///
  /// This function processes a send request, validates the system is enabled,
  /// processes fees, generates a transaction ID, and emits a `SendRequested` event.
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `request` - The send request containing message data
  ///
  /// # Returns
  ///
  /// Returns the transaction ID of the sent message, or an error if:
  /// - The system is not enabled
  /// - The recipient address is zero
  /// - Fee processing fails
  fn send(env: &Env, request: SendRequest) -> Result<u128, Error>;

  /// Processes an incoming message from another chain
  ///
  /// This function validates the relayer, checks if the system is enabled, prevents
  /// duplicate processing, validates security layers (signatures), processes the message,
  /// and handles gas refunds.
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `request` - The process request containing message data
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if:
  /// - The relayer is not authorized
  /// - The system is not enabled
  /// - The transaction has already been processed
  /// - Security validation fails
  /// - Gas refund processing fails
  fn process(env: &Env, request: ProcessRequest) -> Result<(), Error>;

  /// Sets contract-specific relayers
  ///
  /// Only the contract itself can set its relayers. This allows contracts to manage
  /// their own authorized relayers.
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `contract` - The contract address (must match the caller)
  /// * `contract_relayers` - Vector of relayer addresses for this contract
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the contract itself
  fn set_contract_relayers(
    env: &Env,
    contract: Address,
    contract_relayers: Vec<Address>,
  ) -> Result<(), Error>;

  /// Sets project-specific signers
  ///
  /// Only the contract itself can set its project signers. This allows contracts to manage
  /// their own authorized signers for additional security layers.
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `contract` - The contract address (must match the caller)
  /// * `project_signers` - Vector of project signer addresses
  /// * `required` - Number of project signatures required
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the contract itself
  fn set_project_signers(
    env: &Env,
    contract: Address,
    project_signers: Vec<Address>,
    required: u32,
  ) -> Result<(), Error>;

  /// Sets the POS (Proof of Stake) handler contract address
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `pos_handler` - The POS handler contract address
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_pos_handler(env: &Env, pos_handler: Address) -> Result<(), Error>;

  /// Sets the fee handler contract address
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `fee_handler` - The fee handler contract address
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_fee_handler(env: &Env, fee_handler: Address) -> Result<(), Error>;

  /// Sets the gas handler contract address
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `gas_handler` - The gas handler contract address
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the caller is not the owner
  fn set_gas_handler(env: &Env, gas_handler: Address) -> Result<(), Error>;

  /// Gets the required signer counts for a recipient
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `recipient` - The recipient contract address
  ///
  /// # Returns
  ///
  /// Returns a tuple of (chain_signers_required, via_signers_required, project_signers_required)
  fn get_required_signer_counts(env: &Env, recipient: Address) -> (u32, u32, u32);

  /// Gets the gas handler contract address
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns the gas handler address, or `None` if not set
  fn get_gas_handler(env: &Env) -> Option<Address>;

  /// Gets the fee handler contract address
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns the fee handler address, or `None` if not set
  fn get_fee_handler(env: &Env) -> Option<Address>;

  /// Gets all VIA signers and the required count
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns a tuple of (via_signers, required_count)
  fn get_all_via_signers(env: &Env) -> (Vec<Address>, u32);

  /// Gets all chain signers and the required count
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns a tuple of (chain_signers, required_count)
  fn get_all_chain_signers(env: &Env) -> (Vec<Address>, u32);

  /// Gets all relayers and whether they are required
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns a tuple of (relayers, required)
  fn get_all_relayers(env: &Env) -> (Vec<Address>, bool);

  /// Gets all project signers for a contract and the required count
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `project_contract` - The project contract address
  ///
  /// # Returns
  ///
  /// Returns a tuple of (project_signers, required_count)
  fn get_all_project_signers(env: &Env, project_contract: Address) -> (Vec<Address>, u32);

  /// Gets all contract relayers for a contract
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `contract` - The contract address
  ///
  /// # Returns
  ///
  /// Returns a tuple of (contract_relayers, required)
  fn get_all_contract_relayers(env: &Env, contract: Address) -> (Vec<Address>, bool);

  /// Gets the next transaction ID
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns the next transaction ID
  fn get_next_tx_id(env: &Env) -> Result<u128, Error>;

  /// Gets the block tip
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns the block tip
  fn get_tip(env: &Env) -> u32;

  /// Gets the chain details including the chain ID and next transaction ID
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  ///
  /// # Returns
  ///
  /// Returns the chain details, or an error if not found
  fn get_chain_details(env: &Env) -> Result<ChainDetails, Error>;

  /// Checks if a relayer is authorized for a specific recipient contract
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `recipient` - The recipient contract address
  /// * `relayer` - The relayer address to check
  ///
  /// # Returns
  ///
  /// Returns `true` if the relayer is authorized, `false` otherwise
  fn is_relayer_authorized(env: &Env, recipient: Address, relayer: Address) -> bool;

  /// Processes the fee for a caller
  ///
  /// # Arguments
  ///
  /// * `env` - The Soroban environment
  /// * `caller_address` - The address of the caller
  ///
  /// # Returns
  ///
  /// Returns `Ok(())` on success, or an error if the fee processing fails
  fn process_fee(env: &Env, caller_address: Address) -> Result<(), Error>;
}