loop/looprpc/server.proto

syntax = "proto3";

import "google/api/annotations.proto";

package looprpc;

service SwapServer {
    rpc LoopOutTerms (ServerLoopOutTermsRequest) returns (ServerLoopOutTerms);

    rpc NewLoopOutSwap (ServerLoopOutRequest) returns (ServerLoopOutResponse);

    rpc LoopOutPushPreimage (ServerLoopOutPushPreimageRequest)
        returns (ServerLoopOutPushPreimageResponse);

    rpc LoopOutQuote (ServerLoopOutQuoteRequest) returns (ServerLoopOutQuote);

    rpc LoopInTerms (ServerLoopInTermsRequest) returns (ServerLoopInTerms);

    rpc NewLoopInSwap (ServerLoopInRequest) returns (ServerLoopInResponse);

    rpc LoopInQuote (ServerLoopInQuoteRequest)
        returns (ServerLoopInQuoteResponse);

    rpc SubscribeLoopOutUpdates (SubscribeUpdatesRequest)
        returns (stream SubscribeLoopOutUpdatesResponse);

    rpc SubscribeLoopInUpdates (SubscribeUpdatesRequest)
        returns (stream SubscribeLoopInUpdatesResponse);
}

/**
This enum defines the protocol versions that clients may adhere to. Note that
this is not a flagged enum. If a particular protocol version adds a feature,
then in general all the preceding features are also supported. Exception to this
is when features get deprecated.
*/
enum ProtocolVersion {
    /// No protocol version reported at all.
    LEGACY = 0;

    /// Client may attempt to send the loop out payment in multiple parts.
    MULTI_LOOP_OUT = 1;

    /**
    Loop will use native segwit (P2WSH) htlcs by default, while externally
    published htlcs may use native (P2WSH) or nested (NP2WSH) segwit as well.
    */
    NATIVE_SEGWIT_LOOP_IN = 2;

    /*
    Once the on chain loop out htlc is confirmed, the client can push the swap
    preimage to the server to speed up claim of their off chain htlc (acquiring
    incoming liquidity more quickly than if the server waited for the on chain
    claim tx).
    */
    PREIMAGE_PUSH_LOOP_OUT = 3;

    // The client will propose a cltv expiry height for loop out.
    USER_EXPIRY_LOOP_OUT = 4;

    // The client will use the new v2 HTLC scripts.
    HTLC_V2 = 5;

    // The client creates a probe invoice so that the server can perform a
    // multi-path probe.
    MULTI_LOOP_IN = 6;
}

message ServerLoopOutRequest {
    bytes receiver_key = 1;

    bytes swap_hash = 2;

    uint64 amt = 3;

    /// The unix time in seconds we want the on-chain swap to be published by.
    int64 swap_publication_deadline = 4;

    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 5;

    // The requested absolute block height of the on-chain htlc. This is
    // subjected to min and max constraints as reported in the LoopOutTerms
    // response.
    int32 expiry = 6;
}

message ServerLoopOutResponse {
    string swap_invoice = 1;

    string prepay_invoice = 2;

    bytes sender_key = 3;

    // The height at which the on-chain htlc will expire. Deprecated because the
    // field is already specified in the request.
    int32 expiry = 4 [deprecated = true];

    // A human-readable message from the loop server.
    string server_message = 5;
}

message ServerLoopOutQuoteRequest {
    /// The swap amount. If zero, a quote for a maximum amt swap will be given.
    uint64 amt = 1;

    /// The unix time in seconds we want the on-chain swap to be published by.
    int64 swap_publication_deadline = 2;

    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 3;

    // The requested absolute block height of the on-chain htlc. This is
    // subjected to min and max constraints as reported in the LoopOutTerms
    // response.
    int32 expiry = 4;
}

message ServerLoopOutQuote {
    string swap_payment_dest = 1;

    /// The total estimated swap fee given the quote amt.
    int64 swap_fee = 2;

    /// Deprecated, total swap fee given quote amt is calculated in swap_fee.
    int64 swap_fee_rate = 3 [deprecated = true];

    uint64 prepay_amt = 4;

    uint64 min_swap_amount = 5 [deprecated = true];

    uint64 max_swap_amount = 6 [deprecated = true];

    // The server-proposed cltv delta of the on-chain htlc. Deprecated because
    // the field is already specified in the request.
    int32 cltv_delta = 7 [deprecated = true];
}

message ServerLoopOutTermsRequest {
    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 1;
}

message ServerLoopOutTerms {
    uint64 min_swap_amount = 1;
    uint64 max_swap_amount = 2;

    // The minimally accepted cltv delta of the on-chain htlc.
    int32 min_cltv_delta = 3;

    // The maximally accepted cltv delta of the on-chain htlc.
    int32 max_cltv_delta = 4;
}

message ServerLoopInRequest {
    bytes sender_key = 1;
    bytes swap_hash = 2;
    uint64 amt = 3;
    string swap_invoice = 4;
    bytes last_hop = 5;

    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 6;

    string probe_invoice = 7;
}

message ServerLoopInResponse {
    bytes receiver_key = 1;
    int32 expiry = 2;

    // A human-readable message from the loop server.
    string server_message = 3;
}

message ServerLoopInQuoteRequest {
    /// The swap amount. If zero, a quote for a maximum amt swap will be given.
    uint64 amt = 1;

    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 2;
}

message ServerLoopInQuoteResponse {
    int64 swap_fee = 1;
    int64 swap_fee_rate = 2 [deprecated = true];
    uint64 min_swap_amount = 4 [deprecated = true];
    uint64 max_swap_amount = 5 [deprecated = true];
    int32 cltv_delta = 6;
}

message ServerLoopInTermsRequest {
    /// The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 1;
}

message ServerLoopInTerms {
    uint64 min_swap_amount = 1;
    uint64 max_swap_amount = 2;
}

// ServerLoopOutPushPreimageRequest pushes a preimage to the server. Note that
// this call returns with no error after the server acknowledges the preimage
// and does not block until the invoice is settled.
message ServerLoopOutPushPreimageRequest {
    // The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 1;

    /*
    Preimage is the preimage of the loop out swap that we wish to push to the
    server to speed up off-chain claim once the on-chain htlc has confirmed.
    */
    bytes preimage = 2;
}

message ServerLoopOutPushPreimageResponse {
}

message SubscribeUpdatesRequest {
    // The protocol version that the client adheres to.
    ProtocolVersion protocol_version = 1;

    // Swap hash is the hash of the swap to subscribe to updates for.
    bytes swap_hash = 2;
}

// ServerSwapState is an enum which represents all the states a swap may have
// from the server's perspective.
enum ServerSwapState {
    // The server has created the swap.
    INITIATED = 0;

    // The server has published the loop out on chain htlc.
    HTLC_PUBLISHED = 1;

    // The swap completed successfully.
    SUCCESS = 2;

    /*
    The swap failed for a reason that is unknown to the server, this is only
    set for older swaps.
    */
    FAILED_UNKNOWN = 3;

    // No htlc was confirmed in time for the loop in swap to complete.
    FAILED_NO_HTLC = 4;

    // A loop in htlc confirmed on chain, but it did not have the correct value.
    FAILED_INVALID_HTLC_AMOUNT = 5;

    /*
    We did not succeed in completing the loop in off chain payment before the
    timeout.
    */
    FAILED_OFF_CHAIN_TIMEOUT = 6;

    // The on chain timeout was claimed.
    FAILED_TIMEOUT = 7;

    /*
    The server could not publish the loop out on chain htlc before the deadline
    provided.
    */
    FAILED_SWAP_DEADLINE = 8;

    // The server could not publish the loop out on chain htlc.
    FAILED_HTLC_PUBLICATION = 9;

    // The server has published the loop out on chain timeout tx.
    TIMEOUT_PUBLISHED = 10;

    // The swap has failed for unknown reasons, it will not be completed.
    UNEXPECTED_FAILURE = 11;

    // The swap htlc has confirmed on chain.
    HTLC_CONFIRMED = 12;
}

message SubscribeLoopOutUpdatesResponse{
    // The unix timestamp in nanoseconds when the swap was updated.
    int64 timestamp_ns = 1;

    // The swap's current state.
    ServerSwapState state = 2;
}

message SubscribeLoopInUpdatesResponse{
    // The unix timestamp in nanoseconds when the swap was updated.
    int64 timestamp_ns = 1;

    // The swap's current state.
    ServerSwapState state = 2;
}