package walletrpc
Get desktop application:
View/edit binary Protocol Buffers messages
service WalletKit
walletkit.proto:12WalletKit is a service that gives access to the core functionalities of the daemon's wallet.
rpc BumpFee (, )
walletkit.proto:163BumpFee 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.
message
walletkit.proto:672optional outpoint = 1
The input we're attempting to bump the fee of.
uint32 target_conf = 2
The target number of blocks that the input should be spent within.
uint32 sat_per_byte = 3
Deprecated, use sat_per_vbyte. The fee rate, expressed in sat/vbyte, that should be used to spend the input with.
bool force = 4
Whether this input must be force-swept. This means that it is swept even if it has a negative yield.
uint64 sat_per_vbyte = 5
The fee rate, expressed in sat/vbyte, that should be used to spend the input with.
message
walletkit.proto:699(message has no fields)
rpc DeriveKey (, )
walletkit.proto:51DeriveKey attempts to derive an arbitrary key specified by the passed KeyLocator.
rpc DeriveNextKey (, )
walletkit.proto:45DeriveNextKey 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.
message
walletkit.proto:283int32 key_finger_print = 1
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_family = 2
The target key family to derive a key from. In other contexts, this is known as the "account".
rpc EstimateFee (, )
walletkit.proto:122EstimateFee 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.
message
walletkit.proto:507int32 conf_target = 1
The number of confirmations to shoot for when estimating the fee.
message
walletkit.proto:513int64 sat_per_kw = 1
The amount of satoshis per kw that should be used in order to reach the confirmation target in the request.
rpc FinalizePsbt (, )
walletkit.proto:231FinalizePsbt 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.
message
walletkit.proto:851bytes funded_psbt = 1
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.
string account = 5
The name of the account to finalize the PSBT with. If empty, the default wallet account is used.
message
walletkit.proto:865bytes signed_psbt = 1
The fully signed and finalized transaction in PSBT format.
bytes raw_final_tx = 2
The fully signed and finalized transaction in the raw wire format.
rpc FundPsbt (, )
walletkit.proto:201FundPsbt 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.
message
walletkit.proto:741oneof template
bytes psbt = 1
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.
raw = 2
Use the outputs and optional inputs from this raw template.
oneof fees
uint32 target_conf = 3
The target number of blocks that the transaction should be confirmed in.
uint64 sat_per_vbyte = 4
The fee rate, expressed in sat/vbyte, that should be used to spend the input with.
string account = 5
The name of the account to fund the PSBT with. If empty, the default wallet account is used.
int32 min_confs = 6
The minimum number of confirmations each one of your outputs used for the transaction must satisfy.
bool spend_unconfirmed = 7
Whether unconfirmed outputs should be used as inputs for the transaction.
message
walletkit.proto:787bytes funded_psbt = 1
The funded but not yet signed PSBT packet.
int32 change_output_index = 2
The index of the added change output or -1 if no change was left over.
repeated locked_utxos = 3
The list of lock leases that were acquired for the inputs in the funded PSBT packet.
rpc ImportAccount (, )
walletkit.proto:90ImportAccount imports an account backed by an account extended public key. The master key fingerprint denotes the fingerprint of the root key corresponding to the account public key (also known as the key with derivation path m/). This may be required by some hardware wallets for proper identification and signing. The address type can usually be inferred from the key's version, but may be required for certain keys to map them into the proper scope. For BIP-0044 keys, an address type must be specified as we intend to not support importing BIP-0044 keys into the wallet using the legacy pay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will force the standard BIP-0049 derivation scheme, while a witness address type will force the standard BIP-0084 derivation scheme. For BIP-0049 keys, an address type must also be specified to make a distinction between the standard BIP-0049 address schema (nested witness pubkeys everywhere) and our own BIP-0049Plus address schema (nested pubkeys externally, witness pubkeys internally). NOTE: Events (deposits/spends) for keys derived from an account will only be detected by lnd if they happen after the import. Rescans to detect past events will be supported later on.
message
walletkit.proto:392string name = 1
A name to identify the account with.
string extended_public_key = 2
A public key that corresponds to a wallet account represented as an extended key. It must conform to a derivation path of the form m/purpose'/coin_type'/account'.
bytes master_key_fingerprint = 3
The fingerprint of the root key (also known as the key with derivation path m/) from which the account public key was derived from. This may be required by some hardware wallets for proper identification and signing. The bytes must be in big-endian order.
AddressType address_type = 4
An address type is only required when the extended account public key has a legacy version (xpub, tpub, etc.), such that the wallet cannot detect what address scheme it belongs to.
bool dry_run = 5
Whether a dry run should be attempted when importing the account. This serves as a way to confirm whether the account is being imported correctly by returning the first N addresses for the external and internal branches of the account. If these addresses match as expected, then it should be safe to import the account as is.
message
walletkit.proto:427optional account = 1
The details of the imported account.
repeated string dry_run_external_addrs = 2
The first N addresses that belong to the external branch of the account. The external branch is typically used for external non-change addresses. These are only returned if a dry run was specified within the request.
repeated string dry_run_internal_addrs = 3
The first N addresses that belong to the internal branch of the account. The internal branch is typically used for change addresses. These are only returned if a dry run was specified within the request.
rpc ImportPublicKey (, )
walletkit.proto:99ImportPublicKey imports a public key as watch-only into the wallet. NOTE: Events (deposits/spends) for a key will only be detected by lnd if they happen after the import. Rescans to detect past events will be supported later on.
message
walletkit.proto:446bytes public_key = 1
A compressed public key represented as raw bytes.
AddressType address_type = 2
The type of address that will be generated from the public key.
message
walletkit.proto:453(message has no fields)
rpc LabelTransaction (, )
walletkit.proto:178LabelTransaction 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.
message
walletkit.proto:727bytes txid = 1
The txid of the transaction to label.
string label = 2
The label to add to the transaction, limited to 500 characters.
bool overwrite = 3
Whether to overwrite the existing label, if it is present.
message
walletkit.proto:738(message has no fields)
rpc LeaseOutput (, )
walletkit.proto:26LeaseOutput 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`.
message
walletkit.proto:250bytes id = 1
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.
optional outpoint = 2
The identifying outpoint of the output being leased.
uint64 expiration_seconds = 3
The time in seconds before the lock expires. If set to zero, the default lock duration is used.
message
walletkit.proto:265uint64 expiration = 1
The absolute expiration of the output lease represented as a unix timestamp.
rpc ListAccounts (, )
walletkit.proto:63ListAccounts retrieves all accounts belonging to the wallet by default. A name and key scope filter can be provided to filter through all of the wallet accounts and return only those matching.
message
walletkit.proto:381string name = 1
An optional filter to only return accounts matching this name.
AddressType address_type = 2
An optional filter to only return accounts matching this address type.
message
walletkit.proto:388repeated accounts = 1
rpc ListLeases (, )
walletkit.proto:38ListLeases lists all currently locked utxos.
message
walletkit.proto:873(message has no fields)
message
walletkit.proto:876repeated locked_utxos = 1
The list of currently leased utxos.
rpc ListSweeps (, )
walletkit.proto:170ListSweeps 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.
message
walletkit.proto:702bool verbose = 1
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.
message
walletkit.proto:711oneof sweeps
transaction_details = 1
transaction_ids = 2
rpc ListUnspent (, )
walletkit.proto:17ListUnspent returns a list of all utxos spendable by the wallet with a number of confirmations between the specified minimum and maximum.
message
walletkit.proto:234int32 min_confs = 1
The minimum number of confirmations to be included.
int32 max_confs = 2
The maximum number of confirmations to be included.
string account = 3
An optional filter to only include outputs belonging to an account.
message
walletkit.proto:245repeated utxos = 1
A list of utxos satisfying the specified number of confirmations.
rpc NextAddr (, )
walletkit.proto:56NextAddr returns the next unused address within the wallet.
message
walletkit.proto:298string account = 1
The name of the account to retrieve the next address of. If empty, the default wallet account is used.
AddressType type = 2
The type of address to derive.
bool change = 3
Whether a change address should be derived.
message
walletkit.proto:315string addr = 1
The address encoded using a bech32 format.
rpc PendingSweeps (, )
walletkit.proto:134PendingSweeps 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.
message
walletkit.proto:662(message has no fields)
message
walletkit.proto:665repeated pending_sweeps = 1
The set of outputs currently being swept by lnd's central batching engine.
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.
message
walletkit.proto:456bytes tx_hex = 1
The raw serialized transaction.
string label = 2
An optional label to save with the transaction. Limited to 500 characters.
message
walletkit.proto:467string publish_error = 1
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
rpc ReleaseOutput (, )
walletkit.proto:33ReleaseOutput 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.
message
walletkit.proto:272bytes id = 1
The unique ID that was used to lock the output.
optional outpoint = 2
The identifying outpoint of the output being released.
message
walletkit.proto:280(message has no fields)
rpc SendOutputs (, )
walletkit.proto:115SendOutputs 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.
message
walletkit.proto:478int64 sat_per_kw = 1
The number of satoshis per kilo weight that should be used when crafting this transaction.
repeated outputs = 2
A slice of the outputs that should be created in the transaction produced.
string label = 3
An optional label for the transaction, limited to 500 characters.
int32 min_confs = 4
The minimum number of confirmations each one of your outputs used for the transaction must satisfy.
bool spend_unconfirmed = 5
Whether unconfirmed outputs should be used as inputs for the transaction.
message
walletkit.proto:500bytes raw_tx = 1
The serialized transaction sent out on the network.
rpc SignPsbt (, )
walletkit.proto:216SignPsbt expects a partial transaction with all inputs and outputs fully declared and tries to sign all unsigned inputs that have all required fields (UTXO information, BIP32 derivation information, witness or sig scripts) set. If no error is returned, the PSBT is ready to be given to the next signer or to be finalized if lnd was the last signer. NOTE: This RPC only signs inputs (and only those it can sign), it does not perform any other tasks (such as coin selection, UTXO locking or input/output/fee value validation, PSBT finalization). Any input that is incomplete will be skipped.
message
walletkit.proto:838bytes funded_psbt = 1
The PSBT that should be signed. The PSBT must contain all required inputs, outputs, UTXO data and custom fields required to identify the signing key.
message
walletkit.proto:846bytes signed_psbt = 1
The signed transaction in PSBT format.
message
walletkit.proto:328Used in: ,
string name = 1
The name used to identify the account.
AddressType address_type = 2
The type of addresses the account supports. AddressType | External Branch | Internal Branch --------------------------------------------------------------------- WITNESS_PUBKEY_HASH | P2WPKH | P2WPKH NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | NP2WPKH HYBRID_NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | P2WPKH
string extended_public_key = 3
The public key backing the account that all keys are derived from represented as an extended key. This will always be empty for the default imported account in which single public keys are imported into.
bytes master_key_fingerprint = 4
The fingerprint of the root key from which the account public key was derived from. This will always be zero for the default imported account in which single public keys are imported into. The bytes are in big-endian order.
string derivation_path = 5
The derivation path corresponding to the account public key. This will always be empty for the default imported account in which single public keys are imported into.
uint32 external_key_count = 6
The number of keys derived from the external branch of the account public key. This will always be zero for the default imported account in which single public keys are imported into.
uint32 internal_key_count = 7
The number of keys derived from the internal branch of the account public key. This will always be zero for the default imported account in which single public keys are imported into.
bool watch_only = 8
Whether the wallet stores private keys for the account.
Used in: , , , ,
UNKNOWN = 0
WITNESS_PUBKEY_HASH = 1
NESTED_WITNESS_PUBKEY_HASH = 2
HYBRID_NESTED_WITNESS_PUBKEY_HASH = 3
message
walletkit.proto:712Used in:
repeated string transaction_ids = 1
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.
message
walletkit.proto:611Used in:
optional outpoint = 1
The outpoint of the output we're attempting to sweep.
WitnessType witness_type = 2
The witness type of the output we're attempting to sweep.
uint32 amount_sat = 3
The value of the output we're attempting to sweep.
uint32 sat_per_byte = 4
Deprecated, use sat_per_vbyte. The fee rate we'll use to sweep the output, expressed in sat/vbyte. 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 broadcast_attempts = 5
The number of broadcast attempts we've made to sweep the output.
uint32 next_broadcast_height = 6
The next height of the chain at which we'll attempt to broadcast the sweep transaction of the output.
uint32 requested_conf_target = 8
The requested confirmation target for this output.
uint32 requested_sat_per_byte = 9
Deprecated, use requested_sat_per_vbyte. The requested fee rate, expressed in sat/vbyte, for this output.
uint64 sat_per_vbyte = 10
The fee rate we'll use to sweep the output, expressed in sat/vbyte. 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.
uint64 requested_sat_per_vbyte = 11
The requested fee rate, expressed in sat/vbyte, for this output.
bool force = 7
Whether this input must be force-swept. This means that it is swept even if it has a negative yield.
message
walletkit.proto:805Used in:
repeated inputs = 1
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.
map<string, uint64> outputs = 2
A map of all addresses and the amounts to send to in the funded PSBT.
message
walletkit.proto:823Used in: ,
bytes id = 1
A 32 byte random ID that identifies the lease.
optional outpoint = 2
The identifying outpoint of the output being leased.
uint64 expiration = 3
The absolute expiration of the output lease represented as a unix timestamp.
Used in:
UNKNOWN_WITNESS = 0
COMMITMENT_TIME_LOCK = 1
A witness that allows us to spend the output of a commitment transaction after a relative lock-time lockout.
COMMITMENT_NO_DELAY = 2
A witness that allows us to spend a settled no-delay output immediately on a counterparty's commitment transaction.
COMMITMENT_REVOKE = 3
A witness that allows us to sweep the settled output of a malicious counterparty's who broadcasts a revoked commitment transaction.
HTLC_OFFERED_REVOKE = 4
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_ACCEPTED_REVOKE = 5
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_OFFERED_TIMEOUT_SECOND_LEVEL = 6
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_ACCEPTED_SUCCESS_SECOND_LEVEL = 7
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_OFFERED_REMOTE_TIMEOUT = 8
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_ACCEPTED_REMOTE_SUCCESS = 9
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_SECOND_LEVEL_REVOKE = 10
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.
WITNESS_KEY_HASH = 11
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.
NESTED_WITNESS_KEY_HASH = 12
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.
COMMITMENT_ANCHOR = 13
A witness type that allows us to spend our anchor on the commitment transaction.