lnd/lnrpc/walletrpc/walletkit.proto

syntax = "proto3";

import "rpc.proto";
import "signrpc/signer.proto";

package walletrpc;

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

// WalletKit is a service that gives access to the core functionalities of the
// daemon's wallet.
service WalletKit {
    /*
    ListUnspent returns a list of all utxos spendable by the wallet with a
    number of confirmations between the specified minimum and maximum.
    */
    rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse);

    /*
    LeaseOutput locks an output to the given ID, preventing it from being
    available for any future coin selection attempts. The absolute time of the
    lock's expiration is returned. The expiration of the lock can be extended by
    successive invocations of this RPC. Outputs can be unlocked before their
    expiration through `ReleaseOutput`.
    */
    rpc LeaseOutput (LeaseOutputRequest) returns (LeaseOutputResponse);

    /*
    ReleaseOutput unlocks an output, allowing it to be available for coin
    selection if it remains unspent. The ID should match the one used to
    originally lock the output.
    */
    rpc ReleaseOutput (ReleaseOutputRequest) returns (ReleaseOutputResponse);

    /*
    DeriveNextKey attempts to derive the *next* key within the key family
    (account in BIP43) specified. This method should return the next external
    child within this branch.
    */
    rpc DeriveNextKey (KeyReq) returns (signrpc.KeyDescriptor);

    /*
    DeriveKey attempts to derive an arbitrary key specified by the passed
    KeyLocator.
    */
    rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor);

    /*
    NextAddr returns the next unused address within the wallet.
    */
    rpc NextAddr (AddrRequest) returns (AddrResponse);

    /*
    PublishTransaction attempts to publish the passed transaction to the
    network. Once this returns without an error, the wallet will continually
    attempt to re-broadcast the transaction on start up, until it enters the
    chain.
    */
    rpc PublishTransaction (Transaction) returns (PublishResponse);

    /*
    SendOutputs is similar to the existing sendmany call in Bitcoind, and
    allows the caller to create a transaction that sends to several outputs at
    once. This is ideal when wanting to batch create a set of transactions.
    */
    rpc SendOutputs (SendOutputsRequest) returns (SendOutputsResponse);

    /*
    EstimateFee attempts to query the internal fee estimator of the wallet to
    determine the fee (in sat/kw) to attach to a transaction in order to
    achieve the confirmation target.
    */
    rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse);

    /*
    PendingSweeps returns lists of on-chain outputs that lnd is currently
    attempting to sweep within its central batching engine. Outputs with similar
    fee rates are batched together in order to sweep them within a single
    transaction.

    NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to
    remain supported. This is an advanced API that depends on the internals of
    the UtxoSweeper, so things may change.
    */
    rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);

    /*
    BumpFee bumps the fee of an arbitrary input within a transaction. This RPC
    takes a different approach than bitcoind's bumpfee command. lnd has a
    central batching engine in which inputs with similar fee rates are batched
    together to save on transaction fees. Due to this, we cannot rely on
    bumping the fee on a specific transaction, since transactions can change at
    any point with the addition of new inputs. The list of inputs that
    currently exist within lnd's central batching engine can be retrieved
    through the PendingSweeps RPC.

    When bumping the fee of an input that currently exists within lnd's central
    batching engine, a higher fee transaction will be created that replaces the
    lower fee transaction through the Replace-By-Fee (RBF) policy. If it

    This RPC also serves useful when wanting to perform a Child-Pays-For-Parent
    (CPFP), where the child transaction pays for its parent's fee. This can be
    done by specifying an outpoint within the low fee transaction that is under
    the control of the wallet.

    The fee preference can be expressed either as a specific fee rate or a delta
    of blocks in which the output should be swept on-chain within. If a fee
    preference is not explicitly specified, then an error is returned.

    Note that this RPC currently doesn't perform any validation checks on the
    fee preference being provided. For now, the responsibility of ensuring that
    the new fee preference is sufficient is delegated to the user.
    */
    rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse);

    /*
    ListSweeps returns a list of the sweep transactions our node has produced.
    Note that these sweeps may not be confirmed yet, as we record sweeps on
    broadcast, not confirmation.
    */
    rpc ListSweeps (ListSweepsRequest) returns (ListSweepsResponse);

    /*
    LabelTransaction adds a label to a transaction. If the transaction already
    has a label the call will fail unless the overwrite bool is set. This will
    overwrite the exiting transaction label. Labels must not be empty, and
    cannot exceed 500 characters.
    */
    rpc LabelTransaction (LabelTransactionRequest)
        returns (LabelTransactionResponse);

    /*
    FundPsbt creates a fully populated PSBT that contains enough inputs to fund
    the outputs specified in the template. There are two ways of specifying a
    template: Either by passing in a PSBT with at least one output declared or
    by passing in a raw TxTemplate message.

    If there are no inputs specified in the template, coin selection is
    performed automatically. If the template does contain any inputs, it is
    assumed that full coin selection happened externally and no additional
    inputs are added. If the specified inputs aren't enough to fund the outputs
    with the given fee rate, an error is returned.

    After either selecting or verifying the inputs, all input UTXOs are locked
    with an internal app ID.

    NOTE: If this method returns without an error, it is the caller's
    responsibility to either spend the locked UTXOs (by finalizing and then
    publishing the transaction) or to unlock/release the locked UTXOs in case of
    an error on the caller's side.
    */
    rpc FundPsbt (FundPsbtRequest) returns (FundPsbtResponse);

    /*
    FinalizePsbt expects a partial transaction with all inputs and outputs fully
    declared and tries to sign all inputs that belong to the wallet. Lnd must be
    the last signer of the transaction. That means, if there are any unsigned
    non-witness inputs or inputs without UTXO information attached or inputs
    without witness data that do not belong to lnd's wallet, this method will
    fail. If no error is returned, the PSBT is ready to be extracted and the
    final TX within to be broadcast.

    NOTE: This method does NOT publish the transaction once finalized. It is the
    caller's responsibility to either publish the transaction on success or
    unlock/release any locked UTXOs in case of an error in this method.
    */
    rpc FinalizePsbt (FinalizePsbtRequest) returns (FinalizePsbtResponse);
}

message ListUnspentRequest {
    // The minimum number of confirmations to be included.
    int32 min_confs = 1;

    // The maximum number of confirmations to be included.
    int32 max_confs = 2;
}

message ListUnspentResponse {
    // A list of utxos satisfying the specified number of confirmations.
    repeated lnrpc.Utxo utxos = 1;
}

message LeaseOutputRequest {
    /*
    An ID of 32 random bytes that must be unique for each distinct application
    using this RPC which will be used to bound the output lease to.
    */
    bytes id = 1;

    // The identifying outpoint of the output being leased.
    lnrpc.OutPoint outpoint = 2;
}

message LeaseOutputResponse {
    /*
    The absolute expiration of the output lease represented as a unix timestamp.
    */
    uint64 expiration = 1;
}

message ReleaseOutputRequest {
    // The unique ID that was used to lock the output.
    bytes id = 1;

    // The identifying outpoint of the output being released.
    lnrpc.OutPoint outpoint = 2;
}

message ReleaseOutputResponse {
}

message KeyReq {
    /*
    Is the key finger print of the root pubkey that this request is targeting.
    This allows the WalletKit to possibly serve out keys for multiple HD chains
    via public derivation.
    */
    int32 key_finger_print = 1;

    /*
    The target key family to derive a key from. In other contexts, this is
    known as the "account".
    */
    int32 key_family = 2;
}

message AddrRequest {
    // No fields, as we always give out a p2wkh address.
}
message AddrResponse {
    /*
    The address encoded using a bech32 format.
    */
    string addr = 1;
}

message Transaction {
    /*
    The raw serialized transaction.
    */
    bytes tx_hex = 1;

    /*
    An optional label to save with the transaction. Limited to 500 characters.
    */
    string label = 2;
}
message PublishResponse {
    /*
    If blank, then no error occurred and the transaction was successfully
    published. If not the empty string, then a string representation of the
    broadcast error.

    TODO(roasbeef): map to a proper enum type
    */
    string publish_error = 1;
}

message SendOutputsRequest {
    /*
    The number of satoshis per kilo weight that should be used when crafting
    this transaction.
    */
    int64 sat_per_kw = 1;

    /*
    A slice of the outputs that should be created in the transaction produced.
    */
    repeated signrpc.TxOut outputs = 2;

    // An optional label for the transaction, limited to 500 characters.
    string label = 3;

    // The minimum number of confirmations each one of your outputs used for
    // the transaction must satisfy.
    int32 min_confs = 4;

    // Whether unconfirmed outputs should be used as inputs for the transaction.
    bool spend_unconfirmed = 5;
}
message SendOutputsResponse {
    /*
    The serialized transaction sent out on the network.
    */
    bytes raw_tx = 1;
}

message EstimateFeeRequest {
    /*
    The number of confirmations to shoot for when estimating the fee.
    */
    int32 conf_target = 1;
}
message EstimateFeeResponse {
    /*
    The amount of satoshis per kw that should be used in order to reach the
    confirmation target in the request.
    */
    int64 sat_per_kw = 1;
}

enum WitnessType {
    UNKNOWN_WITNESS = 0;

    /*
    A witness that allows us to spend the output of a commitment transaction
    after a relative lock-time lockout.
    */
    COMMITMENT_TIME_LOCK = 1;

    /*
    A witness that allows us to spend a settled no-delay output immediately on a
    counterparty's commitment transaction.
    */
    COMMITMENT_NO_DELAY = 2;

    /*
    A witness that allows us to sweep the settled output of a malicious
    counterparty's who broadcasts a revoked commitment transaction.
    */
    COMMITMENT_REVOKE = 3;

    /*
    A witness that allows us to sweep an HTLC which we offered to the remote
    party in the case that they broadcast a revoked commitment state.
    */
    HTLC_OFFERED_REVOKE = 4;

    /*
    A witness that allows us to sweep an HTLC output sent to us in the case that
    the remote party broadcasts a revoked commitment state.
    */
    HTLC_ACCEPTED_REVOKE = 5;

    /*
    A witness that allows us to sweep an HTLC output that we extended to a
    party, but was never fulfilled.  This HTLC output isn't directly on the
    commitment transaction, but is the result of a confirmed second-level HTLC
    transaction. As a result, we can only spend this after a CSV delay.
    */
    HTLC_OFFERED_TIMEOUT_SECOND_LEVEL = 6;

    /*
    A witness that allows us to sweep an HTLC output that was offered to us, and
    for which we have a payment preimage. This HTLC output isn't directly on our
    commitment transaction, but is the result of confirmed second-level HTLC
    transaction. As a result, we can only spend this after a CSV delay.
    */
    HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL = 7;

    /*
    A witness that allows us to sweep an HTLC that we offered to the remote
    party which lies in the commitment transaction of the remote party. We can
    spend this output after the absolute CLTV timeout of the HTLC as passed.
    */
    HTLC_OFFERED_REMOTE_TIMEOUT = 8;

    /*
    A witness that allows us to sweep an HTLC that was offered to us by the
    remote party. We use this witness in the case that the remote party goes to
    chain, and we know the pre-image to the HTLC. We can sweep this without any
    additional timeout.
    */
    HTLC_ACCEPTED_REMOTE_SUCCESS = 9;

    /*
    A witness that allows us to sweep an HTLC from the remote party's commitment
    transaction in the case that the broadcast a revoked commitment, but then
    also immediately attempt to go to the second level to claim the HTLC.
    */
    HTLC_SECOND_LEVEL_REVOKE = 10;

    /*
    A witness type that allows us to spend a regular p2wkh output that's sent to
    an output which is under complete control of the backing wallet.
    */
    WITNESS_KEY_HASH = 11;

    /*
    A witness type that allows us to sweep an output that sends to a nested P2SH
    script that pays to a key solely under our control.
    */
    NESTED_WITNESS_KEY_HASH = 12;

    /*
    A witness type that allows us to spend our anchor on the commitment
    transaction.
    */
    COMMITMENT_ANCHOR = 13;
}

message PendingSweep {
    // The outpoint of the output we're attempting to sweep.
    lnrpc.OutPoint outpoint = 1;

    // The witness type of the output we're attempting to sweep.
    WitnessType witness_type = 2;

    // The value of the output we're attempting to sweep.
    uint32 amount_sat = 3;

    /*
    The fee rate we'll use to sweep the output. The fee rate is only determined
    once a sweeping transaction for the output is created, so it's possible for
    this to be 0 before this.
    */
    uint32 sat_per_byte = 4;

    // The number of broadcast attempts we've made to sweep the output.
    uint32 broadcast_attempts = 5;

    /*
    The next height of the chain at which we'll attempt to broadcast the
    sweep transaction of the output.
    */
    uint32 next_broadcast_height = 6;

    // The requested confirmation target for this output.
    uint32 requested_conf_target = 8;

    // The requested fee rate, expressed in sat/byte, for this output.
    uint32 requested_sat_per_byte = 9;

    /*
    Whether this input must be force-swept. This means that it is swept even
    if it has a negative yield.
    */
    bool force = 7;
}

message PendingSweepsRequest {
}

message PendingSweepsResponse {
    /*
    The set of outputs currently being swept by lnd's central batching engine.
    */
    repeated PendingSweep pending_sweeps = 1;
}

message BumpFeeRequest {
    // The input we're attempting to bump the fee of.
    lnrpc.OutPoint outpoint = 1;

    // The target number of blocks that the input should be spent within.
    uint32 target_conf = 2;

    /*
    The fee rate, expressed in sat/byte, that should be used to spend the input
    with.
    */
    uint32 sat_per_byte = 3;

    /*
    Whether this input must be force-swept. This means that it is swept even
    if it has a negative yield.
    */
    bool force = 4;
}

message BumpFeeResponse {
}

message ListSweepsRequest {
    /*
    Retrieve the full sweep transaction details. If false, only the sweep txids
    will be returned. Note that some sweeps that LND publishes will have been
    replaced-by-fee, so will not be included in this output.
    */
    bool verbose = 1;
}

message ListSweepsResponse {
    message TransactionIDs {
        /*
        Reversed, hex-encoded string representing the transaction ids of the
        sweeps that our node has broadcast. Note that these transactions may
        not have confirmed yet, we record sweeps on broadcast, not confirmation.
        */
        repeated string transaction_ids = 1;
    }

    oneof sweeps {
        lnrpc.TransactionDetails transaction_details = 1;
        TransactionIDs transaction_ids = 2;
    }
}

message LabelTransactionRequest {
    // The txid of the transaction to label.
    bytes txid = 1;

    // The label to add to the transaction, limited to 500 characters.
    string label = 2;

    // Whether to overwrite the existing label, if it is present.
    bool overwrite = 3;
}

message LabelTransactionResponse {
}

message FundPsbtRequest {
    oneof template {
        /*
        Use an existing PSBT packet as the template for the funded PSBT.

        The packet must contain at least one non-dust output. If one or more
        inputs are specified, no coin selection is performed. In that case every
        input must be an UTXO known to the wallet that has not been locked
        before. The sum of all inputs must be sufficiently greater than the sum
        of all outputs to pay a miner fee with the specified fee rate. A change
        output is added to the PSBT if necessary.
        */
        bytes psbt = 1;

        /*
        Use the outputs and optional inputs from this raw template.
        */
        TxTemplate raw = 2;
    }

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

        /*
        The fee rate, expressed in sat/vbyte, that should be used to spend the
        input with.
        */
        uint32 sat_per_vbyte = 4;
    }
}
message FundPsbtResponse {
    /*
    The funded but not yet signed PSBT packet.
    */
    bytes funded_psbt = 1;

    /*
    The index of the added change output or -1 if no change was left over.
    */
    int32 change_output_index = 2;

    /*
    The list of lock leases that were acquired for the inputs in the funded PSBT
    packet.
    */
    repeated UtxoLease locked_utxos = 3;
}

message TxTemplate {
    /*
    An optional list of inputs to use. Every input must be an UTXO known to the
    wallet that has not been locked before. The sum of all inputs must be
    sufficiently greater than the sum of all outputs to pay a miner fee with the
    fee rate specified in the parent message.

    If no inputs are specified, coin selection will be performed instead and
    inputs of sufficient value will be added to the resulting PSBT.
    */
    repeated lnrpc.OutPoint inputs = 1;

    /*
    A map of all addresses and the amounts to send to in the funded PSBT.
    */
    map<string, uint64> outputs = 2;
}

message UtxoLease {
    /*
    A 32 byte random ID that identifies the lease.
    */
    bytes id = 1;

    // The identifying outpoint of the output being leased.
    lnrpc.OutPoint outpoint = 2;

    /*
    The absolute expiration of the output lease represented as a unix timestamp.
    */
    uint64 expiration = 3;
}

message FinalizePsbtRequest {
    /*
    A PSBT that should be signed and finalized. The PSBT must contain all
    required inputs, outputs, UTXO data and partial signatures of all other
    signers.
    */
    bytes funded_psbt = 1;
}
message FinalizePsbtResponse {
    // The fully signed and finalized transaction in PSBT format.
    bytes signed_psbt = 1;

    // The fully signed and finalized transaction in the raw wire format.
    bytes raw_final_tx = 2;
}