Skip to main content

IGatewayClientV1

fedimint_gw_client

Trait IGatewayClientV1 

Source 
pub trait IGatewayClientV1:
    Debug
    + Send
    + Sync {
    // Required methods
    fn verify_preimage_authentication<'life0, 'async_trait>(
        &'life0 self,
        payment_hash: Hash,
        preimage_auth: Hash,
        contract: OutgoingContractAccount,
    ) -> Pin<Box<dyn Future<Output = Result<(), OutgoingPaymentError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn verify_pruned_invoice<'life0, 'async_trait>(
        &'life0 self,
        payment_data: PaymentData,
    ) -> Pin<Box<dyn Future<Output = Result<(), GatewayClientV1Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_routing_fees<'life0, 'async_trait>(
        &'life0 self,
        federation_id: FederationId,
    ) -> Pin<Box<dyn Future<Output = Option<RoutingFees>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn begin_fresh_receive<'life0, 'async_trait>(
        &'life0 self,
        federation_id: FederationId,
    ) -> Pin<Box<dyn Future<Output = Option<PaymentPolicyGuard>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_client<'life0, 'life1, 'async_trait>(
        &'life0 self,
        federation_id: &'life1 FederationId,
    ) -> Pin<Box<dyn Future<Output = Option<Spanned<ClientHandleArc>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn get_client_for_invoice<'life0, 'async_trait>(
        &'life0 self,
        payment_data: PaymentData,
    ) -> Pin<Box<dyn Future<Output = Option<Spanned<ClientHandleArc>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pay<'life0, 'async_trait>(
        &'life0 self,
        payment_data: PaymentData,
        max_delay: u64,
        max_fee: Amount,
    ) -> Pin<Box<dyn Future<Output = Result<PayInvoiceResponse, LightningRpcError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn outbound_payment_exists<'life0, 'async_trait>(
        &'life0 self,
        payment_hash: Hash,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn complete_htlc<'life0, 'async_trait>(
        &'life0 self,
        htlc_response: InterceptPaymentResponse,
    ) -> Pin<Box<dyn Future<Output = Result<(), LightningRpcError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn is_lnv2_direct_swap<'life0, 'async_trait>(
        &'life0 self,
        payment_hash: Hash,
        amount: Amount,
    ) -> Pin<Box<dyn Future<Output = Result<Option<(IncomingContract, ClientHandleArc)>, GatewayClientV1Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn claim_payment_image<'life0, 'life1, 'async_trait>(
        &'life0 self,
        payment_image: &'life1 PaymentImage,
        operation_id: OperationId,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
}
Expand description

An interface between module implementation and the general Gateway

To abstract away and decouple the core gateway from the modules, the interface between them is expressed as a trait. The gateway handles operations that require Lightning node access or database access.

Required Methods§

Source

fn verify_preimage_authentication<'life0, 'async_trait>( &'life0 self, payment_hash: Hash, preimage_auth: Hash, contract: OutgoingContractAccount, ) -> Pin<Box<dyn Future<Output = Result<(), OutgoingPaymentError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Verifies that the supplied preimage_auth is the same as the preimage_auth that initiated the payment.

If it is not, then this will return an error because this client is not authorized to receive the preimage.

Source

fn verify_pruned_invoice<'life0, 'async_trait>( &'life0 self, payment_data: PaymentData, ) -> Pin<Box<dyn Future<Output = Result<(), GatewayClientV1Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Verify that the lightning node supports private payments if a pruned invoice is supplied.

§Errors

Fails with a GatewayClientV1Error if the invoice is pruned and the gateway cannot pay it.

Source

fn get_routing_fees<'life0, 'async_trait>( &'life0 self, federation_id: FederationId, ) -> Pin<Box<dyn Future<Output = Option<RoutingFees>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Retrieves the federation’s routing fees from the federation’s config.

Source

fn begin_fresh_receive<'life0, 'async_trait>( &'life0 self, federation_id: FederationId, ) -> Pin<Box<dyn Future<Output = Option<PaymentPolicyGuard>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Admits a fresh incoming payment for the clients of federation_id when the operator’s receive policy allows one, or answers None when receives are disabled.

The returned guard must be held until the funding operation exists. That is what makes disabling atomic: a policy change waits for the guards outstanding when it runs, so a payment admitted here always funds, and none is admitted once the change has returned.

Source

fn get_client<'life0, 'life1, 'async_trait>( &'life0 self, federation_id: &'life1 FederationId, ) -> Pin<Box<dyn Future<Output = Option<Spanned<ClientHandleArc>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieve a client given a federation ID, used for swapping ecash between federations.

Source

fn get_client_for_invoice<'life0, 'async_trait>( &'life0 self, payment_data: PaymentData, ) -> Pin<Box<dyn Future<Output = Option<Spanned<ClientHandleArc>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Source

fn pay<'life0, 'async_trait>( &'life0 self, payment_data: PaymentData, max_delay: u64, max_fee: Amount, ) -> Pin<Box<dyn Future<Output = Result<PayInvoiceResponse, LightningRpcError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Pay a Lightning invoice using the gateway’s lightning node.

Source

fn outbound_payment_exists<'life0, 'async_trait>( &'life0 self, payment_hash: Hash, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Returns whether the gateway’s Lightning node has any record of an outbound payment for payment_hash, whatever its state.

The pay state machine consults this when it resumes after a restart: a payment the node already knows was dispatched before the crash and must be resolved through IGatewayClientV1::pay’s idempotent resume path rather than cancelled by pre-dispatch checks. A wrong false cancels a contract whose payment may still settle, so implementations must absorb transient node failures and only answer once the node’s payment store could actually be consulted.

Source

fn complete_htlc<'life0, 'async_trait>( &'life0 self, htlc_response: InterceptPaymentResponse, ) -> Pin<Box<dyn Future<Output = Result<(), LightningRpcError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Uses the gateway’s lightning node to complete (settle or cancel) a previously intercepted HTLC.

By the time the gateway settles the upstream HTLC it has already funded the incoming contract, so a transient failure here must not strand it out of pocket. Implementations must absorb and retry every transient node or connectivity failure, returning Err only when Lightning has reached a permanent state that makes the requested outcome impossible. The future may block while retrying and must remain cancellation-safe. The completion state machine persists any returned error as a terminal failure.

Source

fn is_lnv2_direct_swap<'life0, 'async_trait>( &'life0 self, payment_hash: Hash, amount: Amount, ) -> Pin<Box<dyn Future<Output = Result<Option<(IncomingContract, ClientHandleArc)>, GatewayClientV1Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Check if the gateway satisfy the LNv1 payment by funding an LNv2 IncomingContract

§Errors

Fails with a GatewayClientV1Error if the gateway holds no LNv2 incoming contract it can use for this payment. The pay state machine treats a failure like None and pays the invoice some other way.

Source

fn claim_payment_image<'life0, 'life1, 'async_trait>( &'life0 self, payment_image: &'life1 PaymentImage, operation_id: OperationId, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Claims the payment image for operation_id in the claim table shared with LNv2, returning false if another operation already claimed it.

Implementors§