faraday/frdrpc/rpc.proto

syntax = "proto3";

import "google/api/annotations.proto";

package frdrpc;

service FaradayServer {
    rpc OutlierRecommendations (OutlierRecommendationsRequest) returns (CloseRecommendationsResponse);
    rpc ThresholdRecommendations (ThresholdRecommendationsRequest) returns (CloseRecommendationsResponse);
    rpc RevenueReport (RevenueReportRequest) returns (RevenueReportResponse);
    rpc ChannelInsights (ChannelInsightsRequest) returns (ChannelInsightsResponse);
}

message CloseRecommendationRequest {
    /*
    The minimum amount of time in seconds that a channel should have been
    monitored by lnd to be eligible for close. This value is in place to
    protect against closing of newer channels.
    */
    int64 minimum_monitored = 1;

    enum Metric{
        UNKNOWN = 0;
        UPTIME = 1;
        REVENUE = 2;
        INCOMING_VOLUME = 3;
        OUTGOING_VOLUME = 4;
        TOTAL_VOLUME = 5;
    }

    /*
    The data point base close recommendations on. Available options are:
    Uptime: ratio of channel peer's uptime to the period they have been
    monitored to.
    Revenue: the revenue that the channel has produced per block that its
    funding transaction has been confirmed for.
    */
    Metric metric = 2;
}

message OutlierRecommendationsRequest {
    /*
    The parameters that are common to all close recommendations.
    */
    CloseRecommendationRequest rec_request = 1;

    /*
    The number of inter-quartile ranges a value needs to be beneath the lower
    quartile/ above the upper quartile to be considered a lower/upper outlier.
    Lower values will be more aggressive in recommending channel closes, and
    upper values will be more conservative. Recommended values are 1.5 for
    aggressive recommendations and 3 for conservative recommendations.
    */
    float outlier_multiplier = 2;
}

message ThresholdRecommendationsRequest {
    /*
    The parameters that are common to all close recommendations.
    */
    CloseRecommendationRequest rec_request = 1;

    /*
    The threshold that recommendations will be calculated based on.
    For uptime: ratio of uptime to observed lifetime beneath which channels
    will be recommended for closure.

    For revenue: revenue per block that capital has been committed to the
    channel beneath which channels will be recommended for closure. This
    value is provided per block so that channels that have been open for
    different periods of time can be compared.

    For incoming volume: The incoming volume per block that capital has
    been committed to the channel beneath which channels will be recommended
    for closure. This value is provided per block so that channels that have
    been open for different periods of time can be compared.

    For outgoing volume: The outgoing volume per block that capital has been
    committed to the channel beneath which channels will be recommended for
    closure. This value is provided per block so that channels that have been
    open for different periods of time can be compared.

    For total volume: The total volume per block that capital has been
    committed to the channel beneath which channels will be recommended for
    closure. This value is provided per block so that channels that have been
    open for different periods of time can be compared.
    */
    float threshold_value = 2;
}

message CloseRecommendationsResponse {
    /*
    The total number of channels, before filtering out channels that are
    not eligible for close recommendations.
    */
    int32 total_channels = 1;

    /*
    The number of channels that were considered for close recommendations.
    */
    int32 considered_channels = 2;

    /*
    A set of channel close recommendations. The absence of a channel in this
    set implies that it was not considered for close because it did not meet
    the criteria for close recommendations (it is private, or has not been
    monitored for long enough).
    */
    repeated Recommendation recommendations = 3;
}

message Recommendation {
    /*
    The channel point [funding txid: outpoint] of the channel being considered
    for close.
     */
    string chan_point = 1;

    // The value of the metric that close recommendations were based on.
    float value = 2;

    // A boolean indicating whether we recommend closing the channel.
    bool recommend_close = 3;
}

message RevenueReportRequest {
    /*
    The funding transaction outpoints for the channels to generate a revenue
    report for. If this is empty, it will be generated for all open and closed
    channels. Channel funding points should be expressed with the format
    fundingTxID:outpoint.
    */
    repeated string chan_points = 1;

    /*
    Start time is beginning of the range over which the report will be
    generated, expressed as unix epoch offset in seconds.
    */
    uint64 start_time = 2;

    /*
    End time is end of the range over which the report will be
    generated, expressed as unix epoch offset in seconds.
     */
    uint64 end_time = 3;
}

message RevenueReportResponse {
    /*
    Reports is a set of pairwise revenue report generated for the channel(s)
    over the period specified.
    */
    repeated RevenueReport reports = 1;
}

message RevenueReport {
    /*
    Target channel is the channel that the report is generated for; incoming
    fields in the report mean that this channel was the incoming channel,
    and the pair as the outgoing, outgoing fields mean that this channel was
    the outgoing channel and the peer was the incoming channel.
    */
    string target_channel = 1;

    /*
    Pair reports maps the channel point of a peer that we generated revenue
    with to a report detailing the revenue.
    */
    map<string, PairReport> pair_reports = 2;
}

message PairReport {
    /*
    Amount outgoing msat is the amount in millisatoshis that arrived
    on the pair channel to be forwarded onwards by our channel.
    */
    int64 amount_outgoing_msat = 1;

    /*
    Fees outgoing is the amount of fees in millisatoshis that we
    attribute to the channel for its role as the outgoing channel in
    forwards.
    */
    int64 fees_outgoing_msat = 2;

    /*
    Amount incoming msat is the amount in millisatoshis that arrived
    on our channel to be forwarded onwards by the pair channel.
    */
    int64 amount_incoming_msat = 3;

    /*
    Fees incoming is the amount of fees in millisatoshis that we
    attribute to the channel for its role as the incoming channel in
    forwards.
    */
    int64 fees_incoming_msat = 4;
}

message ChannelInsightsRequest {
}

message ChannelInsightsResponse {
    // Insights for the set of currently open channels.
    repeated ChannelInsight channel_insights = 1;
}

message ChannelInsight {
    // The outpoint of the channel's funding transaction.
    string chan_point = 1;

    /*
    The amount of time in seconds that we have monitored the channel peer's
    uptime for.
    */
    uint64 monitored_seconds = 2;

    /*
    The amount of time in seconds that the channel peer has been online over
    the period it has been monitored for.
    */
    uint64 uptime_seconds = 3;

    /*
    The volume, in millisatoshis, that has been forwarded with this channel as
    the incoming channel.
    */
    int64 volume_incoming_msat = 4;

    /*
    The volume, in millisatoshis, that has been forwarded with this channel as
    the outgoing channel.
    */
    int64 volume_outgoing_msat = 5;

    /*
    The total fees earned by this channel for its participation in forwards,
    expressed in millisatoshis. Note that we attribute fees evenly across
    incoming and outgoing channels.
    */
    int64 fees_earned_msat = 6;

    // The number of confirmations the funding transaction has.
    uint32 confirmations = 7;

    // True if the channel is private.
    bool private = 8;
}