syntax = "proto3";

package gateway_lnrpc;

/*
 * GatewayLightning is a service that provides limited access and functionality
 * from a lightning node to Fedimint gateways
 */
service GatewayLightning {
  /* GetNodeInfo returns the public key and alias of the associated lightning node */
  rpc GetNodeInfo(EmptyRequest) returns (GetNodeInfoResponse) {}

  /* GetRouteHints returns the route hints to the associated lightning node */
  rpc GetRouteHints(GetRouteHintsRequest) returns (GetRouteHintsResponse) {}

  /*
   * PayInvoice attempts to pay an invoice using the associated lightning node
   */
  rpc PayInvoice(PayInvoiceRequest) returns (PayInvoiceResponse) {}

  /*
   * PayPrunedInvoice attempts to pay a pruned invoice, which is an invoice without a description, using the associated lightning node.
   */
  rpc PayPrunedInvoice(PayPrunedInvoiceRequest) returns (PayInvoiceResponse) {}

  /*
   * RouteHtlcs opens a bi-directional stream for the client to receive intercepted
   * HTLCs. `InterceptHtlcRequest` is sent from the server to alert the client that
   * an HTLC has been intercepted and needs to be processed. The client is expected
   * to response with `InterceptHtlcResponse` after the HTLC has been processed with
   * the appropriate action (Settle, Forward, Cancel).
   */
  rpc RouteHtlcs(EmptyRequest) returns (stream InterceptHtlcRequest) {}

  rpc CompleteHtlc(InterceptHtlcResponse) returns (EmptyResponse) {}

  rpc CreateInvoice(CreateInvoiceRequest) returns (CreateInvoiceResponse) {}

  /* Get a Bitcoin address that belongs to the underlying lightning node's wallet. */
  rpc GetFundingAddress(EmptyRequest) returns (GetFundingAddressResponse) {}

  /* Open a channel on the underlying lightning node. */
  rpc OpenChannel(OpenChannelRequest) returns (EmptyResponse) {}

  /* Close all channels with a given peer on the underlying lightning node. */
  rpc CloseChannelsWithPeer(CloseChannelsWithPeerRequest) returns (CloseChannelsWithPeerResponse) {}

  /* List all channels that are active and able to send and receive funds. */
  rpc ListActiveChannels(EmptyRequest) returns (ListActiveChannelsResponse) {}
}

message EmptyRequest {}

message EmptyResponse {}

message GetRouteHintsRequest {
  uint64 num_route_hints = 1;
}

message GetNodeInfoResponse {
  // The public key of the associated lightning node
  bytes pub_key = 1;

  // The alias of the lightning node
  string alias = 2;

  // The network the node is on. Valid values are "main" | "test" | "signet" | "regtest"
  string network = 3;

  // The best block height that the associated lightning node is aware of
  // If `synced_to_chain` is true, then the node is also fully synced to this height
  uint32 block_height = 4;

  // Whether the associated lightning node is fully synced up to `block_height`
  bool synced_to_chain = 5;
}

message PayInvoiceRequest {
  // Bolt11 invoice
  string invoice = 1;

  // The maximum delay, in blocks, that the payment route can be locked for
  uint64 max_delay = 2;

  // The maximum fee, in millisats, that will be paid as a lightning routing fee
  uint64 max_fee_msat = 3;

  // The hash of the payment
  bytes payment_hash = 4;
}

message PayPrunedInvoiceRequest {
  // A BOLT11 invoice without a description
  PrunedInvoice pruned_invoice = 1;

  // The maximum delay, in blocks, that the payment route can be locked for
  uint64 max_delay = 2;

  // The maximum fee, in millisats, that will be paid as a lightning routing fee
  uint64 max_fee_msat = 3;
}

message PrunedInvoice {
  // The amount in msats to be paid
  uint64 amount_msat = 1;

  // The receiver's public key
  bytes destination = 2;

  // The features the the receiver supports
  bytes destination_features = 3;

  // The hash of the preimage for this payment
  bytes payment_hash = 4;

  // The payment secret for this payment
  bytes payment_secret = 5;

  // Minimum CLTV delta for this payment
  uint64 min_final_cltv_delta = 6;
}

message PayInvoiceResponse {
  // The preimage of the invoice
  bytes preimage = 1;
}

message InterceptHtlcRequest {
  // The HTLC payment hash.
  // HTLCs corresponding to the same payment will have the same payment hash.
  bytes payment_hash = 1;

  // The incoming HTLC amount in millisatoshi.
  // This amount minus the `outgoing_amount_msat` is the fee paid for processing
  // this intercepted HTLC
  uint64 incoming_amount_msat = 2;

  // The outgoing HTLC amount in millisatoshi
  // This is the amount we should forward to the Federation if we successfully
  // process this intercepted HTLC
  uint64 outgoing_amount_msat = 3;

  // The incoming HTLC expiry
  // Determines block height when the node will automatically cancel and revert
  // the intercepted HTLC to sender if it is not settled.
  uint32 incoming_expiry = 4;

  // Reserved for getting more details about intercepted HTLC
  reserved 5 to 9;

  // The short channel id of the HTLC.
  // Use this value to confirm relevance of the intercepted HTLC
  optional uint64 short_channel_id = 10;

  // The id of the incoming channel
  uint64 incoming_chan_id = 12;

  // The index of the incoming htlc in the incoming channel
  uint64 htlc_id = 13;
}

message InterceptHtlcResponse {
  message Settle {
    // The preimage for settling an intercepted HTLC
    bytes preimage = 1;
  }

  message Cancel {
    // The reason for the cancellation of an intercepted HTLC
    string reason = 1;
  }

  message Forward {}

  oneof action {
    // Request to complete an intercepted HTLC with success result after
    // processing
    //
    // Send this request when the gateway successfully processed intercepted
    // HTLC GatewayLightning will settle/resolve the intercepted HTLC with
    // reason provided.
    Settle settle = 1;

    // Request to complete an intercepted HTLC with failure result after
    // processing
    //
    // Send this request when the gateway failed or canceled processing of
    // intercepted HTLC. GatewayLightning will fail/cancel the intercepted HTLC
    // with reason provided.
    Cancel cancel = 2;

    // Request to just forward the HTLC without failing or settling it.
    Forward forward = 3;
  }

  // The id of the incoming channel
  uint64 incoming_chan_id = 4;

  // The index of the incoming htlc in the incoming channel
  uint64 htlc_id = 5;

  // The HTLC payment hash.
  // HTLCs corresponding to the same payment will have the same payment hash.
  bytes payment_hash = 6;
}

message GetRouteHintsResponse {
  message RouteHintHop {
    // The node_id of the non-target end of the route.
    bytes src_node_id = 1;

    // The short_channel_id of this channel.
    uint64 short_channel_id = 2;

    // Flat routing fee in millisatoshis.
    uint32 base_msat = 3;

    // Liquidity-based routing fee in millionths of a routed amount.
    // In other words, 10000 is 1%.
    uint32 proportional_millionths = 4;

    // The difference in CLTV values between this node and the next node.
    uint32 cltv_expiry_delta = 5;

    // The minimum value, in msat, which must be relayed to the next hop.
    optional uint64 htlc_minimum_msat = 6;

    // The maximum value in msat available for routing with a single HTLC.
    optional uint64 htlc_maximum_msat = 7;
  }

  message RouteHint {
    // Hops that make up a route hint to the associated lightning node
    repeated RouteHintHop hops = 1;
  }

  // The route hints to the associated lightning node
  repeated RouteHint route_hints = 1;
}

message CreateInvoiceRequest {
  // The payment hash of the invoice being created.
  bytes payment_hash = 1;

  // The amount in millisatoshis of the invoice.
  uint64 amount_msat = 2;

  // The time in seconds this invoice is valid for.
  uint32 expiry_secs = 3;

  // A description or a description hash must be provided.
  oneof description {
    string direct = 4;

    bytes hash = 5;
  }
}

message CreateInvoiceResponse {
  string invoice = 1;
}

message GetFundingAddressResponse {
  // An address belonging to the lightning node's on-chain wallet.
  string address = 1;
}

message OpenChannelRequest {
  // The public key of the node we're opening a channel to.
  string pubkey = 1;

  // The host address of the node we're connecting to.
  string host = 4;

  // The capacity of the channel, in sats.
  uint64 channel_size_sats = 2;

  // The amount of sats that should be pushed to the
  // counterparty once the channel is opened.
  uint64 push_amount_sats = 3;
}

message CloseChannelsWithPeerRequest {
  // The public key of the node we're closing channels with.
  bytes pubkey = 1;
}

message CloseChannelsWithPeerResponse {
    // The number of channels that were closed.
    uint32 num_channels_closed = 1;
}

message ListActiveChannelsResponse {
  message ChannelInfo {
    // The pubkey of the lightning node that the channel is open with.
    string remote_pubkey = 1;

    // The total capacity of the channel, in sats.
    uint64 channel_size_sats = 2;

    // The amount of sats that the local node can send through the channel.
    uint64 outbound_liquidity_sats = 3;

    // The amount of sats that the local node can receive through the channel.
    uint64 inbound_liquidity_sats = 4;

    // The SCID of the channel.
    uint64 short_channel_id = 5;
  }

  // All channels on the node that are currently able to send and receive payments.
  repeated ChannelInfo channels = 1;
}