syntax = "proto3";

package autopilotrpc;

option go_package = "github.com/lightningnetwork/lnd/lnrpc/autopilotrpc";

/*
 * Comments in this file will be directly parsed into the API
 * Documentation as descriptions of the associated method, message, or field.
 * These descriptions should go right above the definition of the object, and
 * can be in either block or // comment format.
 *
 * An RPC method can be matched to an lncli command by placing a line in the
 * beginning of the description in exactly the following format:
 * lncli: `methodname`
 *
 * Failure to specify the exact name of the command will cause documentation
 * generation to fail.
 *
 * More information on how exactly the gRPC documentation is generated from
 * this proto file can be found here:
 * https://github.com/lightninglabs/lightning-api
 */

// Autopilot is a service that can be used to get information about the current
// state of the daemon's autopilot agent, and also supply it with information
// that can be used when deciding where to open channels.
service Autopilot {
    /* lncli: `autopilot status`
    Status returns whether the daemon's autopilot agent is active.
    */
    rpc Status (StatusRequest) returns (StatusResponse);

    /*
    ModifyStatus is used to modify the status of the autopilot agent, like
    enabling or disabling it.
    */
    rpc ModifyStatus (ModifyStatusRequest) returns (ModifyStatusResponse);

    /* lncli: `autopilot query`
    QueryScores queries all available autopilot heuristics, in addition to any
    active combination of these heruristics, for the scores they would give to
    the given nodes.
    */
    rpc QueryScores (QueryScoresRequest) returns (QueryScoresResponse);

    /*
    SetScores attempts to set the scores used by the running autopilot agent,
    if the external scoring heuristic is enabled.
    */
    rpc SetScores (SetScoresRequest) returns (SetScoresResponse);
}

message StatusRequest {
}

message StatusResponse {
    // Indicates whether the autopilot is active or not.
    bool active = 1;
}

message ModifyStatusRequest {
    // Whether the autopilot agent should be enabled or not.
    bool enable = 1;
}

message ModifyStatusResponse {
}

message QueryScoresRequest {
    repeated string pubkeys = 1;

    // If set, we will ignore the local channel state when calculating scores.
    bool ignore_local_state = 2;
}

message QueryScoresResponse {
    message HeuristicResult {
        string heuristic = 1;
        map<string, double> scores = 2;
    }

    repeated HeuristicResult results = 1;
}

message SetScoresRequest {
    // The name of the heuristic to provide scores to.
    string heuristic = 1;

    /*
    A map from hex-encoded public keys to scores. Scores must be in the range
    [0.0, 1.0].
    */
    map<string, double> scores = 2;
}

message SetScoresResponse {
}
