Struct Gateway

pub struct Gateway {
    pub(crate) federation_manager: Arc<RwLock<FederationManager>>,
    pub(crate) lightning_builder: Arc<dyn LightningBuilder + Send + Sync>,
    pub(crate) gateway_config: Arc<RwLock<Option<GatewayConfiguration>>>,
    pub(crate) state: Arc<RwLock<GatewayState>>,
    pub(crate) client_builder: GatewayClientBuilder,
    pub(crate) gateway_db: Database,
    pub(crate) gateway_id: PublicKey,
    pub(crate) versioned_api: SafeUrl,
    pub(crate) listen: SocketAddr,
    pub(crate) lightning_module_mode: LightningModuleMode,
}

Fields

federation_manager: Arc<RwLock<FederationManager>>

The gateway’s federation manager.

lightning_builder: Arc<dyn LightningBuilder + Send + Sync>

Builder struct that allows the gateway to build a ILnRpcClient, which represents a connection to a lightning node.

gateway_config: Arc<RwLock<Option<GatewayConfiguration>>>

The gateway’s current configuration

state: Arc<RwLock<GatewayState>>

The current state of the Gateway.

client_builder: GatewayClientBuilder

Builder struct that allows the gateway to build a Fedimint client, which handles the communication with a federation.

gateway_db: Database

Database for Gateway metadata.

gateway_id: PublicKey

A public key representing the identity of the gateway. Private key is not used.

versioned_api: SafeUrl

The Gateway’s API URL.

listen: SocketAddr

The socket the gateway listens on.

lightning_module_mode: LightningModuleMode

The “module mode” of the gateway. Options are LNv1, LNv2, or All.

Implementations

impl Gateway

pub async fn new_with_custom_registry( lightning_builder: Arc<dyn LightningBuilder + Send + Sync>, client_builder: GatewayClientBuilder, listen: SocketAddr, api_addr: SafeUrl, cli_password: Option<String>, network: Option<Network>, fees: RoutingFees, num_route_hints: u32, gateway_db: Database, gateway_state: GatewayState, lightning_module_mode: LightningModuleMode, ) -> Result<Gateway>

Creates a new gateway but with a custom module registry provided inside client_builder. Currently only used for testing.

pub async fn new_with_default_modules() -> Result<Gateway>

Default function for creating a gateway with the Mint, Wallet, and Gateway modules.

pub(crate) async fn new( lightning_builder: Arc<dyn LightningBuilder + Send + Sync>, gateway_parameters: GatewayParameters, gateway_db: Database, client_builder: GatewayClientBuilder, gateway_state: GatewayState, ) -> Result<Gateway>

Helper function for creating a gateway from either new_with_default_modules or new_with_custom_registry.

pub(crate) async fn load_or_create_gateway_id( gateway_db: &Database, ) -> PublicKey

Returns a PublicKey that uniquely identifies the Gateway.

pub fn gateway_id(&self) -> PublicKey

pub fn versioned_api(&self) -> &SafeUrl

pub async fn clone_gateway_config(&self) -> Option<GatewayConfiguration>

pub(crate) async fn get_state(&self) -> GatewayState

pub async fn dump_database( dbtx: &mut DatabaseTransaction<'_>, prefix_names: Vec<String>, ) -> BTreeMap<String, Box<dyn Serialize + Send>>

Reads and serializes structures from the Gateway’s database for the purpose for serializing to JSON for inspection.

pub async fn run( self, tg: TaskGroup, runtime: Arc<Runtime>, ) -> Result<TaskShutdownToken>

Main entrypoint into the gateway that starts the client registration timer, loads the federation clients from the persisted config, begins listening for intercepted payments, and starts the webserver to service requests.

pub(crate) fn start_gateway( &self, task_group: &TaskGroup, runtime: Arc<Runtime>, )

Begins the task for listening for intercepted payments from the lightning node.

pub(crate) async fn route_lightning_payments<'a>( &'a self, handle: &TaskHandle, stream: RouteHtlcStream<'a>, ln_client: Arc<dyn ILnRpcClient>, ) -> ReceivePaymentStreamAction

Handles a stream of incoming payments from the lightning node after ensuring the gateway is properly configured. Awaits until the stream is closed, then returns with the appropriate action to take.

pub(crate) async fn is_shutting_down_safely(&self)

Polls the Gateway’s state waiting for it to shutdown so the thread processing payment requests can exit.

pub(crate) async fn handle_lightning_payment( &self, payment_request: InterceptPaymentRequest, lightning_context: &LightningContext, )

Handles an intercepted lightning payment. If the payment is part of an incoming payment to a federation, spawns a state machine and hands the payment off to it. Otherwise, forwards the payment to the next hop like a normal lightning node.

pub(crate) async fn try_handle_lightning_payment_lnv2( &self, htlc_request: &InterceptPaymentRequest, lightning_context: &LightningContext, ) -> Result<()>

Tries to handle a lightning payment using the LNv2 protocol. Returns Ok if the payment was handled, Err otherwise.

pub(crate) async fn try_handle_lightning_payment_ln_legacy( &self, htlc_request: &InterceptPaymentRequest, ) -> Result<()>

Tries to handle a lightning payment using the legacy lightning protocol. Returns Ok if the payment was handled, Err otherwise.

pub(crate) async fn forward_lightning_payment( htlc_request: InterceptPaymentRequest, lightning_context: &LightningContext, )

Forwards a lightning payment to the next hop like a normal lightning node. Only necessary for LNv1, since LNv2 uses hold invoices instead of HTLC interception for routing incoming payments.

pub(crate) async fn set_gateway_state(&self, state: GatewayState)

Helper function for atomically changing the Gateway’s internal state.

pub async fn handle_get_info(&self) -> AdminResult<GatewayInfo>

Returns information about the Gateway back to the client when requested via the webserver.

pub async fn handle_get_federation_config( &self, federation_id_or: Option<FederationId>, ) -> AdminResult<GatewayFedConfig>

If the Gateway is connected to the Lightning node, returns the ClientConfig for each federation that the Gateway is connected to.

pub async fn handle_address_msg( &self, payload: DepositAddressPayload, ) -> AdminResult<Address>

Returns a Bitcoin deposit on-chain address for pegging in Bitcoin for a specific connected federation.

pub async fn handle_withdraw_msg( &self, payload: WithdrawPayload, ) -> AdminResult<WithdrawResponse>

Returns a Bitcoin TXID from a peg-out transaction for a specific connected federation.

pub(crate) async fn handle_create_invoice_for_operator_msg( &self, payload: CreateInvoiceForOperatorPayload, ) -> AdminResult<Bolt11Invoice>

Creates an invoice that is directly payable to the gateway’s lightning node.

pub(crate) async fn handle_pay_invoice_for_operator_msg( &self, payload: PayInvoiceForOperatorPayload, ) -> AdminResult<Preimage>

Requests the gateway to pay an outgoing LN invoice using its own funds. Returns the payment hash’s preimage on success.

pub(crate) async fn handle_pay_invoice_msg( &self, payload: PayInvoicePayload, ) -> Result<Preimage>

Requests the gateway to pay an outgoing LN invoice on behalf of a Fedimint client. Returns the payment hash’s preimage on success.

pub async fn handle_connect_federation( &self, payload: ConnectFedPayload, ) -> AdminResult<FederationInfo>

Handles a connection request to join a new federation. The gateway will download the federation’s client configuration, construct a new client, registers, the gateway with the federation, and persists the necessary config to reconstruct the client when restarting the gateway.

pub async fn handle_leave_federation( &self, payload: LeaveFedPayload, ) -> AdminResult<FederationInfo>

Handle a request to have the Gateway leave a federation. The Gateway will request the federation to remove the registration record and the gateway will remove the configuration needed to construct the federation client.

pub async fn handle_backup_msg(&self, __arg1: BackupPayload) -> AdminResult<()>

Handles a request for the gateway to backup a connected federation’s ecash.

pub async fn handle_mnemonic_msg(&self) -> AdminResult<MnemonicResponse>

Handles an authenticated request for the gateway’s mnemonic. This also returns a vector of federations that are not using the mnemonic backup strategy.

pub async fn handle_set_configuration_msg( &self, __arg1: SetConfigurationPayload, ) -> AdminResult<()>

Handle a request to change a connected federation’s configuration or gateway metadata. If num_route_hints is changed, the Gateway will re-register with all connected federations. If per_federation_routing_fees is changed, the Gateway will only re-register with the specified federation.

pub async fn handle_get_ln_onchain_address_msg(&self) -> AdminResult<Address>

Generates an onchain address to fund the gateway’s lightning node.

pub async fn handle_open_channel_msg( &self, payload: OpenChannelPayload, ) -> AdminResult<Txid>

Instructs the Gateway’s Lightning node to open a channel to a peer specified by pubkey.

pub async fn handle_close_channels_with_peer_msg( &self, payload: CloseChannelsWithPeerPayload, ) -> AdminResult<CloseChannelsWithPeerResponse>

Instructs the Gateway’s Lightning node to close all channels with a peer specified by pubkey.

pub async fn handle_list_active_channels_msg( &self, ) -> AdminResult<Vec<ChannelInfo>>

Returns a list of Lightning network channels from the Gateway’s Lightning node.

pub async fn handle_send_onchain_msg( &self, payload: SendOnchainPayload, ) -> AdminResult<Txid>

Send funds from the gateway’s lightning node on-chain wallet.

pub async fn handle_get_balances_msg(&self) -> AdminResult<GatewayBalances>

Returns the ecash, lightning, and onchain balances for the gateway and the gateway’s lightning node.

pub async fn handle_spend_ecash_msg( &self, payload: SpendEcashPayload, ) -> AdminResult<SpendEcashResponse>

pub async fn handle_receive_ecash_msg( &self, payload: ReceiveEcashPayload, ) -> Result<ReceiveEcashResponse>

Handles a request to receive ecash into the gateway.

pub async fn handle_shutdown_msg( &self, task_group: TaskGroup, ) -> AdminResult<()>

Instructs the gateway to shutdown, but only after all incoming payments have been handlded.

pub async fn handle_payment_log_msg( &self, __arg1: PaymentLogPayload, ) -> AdminResult<PaymentLogResponse>

Queries the client log for payment events and returns to the user.

pub(crate) async fn register_federations( &self, gateway_config: &GatewayConfiguration, federations: &[(FederationId, FederationConfig)], register_task_group: &TaskGroup, )

Registers the gateway with each specified federation.

pub(crate) async fn get_gateway_configuration( gateway_db: Database, gateway_parameters: &GatewayParameters, ) -> Option<GatewayConfiguration>

This function will return a GatewayConfiguration one of two ways. To avoid conflicting configs, the below order is the order in which the gateway will respect configurations:

• GatewayConfiguration is read from the database.
• All cli or environment variables are set such that we can create a GatewayConfiguration

pub async fn select_client( &self, federation_id: FederationId, ) -> Result<Spanned<ClientHandleArc>, FederationNotConnected>

Retrieves a ClientHandleArc from the Gateway’s in memory structures that keep track of available clients, given a federation_id.

pub(crate) async fn load_or_generate_mnemonic( gateway_db: &Database, ) -> AdminResult<Mnemonic>

Loads a mnemonic from the database or generates a new one if the mnemonic does not exist. Before generating a new mnemonic, this function will check if a mnemonic has been provided in the environment variable and use that if provided.

pub(crate) async fn load_clients(&self) -> AdminResult<()>

Reads the connected federation client configs from the Gateway’s database and reconstructs the clients necessary for interacting with connection federations.

pub(crate) fn register_clients_timer(&self, task_group: &TaskGroup)

Legacy mechanism for registering the Gateway with connected federations. This will spawn a task that will re-register the Gateway with connected federations every 8.5 mins. Only registers the Gateway if it has successfully connected to the Lightning node, so that it can include route hints in the registration.

pub(crate) async fn check_lnv1_federation_network( client: &ClientHandleArc, network: Network, ) -> AdminResult<()>

Verifies that the supplied network matches the Bitcoin network in the connected client’s LNv1 configuration.

pub(crate) async fn check_lnv2_federation_network( client: &ClientHandleArc, network: Network, ) -> AdminResult<()>

Verifies that the supplied network matches the Bitcoin network in the connected client’s LNv2 configuration.

pub async fn get_lightning_context( &self, ) -> Result<LightningContext, LightningRpcError>

Checks the Gateway’s current state and returns the proper LightningContext if it is available. Sometimes the lightning node will not be connected and this will return an error.

pub async fn unannounce_from_all_federations(&self)

Iterates through all of the federations the gateway is registered with and requests to remove the registration record.

impl Gateway

pub(crate) async fn public_key_v2( &self, federation_id: &FederationId, ) -> Option<PublicKey>

Retrieves the PublicKey of the Gateway module for a given federation for LNv2. This is NOT the same as the gateway_id, it is different per-connected federation.

pub async fn routing_info_v2( &self, federation_id: &FederationId, ) -> Result<Option<RoutingInfo>>

Returns payment information that LNv2 clients can use to instruct this Gateway to pay an invoice or receive a payment.

pub(crate) async fn send_payment_v2( &self, payload: SendPaymentPayload, ) -> Result<Result<[u8; 32], Signature>>

Instructs this gateway to pay a Lightning network invoice via the LNv2 protocol.

pub(crate) async fn create_bolt11_invoice_v2( &self, payload: CreateBolt11InvoicePayload, ) -> Result<Bolt11Invoice>

For the LNv2 protocol, this will create an invoice by fetching it from the connected Lightning node, then save the payment hash so that incoming lightning payments can be matched as a receive attempt to a specific federation.

pub async fn create_invoice_via_lnrpc_v2( &self, payment_hash: Hash, amount: Amount, description: Bolt11InvoiceDescription, expiry_time: u32, ) -> Result<Bolt11Invoice, LightningRpcError>

Retrieves a BOLT11 invoice from the connected Lightning node with a specific payment_hash.

pub async fn get_registered_incoming_contract_and_client_v2( &self, payment_image: PaymentImage, amount_msats: u64, ) -> Result<(IncomingContract, ClientHandleArc)>

Retrieves the persisted CreateInvoicePayload from the database specified by the payment_hash and the ClientHandleArc specified by the payload’s federation_id.

pub(crate) fn is_running_lnv2(&self) -> bool

Helper function for determining if the gateway supports LNv2.

pub(crate) fn is_running_lnv1(&self) -> bool

Helper function for determining if the gateway supports LNv1.

Trait Implementations

impl Clone for Gateway

fn clone(&self) -> Gateway

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Gateway

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.