FundPsbt

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.

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>,
  target_conf: <uint32>,
  sat_per_vbyte: <uint64>,
  account: <string>,
  min_confs: <int32>,
  spend_unconfirmed: <bool>,
};
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>,
  target_conf=<uint32>,
  sat_per_vbyte=<uint64>,
  account=<string>,
  min_confs=<int32>,
  spend_unconfirmed=<bool>,
)
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> 
  target_conf: <integer>, // <uint32> 
  sat_per_vbyte: <string>, // <uint64> 
  account: <string>, // <string> 
  min_confs: <integer>, // <int32> 
  spend_unconfirmed: <boolean>, // <bool> 
};
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>,
  'target_conf': <uint32>,
  'sat_per_vbyte': <uint64>,
  'account': <string>,
  'min_confs': <int32>,
  'spend_unconfirmed': <bool>,
}
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

# There is no CLI command for this RPC

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
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
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

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.	UtxoLease[]	array

Nested Messages

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

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.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