lightning-terminal/proto/lit-accounts.proto

syntax = "proto3";

package litrpc;

import "lnd.proto";

option go_package = "github.com/lightninglabs/lightning-terminal/litrpc";

service Accounts {
    /* litcli: `accounts create`
    CreateAccount adds an entry to the account database. This entry represents
    an amount of satoshis (account balance) that can be spent using off-chain
    transactions (e.g. paying invoices).

    Macaroons can be created to be locked to an account. This makes sure that
    the bearer of the macaroon can only spend at most that amount of satoshis
    through the daemon that has issued the macaroon.

    Accounts only assert a maximum amount spendable. Having a certain account
    balance does not guarantee that the node has the channel liquidity to
    actually spend that amount.
    */
    rpc CreateAccount (CreateAccountRequest) returns (CreateAccountResponse);

    /* litcli: `accounts update`
    UpdateAccount updates an existing account in the account database.
    */
    rpc UpdateAccount (UpdateAccountRequest) returns (Account);

    /* litcli: `accounts update credit`
    CreditAccount increases the balance of an existing account in the account
    database.
    */
    rpc CreditAccount (CreditAccountRequest) returns (CreditAccountResponse);

    /* litcli: `accounts update debit`
    DebitAccount decreases the balance of an existing account in the account
    database.
    */
    rpc DebitAccount (DebitAccountRequest) returns (DebitAccountResponse);

    /* litcli: `accounts list`
    ListAccounts returns all accounts that are currently stored in the account
    database.
    */
    rpc ListAccounts (ListAccountsRequest) returns (ListAccountsResponse);

    /* litcli: `accounts info`
    AccountInfo returns the account with the given ID or label.
    */
    rpc AccountInfo (AccountInfoRequest) returns (Account);

    /* litcli: `accounts remove`
    RemoveAccount removes the given account from the account database.
    */
    rpc RemoveAccount (RemoveAccountRequest) returns (RemoveAccountResponse);

    /* litcli: `accounts payments`
    AccountPayments returns the detailed payment history for the given account.
    */
    rpc AccountPayments (AccountPaymentsRequest)
        returns (AccountPaymentsResponse);
}

message CreateAccountRequest {
    /*
    The initial account balance in satoshis representing the maximum amount that
    can be spent.
    */
    uint64 account_balance = 1 [jstype = JS_STRING];

    /*
    The expiration date of the account as a timestamp. Set to 0 to never expire.
    */
    int64 expiration_date = 2 [jstype = JS_STRING];

    /*
    An optional label to identify the account. If the label is not empty, then
    it must be unique, otherwise it couldn't be used to query a single account.
    */
    string label = 3;
}

message CreateAccountResponse {
    // The new account that was created.
    Account account = 1;

    // The macaroon with all permissions required to access the account.
    bytes macaroon = 2;
}

message Account {
    // The ID of the account.
    string id = 1;

    /*
    The initial balance in satoshis that was set when the account was created.
    */
    uint64 initial_balance = 2 [jstype = JS_STRING];

    // The current balance in satoshis.
    int64 current_balance = 3 [jstype = JS_STRING];

    // Timestamp of the last time the account was updated.
    int64 last_update = 4 [jstype = JS_STRING];

    /*
    Timestamp of the account's expiration date. Zero means it does not expire.
    */
    int64 expiration_date = 5 [jstype = JS_STRING];

    /*
    The list of invoices created by the account. An invoice created by an
    account will credit the account balance if it is settled.
    */
    repeated AccountInvoice invoices = 6;

    /*
    The list of payments made by the account. A payment made by an account will
    debit the account balance if it is settled.
    */
    repeated AccountPayment payments = 7;

    /*
    An optional label to identify the account. If this is not empty, then it is
    guaranteed to be unique.
    */
    string label = 8;
}

message AccountInvoice {
    // The payment hash of the invoice.
    bytes hash = 1;
}

message AccountPayment {
    // The payment hash.
    bytes hash = 1;

    // The state of the payment as reported by lnd.
    string state = 2;

    /*
    The full amount in satoshis reserved for this payment. This includes the
    routing fee estimated by the fee limit of the payment request. The actual
    debited amount will likely be lower if the fee is below the limit.
    */
    int64 full_amount = 3 [jstype = JS_STRING];
}

message UpdateAccountRequest {
    // The ID of the account to update. Either the ID or the label must be set.
    string id = 1;

    /*
    Deprecated, use the `litcli update credit` or `litcli update debit`
    commands instead. The new account balance to set. Set to -1 to not
    update the balance.
     */
    int64 account_balance = 2 [deprecated = true, jstype = JS_STRING];

    /*
    The new account expiry to set. Set to -1 to not update the expiry. Set to 0
    to never expire.
    */
    int64 expiration_date = 3 [jstype = JS_STRING];

    /*
    The label of the account to update. If an account has no label, then the ID
    must be used instead. This field is only used to identify the account.
    */
    string label = 4;

    // The new label to set for the account.
    string new_label = 5;
}

message CreditAccountRequest {
    // The identifier of the account to credit.
    AccountIdentifier account = 1;

    /*
    The amount by which the account's balance should be credited.
    */
    uint64 amount = 2 [jstype = JS_STRING];
}

message CreditAccountResponse {
    // The credited account.
    Account account = 1;
}

message DebitAccountRequest {
    // The identifier of the account to debit.
    AccountIdentifier account = 1;

    /*
    The amount by which the account's balance should be debited.
    */
    uint64 amount = 3 [jstype = JS_STRING];
}

message DebitAccountResponse {
    // The debited account.
    Account account = 1;
}

message ListAccountsRequest {
}

message ListAccountsResponse {
    // All accounts in the account database.
    repeated Account accounts = 1;
}

message AccountInfoRequest {
    /*
    The hexadecimal ID of the account to remove. Either the ID or the label must
    be set.
    */
    string id = 1;

    /*
    The label of the account to remove. If an account has no label, then the ID
    must be used instead.
    */
    string label = 2;
}

message RemoveAccountRequest {
    /*
    The hexadecimal ID of the account to remove. Either the ID or the label must
    be set.
    */
    string id = 1;

    /*
    The label of the account to remove. If an account has no label, then the ID
    must be used instead.
    */
    string label = 2;
}

message RemoveAccountResponse {
}

message AccountIdentifier {
    oneof identifier {
        // The ID of the account.
        string id = 1;

        // The label of the account.
        string label = 2;
    }
}

message AccountPaymentsRequest {
    /*
    The identifier of the account to query payments for.
    */
    AccountIdentifier account = 1;

    /*
    The maximum number of payments to return. If set to 0, it will default
    to 20. Capped at 50.
    */
    uint64 max_payments = 2 [jstype = JS_STRING];

    /*
    The row offset into the list of payments that will be used as the start of
    the query. The payments are returned in ascending lexicographical order of
    their payment hash.
    */
    uint64 index_offset = 3 [jstype = JS_STRING];

    /*
    If set, the total number of payments matching the query will be returned
    in the response.
    */
    bool count_total_payments = 4;
}

message AccountPaymentsResponse {
    /*
    The detailed payments associated with the account, sorted in ascending
    lexicographical order of their payment hash.
    */
    repeated lnrpc.Payment payments = 1;

    /*
    The row offset of the first payment returned.
    */
    uint64 first_index_offset = 2 [jstype = JS_STRING];

    /*
    The row offset of the last payment returned. This can be used as the
    index_offset in a subsequent query to paginate forwards.
    */
    uint64 last_index_offset = 3 [jstype = JS_STRING];

    /*
    The total number of payments matching the query (only set if
    count_total_payments was true in the request).
    */
    uint64 total_num_payments = 4 [jstype = JS_STRING];
}