pool/poolrpc/trader.proto

syntax = "proto3";

import "google/api/annotations.proto";
import "auctioneer.proto";

package poolrpc;

option go_package = "github.com/lightninglabs/pool/poolrpc";

service Trader {
    /*
    QuoteAccount gets a fee quote to fund an account of the given size with the
    given confirmation target. If the connected lnd wallet doesn't have enough
    balance to fund an account of the requested size, an error is returned.
    */
    rpc QuoteAccount (QuoteAccountRequest) returns (QuoteAccountResponse) {
        option (google.api.http) = {
            post: "/v1/pool/accounts/quote"
            body: "*"
        };
    };

    /* pool: `accounts new`
    InitAccount creates a new account with the requested size and expiration,
    funding it from the wallet of the connected lnd node.
    */
    rpc InitAccount (InitAccountRequest) returns (Account) {
        option (google.api.http) = {
            post: "/v1/pool/accounts"
            body: "*"
        };
    };

    /* pool: `accounts list`
    ListAccounts returns a list of all accounts known to the trader daemon and
    their current state.
    */
    rpc ListAccounts (ListAccountsRequest) returns (ListAccountsResponse) {
        option (google.api.http) = {
            get: "/v1/pool/accounts"
        };
    };

    /* pool: `accounts close`
    CloseAccount closes an account and returns the funds locked in that account
    to the connected lnd node's wallet.
    */
    rpc CloseAccount (CloseAccountRequest) returns (CloseAccountResponse) {
        option (google.api.http) = {
            delete: "/v1/pool/accounts"
        };
    };

    /* pool: `accounts withdraw`
    WithdrawAccount splits off parts of the account balance into the specified
    outputs while recreating the account with a reduced balance.
    */
    rpc WithdrawAccount (WithdrawAccountRequest) returns (WithdrawAccountResponse) {
        option (google.api.http) = {
            post: "/v1/pool/accounts/withdraw"
            body: "*"
        };
    };

    /* pool: `accounts deposit`
    DepositAccount adds more funds from the connected lnd node's wallet to an
    account.
    */
    rpc DepositAccount (DepositAccountRequest) returns (DepositAccountResponse) {
        option (google.api.http) = {
            post: "/v1/pool/accounts/deposit"
            body: "*"
        };
    };

    /* pool: `accounts bumpfee`
    BumpAccountFee attempts to bump the fee of an account's transaction through
    child-pays-for-parent (CPFP). Since the CPFP is performed through the
    backing lnd node, the account transaction must contain an output under its
    control for a successful bump. If a CPFP has already been performed for an
    account, and this RPC is invoked again, then a replacing transaction (RBF)
    of the child will be broadcast.
    */
    rpc BumpAccountFee (BumpAccountFeeRequest) returns (BumpAccountFeeResponse) {
        option (google.api.http) = {
            post: "/v1/pool/accounts/bump"
            body: "*"
        };
    };

    /* pool: `accounts recover`
    RecoverAccounts queries the auction server for this trader daemon's accounts
    in case we lost our local account database.
    */
    rpc RecoverAccounts (RecoverAccountsRequest) returns (RecoverAccountsResponse) {
        option (google.api.http) = {
            post: "/v1/pool/accounts/recover"
            body: "*"
        };
    };

    /* pool: `orders submit`
    SubmitOrder creates a new ask or bid order and submits for the given account
    and submits it to the auction server for matching.
    */
    rpc SubmitOrder (SubmitOrderRequest) returns (SubmitOrderResponse) {
        option (google.api.http) = {
            post: "/v1/pool/orders"
            body: "*"
        };
    };

    /* pool: `orders list`
    ListOrders returns a list of all active and archived orders that are
    currently known to the trader daemon.
    */
    rpc ListOrders (ListOrdersRequest) returns (ListOrdersResponse) {
        option (google.api.http) = {
            get: "/v1/pool/orders"
        };
    }

    /* pool: `orders cancel`
    CancelOrder cancels an active order with the auction server to remove it
    from future matching.
    */
    rpc CancelOrder (CancelOrderRequest) returns (CancelOrderResponse) {
        option (google.api.http) = {
            delete: "/v1/pool/orders/{order_nonce}"
        };
    };

    /* pool: `auction fee`
    AuctionFee returns the current auction order execution fee specified by the
    auction server.
    */
    rpc AuctionFee (AuctionFeeRequest) returns (AuctionFeeResponse) {
        option (google.api.http) = {
            get: "/v1/pool/fee"
        };
    };

    /* pool: `auction leasedurations`
    LeaseDurations returns the current set of valid lease duration in the
    market as is, and also information w.r.t if the market is currently active.
    */
    rpc LeaseDurations(LeaseDurationRequest) returns (LeaseDurationResponse) {
        option (google.api.http) = {
            get: "/v1/pool/lease_durations"
        };
    }

    /* pool: `auction snapshot`
    BatchSnapshot returns the snapshot of a past batch identified by its ID.
    */
    rpc BatchSnapshot (BatchSnapshotRequest) returns (BatchSnapshotResponse) {
        option (google.api.http) = {
            get: "/v1/pool/batch/snapshot"
        };
    };

    /* pool: `listauth`
    GetLsatTokens returns all LSAT tokens the daemon ever paid for.
    */
    rpc GetLsatTokens (TokensRequest) returns (TokensResponse) {
        option (google.api.http) = {
            get: "/v1/lsat/tokens"
        };
    }

    /* pool: `auction leases`
    Leases returns the list of channels that were either purchased or sold by
    the trader within the auction.
    */
    rpc Leases (LeasesRequest) returns (LeasesResponse) {
        option (google.api.http) = {
            get: "/v1/pool/leases"
        };
    };

    /* pool: `auction ratings`
    Returns the Node Tier information for this target Lightning node, and other
    related ranking information.
    */
    rpc NodeRatings(NodeRatingRequest) returns (NodeRatingResponse) {
        option (google.api.http) = {
            get: "/v1/pool/node_ratings"
        };
    };
}

message InitAccountRequest {
    uint64 account_value = 1;

    oneof account_expiry {
        uint32 absolute_height = 2;
        uint32 relative_height = 3;
    }

    oneof fees {
        /*
        The target number of blocks that the transaction should be confirmed in.
        */
        uint32 conf_target = 4;

        // TODO(guggero): Add sat_per_vbyte as soon as lnd has a parameter for
        // that in rpcServer.EstimateFee.
    }
}

message QuoteAccountRequest {
    uint64 account_value = 1;

    oneof fees {
        /*
        The target number of blocks that the transaction should be confirmed in.
        */
        uint32 conf_target = 2;

        // TODO(guggero): Add sat_per_vbyte as soon as lnd has a parameter for
        // that in rpcServer.EstimateFee.
    }
}

message QuoteAccountResponse {
    uint64 miner_fee_rate_sat_per_kw = 1;

    uint64 miner_fee_total = 2;
}

message ListAccountsRequest {
}
message ListAccountsResponse {
    repeated Account accounts = 1;
}

message Output {
    // The value, in satoshis, of the output.
    uint64 value_sat = 1;

    // The address corresponding to the output.
    string address = 2;
}

message OutputWithFee {
    // The address corresponding to the output.
    string address = 1;

    oneof fees {
        /*
        The target number of blocks that the transaction should be confirmed in.
        */
        uint32 conf_target = 2;

        /*
        The fee rate, in satoshis per kw, to use for the withdrawal transaction.
        */
        uint64 fee_rate_sat_per_kw = 3;
    }
}

message OutputsWithImplicitFee {
    repeated Output outputs = 1;
}

message CloseAccountRequest {
    // The trader key associated with the account that will be closed.
    bytes trader_key = 1;

    oneof funds_destination {
        /*
        A single output/address to which the remaining funds of the account will
        be sent to at the specified fee. If an address is not specified, then
        the funds are sent to an address the backing lnd node controls.
        */
        OutputWithFee output_with_fee = 2;

        /*
        The outputs to which the remaining funds of the account will be sent to.
        This should only be used when wanting to create two or more outputs,
        otherwise OutputWithFee should be used instead. The fee of the account's
        closing transaction is implicitly defined by the combined value of all
        outputs.
        */
        OutputsWithImplicitFee outputs = 3;
    }
}
message CloseAccountResponse {
    // The hash of the closing transaction.
    bytes close_txid = 1;
}

message WithdrawAccountRequest {
    /*
    The trader key associated with the account that funds will be withdrawed
    from.
    */
    bytes trader_key = 1;

    // The outputs we'll withdraw funds from the account into.
    repeated Output outputs = 2;

    /*
    The fee rate, in satoshis per kw, to use for the withdrawal transaction.
    */
    uint64 fee_rate_sat_per_kw = 3;
}
message WithdrawAccountResponse {
    // The state of the account after processing the withdrawal.
    Account account = 1;

    // The transaction used to withdraw funds from the account.
    bytes withdraw_txid = 2;
}

message DepositAccountRequest {
    /*
    The trader key associated with the account that funds will be deposited
    into.
    */
    bytes trader_key = 1;

    // The amount in satoshis to deposit into the account.
    uint64 amount_sat = 2;

    /*
    The fee rate, in satoshis per kw, to use for the deposit transaction.
    */
    uint64 fee_rate_sat_per_kw = 3;
}
message DepositAccountResponse {
    // The state of the account after processing the deposit.
    Account account = 1;

    // The transaction used to deposit funds into the account.
    bytes deposit_txid = 2;
}

message BumpAccountFeeRequest {
    /*
    The trader key associated with the account that will have its fee bumped.
    */
    bytes trader_key = 1;

    /*
    The new fee rate, in satoshis per kw, to use for the child of the account
    transaction.
    */
    uint64 fee_rate_sat_per_kw = 2;
}
message BumpAccountFeeResponse {
}

enum AccountState {
    // The state of an account when it is pending its confirmation on-chain.
    PENDING_OPEN = 0;

    /*
    The state of an account when it has undergone an update on-chain either as
    part of a matched order or a trader modification and it is pending its
    confirmation on-chain.
    */
    PENDING_UPDATE = 1;

    // The state of an account once it has confirmed on-chain.
    OPEN = 2;

    /*
    The state of an account once its expiration has been reached and its closing
    transaction has confirmed.
    */
    EXPIRED = 3;

    /*
    The state of an account when we're waiting for the closing transaction of
    an account to confirm that required cooperation with the auctioneer.
    */
    PENDING_CLOSED = 4;

    // The state of an account once its closing transaction has confirmed.
    CLOSED = 5;

    /*
    The state of an account that indicates that the account was attempted to be
    recovered but failed because the opening transaction wasn't found by lnd.
    This could be because it was never published or it never confirmed. Then the
    funds are SAFU and the account can be considered to never have been opened
    in the first place.
    */
    RECOVERY_FAILED = 6;

    /*
    The account has recently participated in a batch and is not yet confirmed.
    */
    PENDING_BATCH = 7;
}

message Account {
    /*
    The identifying component of an account. This is the key used for the trader
    in the 2-of-2 multi-sig construction of an account with an auctioneer.
    */
    bytes trader_key = 1;

    /*
    The current outpoint associated with the account. This will change every
    time the account has been updated.
    */
    OutPoint outpoint = 2;

    // The current total amount of satoshis in the account.
    uint64 value = 3;

    /*
    The amount of satoshis in the account that is available, meaning not
    allocated to any oustanding orders.
    */
    uint64 available_balance = 4;

    // The height at which the account will expire.
    uint32 expiration_height = 5;

    // The current state of the account.
    AccountState state = 6;

    // The hash of the account's latest transaction.
    bytes latest_txid = 7;
}

message SubmitOrderRequest {
    oneof details {
        Ask ask = 1;
        Bid bid = 2;
    }
}
message SubmitOrderResponse {
    oneof details {
        /*
        Order failed with the given reason.
        */
        InvalidOrder invalid_order = 1;

        /*
        The order nonce of the accepted order.
        */
        bytes accepted_order_nonce = 2;
    }
}

message ListOrdersRequest {
    /*
    Can be set to true to list the orders including all events, which can be
    very verbose.
    */
    bool verbose = 1;

    /*
    Only list orders that are still active.
    */
    bool active_only = 2;
}
message ListOrdersResponse {
    repeated Ask asks = 1;
    repeated Bid bids = 2;
}

message CancelOrderRequest {
    bytes order_nonce = 1;
}
message CancelOrderResponse {
}

message Order {
    /*
    The trader's account key of the account that is used for the order.
    */
    bytes trader_key = 1;

    /*
    Fixed order rate in parts per billion.
    */
    uint32 rate_fixed = 2;

    /*
    Order amount in satoshis.
    */
    uint64 amt = 3;

    /*
    Maximum fee rate the trader is willing to pay for the batch transaction,
    expressed in satoshis per 1000 weight units (sat/KW).
    */
    uint64 max_batch_fee_rate_sat_per_kw = 4;

    /*
    Order nonce, acts as unique order identifier.
    */
    bytes order_nonce = 5;

    /*
    The state the order currently is in.
    */
    OrderState state = 6;

    /*
    The number of order units the amount corresponds to.
    */
    uint32 units = 7;

    /*
    The number of currently unfilled units of this order. This will be equal to
    the total amount of units until the order has reached the state PARTIAL_FILL
    or EXECUTED.
    */
    uint32 units_unfulfilled = 8;

    // The value reserved from the account by this order to ensure the account
    // can pay execution and chain fees in case it gets matched.
    uint64 reserved_value_sat = 9;

    // The unix timestamp in nanoseconds the order was first created/submitted.
    uint64 creation_timestamp_ns = 10;

    /*
    A list of events that were emitted for this order. This field is only set
    when the verbose flag is set to true in the request.
    */
    repeated OrderEvent events = 11;

    // The minimum number of order units that must be matched per order pair.
    uint32 min_units_match = 12;
}

message Bid {
    /*
    The common fields shared between both ask and bid order types.
    */
    Order details = 1;

    /*
    Required number of blocks that a channel opened as a result of this bid
    should be kept open.
    */
    uint32 lease_duration_blocks = 2;

    /*
    The version of the order format that is used. Will be increased once new
    features are added.
    */
    uint32 version = 3;


    /*
    The minium node tier this order should be matched with. Only asks backed by
    a node this tier or higher will be eligible for matching with this bid.
    */
    NodeTier min_node_tier = 4;
}

message Ask {
    /*
    The common fields shared between both ask and bid order types.
    */
    Order details = 1;

    /*
    The number of blocks the liquidity provider is willing to provide the
    channel funds for.
    */
    uint32 lease_duration_blocks = 2;

    /*
    The version of the order format that is used. Will be increased once new
    features are added.
    */
    uint32 version = 3;
}

message OrderEvent {
    /*
    The unix timestamp in nanoseconds the event was emitted at. This is the
    primary key of the event and is unique across the database.
    */
    int64 timestamp_ns = 1;

    // The human readable representation of the event.
    string event_str = 2;

    oneof event {
        // The order was updated in the database.
        UpdatedEvent state_change = 3;

        // The order was involved in a match making attempt.
        MatchEvent matched = 4;
    }
}

message UpdatedEvent {
    /*
    The state of the order previous to the change. This is what the state
    changed from.
    */
    OrderState previous_state = 1;

    /*
    The new state of the order after the change. This is what the state changed
    to.
    */
    OrderState new_state = 2;

    // The units that were filled at the time of the event.
    uint32 units_filled = 3;
}

message MatchEvent {
    // The state of the match making process the order went through.
    MatchState match_state = 1;

    // The number of units that would be (or were) filled with this match.
    uint32 units_filled = 2;

    // The nonce of the order we were matched to.
    bytes matched_order = 3;

    /*
    The reason why the trader daemon rejected the order. Is only set if
    match_state is set to REJECTED.
    */
    MatchRejectReason reject_reason = 4;
}

enum MatchState {
    /*
    The OrderMatchPrepare message from the auctioneer was received initially.
    */
    PREPARE = 0;

    /*
    The OrderMatchPrepare message from the auctioneer was processed successfully
    and the batch was accepted.
    */
    ACCEPTED = 1;

    /*
    The order was rejected by the trader daemon, either as an answer to a
    OrderMatchSignBegin or OrderMatchFinalize message from the auctioneer.
    */
    REJECTED = 2;

    /*
    The OrderMatchSignBegin message from the auctioneer was processed
    successfully.
    */
    SIGNED = 3;

    /*
    The OrderMatchFinalize message from the auctioneer was processed
    successfully.
    */
    FINALIZED = 4;
}

enum MatchRejectReason {
    // No reject occurred, this is the default value.
    NONE = 0;

    /*
    The client didn't come up with the same result as the server and is
    rejecting the batch because of that.
    */
    SERVER_MISBEHAVIOR = 1;

    /*
    The client doesn't support the current batch verification version the
    server is using.
    */
    BATCH_VERSION_MISMATCH = 2;

    /*
    The client rejects some of the orders, not the full batch. This reason is
    set on matches for orders that were in the same batch as partial reject ones
    but were not themselves rejected.
    */
    PARTIAL_REJECT_COLLATERAL = 3;

    /*
    The trader's client has a preference to only match orders with peers it
    doesn't already have channels with. The order that is rejected with this
    reason type comes from a peer that the trader already has channels with.
    */
    PARTIAL_REJECT_DUPLICATE_PEER = 4;

    /*
    The trader's client couldn't connect to the remote node of the matched
    order or the channel funding could not be initialized for another
    reason. This could also be the rejecting node's fault if their
    connection is not stable. Using this code can have a negative impact on
    the reputation score of both nodes, depending on the number of errors
    recorded.
    */
    PARTIAL_REJECT_CHANNEL_FUNDING_FAILED = 5;
}

message RecoverAccountsRequest {
}

message RecoverAccountsResponse {
    // The number of accounts that were recovered.
    uint32 num_recovered_accounts = 1;
}

message AuctionFeeRequest {
}

message AuctionFeeResponse {
    /*
    The execution fee charged per matched order.
    */
    ExecutionFee execution_fee = 1;
}

message Lease {
    // The outpoint of the channel created.
    OutPoint channel_point = 1;

    // The amount, in satoshis, of the channel created.
    uint64 channel_amt_sat = 2;

    // The intended duration, in blocks, of the channel created.
    uint32 channel_duration_blocks = 3;

    // The absolute height that this channel lease expires.
    uint32 channel_lease_expiry = 4;

    /*
    The premium, in satoshis, either paid or received for the offered liquidity.
    */
    uint64 premium_sat = 5;

    /*
    The execution fee, in satoshis, charged by the auctioneer for the channel
    created.
    */
    uint64 execution_fee_sat = 6;

    /*
    The fee, in satoshis, charged by the auctioneer for the batch execution
    transaction that created this lease.
    */
    uint64 chain_fee_sat = 7;

    /*
    The actual fixed rate expressed in parts per billionth this lease was
    bought/sold at.
    */
    uint64 clearing_rate_price = 8;

    /*
    The actual fixed rate of the bid/ask, this should always be 'better' than
    the clearing_rate_price.
    */
    uint64 order_fixed_rate = 9;

    // The order executed that resulted in the channel created.
    bytes order_nonce = 10;

    // Whether this channel was purchased from another trader or not.
    bool purchased = 11;

    // The pubkey of the node that this channel was bought/sold from.
    bytes channel_remote_node_key = 12;

    // The tier of the node that this channel was bought/sold from.
    NodeTier channel_node_tier = 13;
}

message LeasesRequest {
    /*
    An optional list of batches to retrieve the leases of. If empty, leases
    throughout all batches are returned.
    */
    repeated bytes batch_ids = 1;

    /*
    An optional list of accounts to retrieve the leases of. If empty, leases
    for all accounts are returned.
    */
    repeated bytes accounts = 2;
}

message LeasesResponse {
    // The relevant list of leases purchased or sold within the auction.
    repeated Lease leases = 1;

    // The total amount of satoshis earned from the leases returned.
    uint64 total_amt_earned_sat = 2;

    // The total amount of satoshis paid for the leases returned.
    uint64 total_amt_paid_sat = 3;
}

message TokensRequest {
}

message TokensResponse {
    /**
    List of all tokens the daemon knows of, including old/expired tokens.
    */
    repeated LsatToken tokens = 1;
}

message LsatToken {
    /**
    The base macaroon that was baked by the auth server.
    */
    bytes base_macaroon = 1;

    /**
    The payment hash of the payment that was paid to obtain the token.
    */
    bytes payment_hash = 2;

    /**
    The preimage of the payment hash, knowledge of this is proof that the
    payment has been paid. If the preimage is set to all zeros, this means the
    payment is still pending and the token is not yet fully valid.
    */
    bytes payment_preimage = 3;

    /**
    The amount of millisatoshis that was paid to get the token.
    */
    int64 amount_paid_msat = 4;

    /**
    The amount of millisatoshis paid in routing fee to pay for the token.
    */
    int64 routing_fee_paid_msat = 5;

    /**
    The creation time of the token as UNIX timestamp in seconds.
    */
    int64 time_created = 6;

    /**
    Indicates whether the token is expired or still valid.
    */
    bool expired = 7;

    /**
    Identifying attribute of this token in the store. Currently represents the
    file name of the token where it's stored on the file system.
    */
    string storage_name = 8;
}

message LeaseDurationRequest {
}

message LeaseDurationResponse {
    map<uint32, bool> lease_durations = 1;
}

message NodeRatingRequest {
    // The target node to obtain ratings information for.
    repeated bytes node_pubkeys = 1;
}

message NodeRatingResponse {
    // A series of node ratings for each of the queried nodes.
    repeated NodeRating node_ratings = 1;
}