FundPsbt

FundPsbt creates a fully populated PSBT that contains enough inputs to fund the outputs specified in the template. There are three ways a user can specify what we call the template (a list of inputs and outputs to use in the PSBT): Either as a PSBT packet directly with no coin selection (using the legacy "psbt" field), a PSBT with advanced coin selection support (using the new "coin_select" field) or as a raw RPC message (using the "raw" field). The legacy "psbt" and "raw" modes, the following restrictions apply:

1. If there are no inputs specified in the template, coin selection is performed automatically.
2. 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.

The new "coin_select" mode does not have these restrictions and allows the user to specify a PSBT with inputs and outputs and still perform coin selection on top of that. For all modes this RPC requires any inputs that are specified to be locked by the user (if they belong to this node in the first place).

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.

Source: walletrpc/walletkit.proto

gRPC

rpc FundPsbt (FundPsbtRequest) returns (FundPsbtResponse);

REST

HTTP Method	Path
POST	/v2/wallet/psbt/fund

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'walletrpc/walletkit.proto'], loaderOptions);
const walletrpc = grpc.loadPackageDefinition(packageDefinition).walletrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new walletrpc.WalletKit(GRPC_HOST, creds);
let request = {
  psbt: <bytes>,
  raw: <TxTemplate>,
  coin_select: <PsbtCoinSelect>,
  target_conf: <uint32>,
  sat_per_vbyte: <uint64>,
  sat_per_kw: <uint64>,
  account: <string>,
  min_confs: <int32>,
  spend_unconfirmed: <bool>,
  change_type: <ChangeAddressType>,
  coin_selection_strategy: <CoinSelectionStrategy>,
  max_fee_ratio: <double>,
};
client.fundPsbt(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "funded_psbt": <bytes>,
//    "change_output_index": <int32>,
//    "locked_utxos": <UtxoLease>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletrpc/walletkit.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletkit_pb2 as walletrpc, walletkit_pb2_grpc as walletkitstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = walletkitstub.WalletKitStub(channel)
request = walletrpc.FundPsbtRequest(
  psbt=<bytes>,
  raw=<TxTemplate>,
  coin_select=<PsbtCoinSelect>,
  target_conf=<uint32>,
  sat_per_vbyte=<uint64>,
  sat_per_kw=<uint64>,
  account=<string>,
  min_confs=<int32>,
  spend_unconfirmed=<bool>,
  change_type=<ChangeAddressType>,
  coin_selection_strategy=<CoinSelectionStrategy>,
  max_fee_ratio=<double>,
)
response = stub.FundPsbt(request)
print(response)
# {
#    "funded_psbt": <bytes>,
#    "change_output_index": <int32>,
#    "locked_utxos": <UtxoLease>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  psbt: <string>, // <bytes> (base64 encoded)
  raw: <object>, // <TxTemplate> 
  coin_select: <object>, // <PsbtCoinSelect> 
  target_conf: <integer>, // <uint32> 
  sat_per_vbyte: <string>, // <uint64> 
  sat_per_kw: <string>, // <uint64> 
  account: <string>, // <string> 
  min_confs: <integer>, // <int32> 
  spend_unconfirmed: <boolean>, // <bool> 
  change_type: <string>, // <ChangeAddressType> 
  coin_selection_strategy: <string>, // <CoinSelectionStrategy> 
  max_fee_ratio: <number>, // <double> 
};
let options = {
  url: `https://${REST_HOST}/v2/wallet/psbt/fund`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "funded_psbt": <string>, // <bytes> 
//    "change_output_index": <integer>, // <int32> 
//    "locked_utxos": <array>, // <UtxoLease> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/wallet/psbt/fund'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'psbt': base64.b64encode(<bytes>),
  'raw': <TxTemplate>,
  'coin_select': <PsbtCoinSelect>,
  'target_conf': <uint32>,
  'sat_per_vbyte': <uint64>,
  'sat_per_kw': <uint64>,
  'account': <string>,
  'min_confs': <int32>,
  'spend_unconfirmed': <bool>,
  'change_type': <ChangeAddressType>,
  'coin_selection_strategy': <CoinSelectionStrategy>,
  'max_fee_ratio': <double>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "funded_psbt": <bytes>,
#    "change_output_index": <int32>,
#    "locked_utxos": <UtxoLease>,
# }

Shell

$ lncli wallet psbt fund --help

NAME:
   lncli wallet psbt fund - Fund a Partially Signed Bitcoin Transaction (PSBT).

USAGE:
   lncli wallet psbt fund [command options] [--template_psbt=T | [--outputs=O [--inputs=I]]] [--conf_target=C | --sat_per_vbyte=S | --sat_per_kw=K] [--change_type=A]

DESCRIPTION:
   
  The fund command creates a fully populated PSBT that contains enough
  inputs to fund the outputs specified in either the PSBT or the
  --outputs flag.

  If there are no inputs specified in the template (or --inputs flag),
  coin selection is performed automatically. If inputs are specified, the
  wallet assumes that full coin selection happened externally and it will
  not add any additional inputs to the PSBT. 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.

  The 'outputs' flag decodes addresses and the amount to send respectively
  in the following JSON format:

      --outputs='{"ExampleAddr": NumCoinsInSatoshis, "SecondAddr": Sats}'

  The optional 'inputs' flag decodes a JSON list of UTXO outpoints as
  returned by the listunspent command for example:

      --inputs='["<txid1>:<output-index1>","<txid2>:<output-index2>",...]

  The optional '--change-type' flag permits to choose the address type
  for the change for default accounts and single imported public keys.
  The custom address type can only be p2tr at the moment (p2wkh will be
  used by default). No custom address type should be provided for custom
  accounts as we will always generate the change address using the coin
  selection key scope.
  

OPTIONS:
   --template_psbt value            the outputs to fund and optional inputs to spend provided in the base64 PSBT format
   --outputs value                  a JSON compatible map of destination addresses to amounts to send, must not include a change address as that will be added automatically by the wallet
   --inputs value                   an optional JSON compatible list of UTXO outpoints to use as the PSBT's inputs
   --conf_target value              the number of blocks that the transaction should be confirmed on-chain within (default: 6)
   --sat_per_vbyte value            a manual fee expressed in sat/vbyte that should be used when creating the transaction (default: 0)
   --sat_per_kw value               a manual fee expressed in sat/kw that should be used when creating the transaction (default: 0)
   --account value                  (optional) the name of the account to use to create/fund the PSBT
   --change_type value              (optional) the type of the change address to use to create/fund the PSBT. If no address type is provided, p2wpkh will be used for default accounts and single imported public keys. No custom address type should be provided for custom accounts as we will always use the coin selection key scope to generate the change address
   --min_confs value                (optional) the minimum number of confirmations each input used for the PSBT transaction must satisfy (default: 1)
   --coin_selection_strategy value  (optional) the strategy to use for selecting coins. Possible values are 'largest', 'random', or 'global-config'. If either 'largest' or 'random' is specified, it will override the globally configured strategy in lnd.conf (default: "global-config")
   --max_fee_ratio value            the maximum fee to total output amount ratio that this psbt should adhere to (default: 0.2)
   

Messages

walletrpc.FundPsbtRequest

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type	REST Placement
psbt 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	string	body
raw Use the outputs and optional inputs from this raw template.	TxTemplate	object	body
coin_select Use an existing PSBT packet as the template for the funded PSBT. The difference to the pure PSBT template above is that coin selection is performed even if inputs are specified. The output amounts are summed up and used as the target amount for coin selection. A change output must either already exist in the PSBT and be marked as such, otherwise a new change output of the specified output type will be added. Any inputs already specified in the PSBT must already be locked (if they belong to this node), only newly added inputs will be locked by this RPC. In case the sum of the already provided inputs exceeds the required output amount, no new coins are selected. Instead only the fee and change amount calculation is performed (e.g. a change output is added if requested or the change is added to the specified existing change output, given there is any non-dust change). This can be identified by the returned locked UTXOs being empty.	PsbtCoinSelect	object	body
target_conf The target number of blocks that the transaction should be confirmed in.	uint32	integer	body
sat_per_vbyte The fee rate, expressed in sat/vbyte, that should be used to spend the input with.	uint64	string	body
sat_per_kw The fee rate, expressed in sat/kWU, that should be used to spend the input with.	uint64	string	body
account The name of the account to fund the PSBT with. If empty, the default wallet account is used.	string	string	body
min_confs The minimum number of confirmations each one of your outputs used for the transaction must satisfy.	int32	integer	body
spend_unconfirmed Whether unconfirmed outputs should be used as inputs for the transaction.	bool	boolean	body
change_type The address type for the change. If empty, P2WPKH addresses will be used for default accounts and single imported public keys. For custom accounts, no change type should be provided as the coin selection key scope will always be used to generate the change address.	ChangeAddressType	string	body
coin_selection_strategy The strategy to use for selecting coins during funding the PSBT.	CoinSelectionStrategy	string	body
max_fee_ratio The max fee to total output amount ratio that this psbt should adhere to.	double	number	body

walletrpc.FundPsbtResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
funded_psbt The funded but not yet signed PSBT packet.	bytes	string
change_output_index The index of the added change output or -1 if no change was left over.	int32	integer
locked_utxos The list of lock leases that were acquired for the inputs in the funded PSBT packet. Only inputs added to the PSBT by this RPC are locked, inputs that were already present in the PSBT are not locked.	UtxoLease[]	array

Nested Messages

lnrpc.OutPoint

Field	gRPC Type	REST Type
txid_bytes Raw bytes representing the transaction id.	bytes	string
txid_str Reversed, hex-encoded string representing the transaction id.	string	string
output_index The index of the output on the transaction.	uint32	integer

walletrpc.PsbtCoinSelect

Field	gRPC Type	REST Type
psbt The template to use for the funded PSBT. The template must contain at least one non-dust output. The amount to be funded is calculated by summing up the amounts of all outputs in the template, subtracting all the input values of the already specified inputs. The change value is added to the output that is marked as such (or a new change output is added if none is marked). For the input amount calculation to be correct, the template must have the WitnessUtxo field set for all inputs. Any inputs already specified in the PSBT must already be locked (if they belong to this node), only newly added inputs will be locked by this RPC.	bytes	string
existing_output_index Use the existing output within the template PSBT with the specified index as the change output. Any leftover change will be added to the already specified amount of that output. To add a new change output to the PSBT, set the "add" field below instead. The type of change output added is defined by change_type in the parent message.	int32	integer
add Add a new change output to the PSBT using the change_type specified in the parent message.	bool	boolean

walletrpc.TxTemplate

Field	gRPC Type	REST Type
inputs 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.	OutPoint[]	array
outputs A map of all addresses and the amounts to send to in the funded PSBT.	OutputsEntry[]	object

walletrpc.TxTemplate.OutputsEntry

Field	gRPC Type	REST Type
key	string	unknown
value	uint64	unknown

walletrpc.UtxoLease

Field	gRPC Type	REST Type
id A 32 byte random ID that identifies the lease.	bytes	string
outpoint The identifying outpoint of the output being leased.	OutPoint	object
expiration The absolute expiration of the output lease represented as a unix timestamp.	uint64	string
pk_script The public key script of the leased output.	bytes	string
value The value of the leased output in satoshis.	uint64	string

Enums

lnrpc.CoinSelectionStrategy

Name	Number
STRATEGY_USE_GLOBAL_CONFIG Use the coin selection strategy defined in the global configuration (lnd.conf).	0
STRATEGY_LARGEST Select the largest available coins first during coin selection.	1
STRATEGY_RANDOM Randomly select the available coins during coin selection.	2

walletrpc.ChangeAddressType

Name	Number
CHANGE_ADDRESS_TYPE_UNSPECIFIED CHANGE_ADDRESS_TYPE_UNSPECIFIED indicates that no change address type is provided. We will then use P2WPKH address type for change (BIP0084 key scope).	0
CHANGE_ADDRESS_TYPE_P2TR CHANGE_ADDRESS_TYPE_P2TR indicates to use P2TR address for change output (BIP0086 key scope).	1