liana/doc/API.md

Liana daemon API

lianad exposes a JSON-RPC 2.0 interface over a Unix Domain socket.

Commands must be sent as valid JSONRPC 2.0 requests, ending with a \n.

Command	Description
stop	Stops liana daemon
getinfo	Get general information about the daemon
updatederivationindexes	Update last generated addresses derivation indexes
getnewaddress	Get a new receiving address
listaddresses	List addresses given start_index and count
listrevealedaddresses	List revealed addresses (both used and unused)
listcoins	List all wallet transaction outputs.
createspend	Create a new Spend transaction
updatespend	Store a created Spend transaction
listspendtxs	List all stored Spend transactions
delspendtx	Delete a stored Spend transaction
broadcastspend	Finalize a stored Spend PSBT, and broadcast it
rbfpsbt	Create a new RBF Spend transaction
startrescan	Start rescanning the block chain from a given date
listconfirmed	List of confirmed transactions of incoming and outgoing funds
listtransactions	List of transactions with the given txids
createrecovery	Create a recovery transaction to sweep expired coins
updatelabels	Update the labels
getlabels	Get the labels for the given addresses, txids and outpoints
getlabelsbip329	Get the labels in BIP-0329 format

Reference

General

stop

Stops the Liana daemon.

Response

Returns an empty response.

Field	Type	Description

getinfo

General information about the daemon

Request

This command does not take any parameter for now.

Field	Type	Description

Response

Field	Type	Description
version	string	Version following the SimVer format
network	string	Answer can be mainnet, testnet, regtest
block_height	integer	The block height we are synced at.
sync	float	The synchronization progress as percentage (0 < sync < 1)
descriptors	object	Object with the name of the descriptor as key and the descriptor string as value
rescan_progress	float or null	Progress of an ongoing rescan as a percentage (between 0 and 1) if there is any
timestamp	integer	Unix timestamp of wallet creation date
last_poll_timestamp	integer or null	Unix timestamp of last poll (if any) of the blockchain
receive_index	integer	Last index used to generate a receive address
change_index	integer	Last index used to generate a change address

updatederivationindexes

Updates the last generated address derivation indexes in the wallet database. At least one of the receive or change arguments is required.

Derivation indexes must be unhardened. If a provided index is lower than the one currently stored in the database, it will be ignored.

Note: Each time a derivation index in the database is incremented, the corresponding new addresses must be inserted into the database. To prevent excessive increments, there is a limit: the derivation index can only be incremented by a maximum of 1000 from its current value.

The updated indexes will be returned in the response.

Request

Field	Type	Description
receive	integer(optional)	The latest receive address derivation index to update
change	integer(optional)	The latest change address derivation index to update

Response

Field	Type	Description
receive	integer	The updated receive address derivation index
change	integer	The updated change address derivation index

getnewaddress

Get a new address for receiving coins. This will always generate a new address regardless of whether it was used or not.

Request

This command does not take any parameter for now.

Field	Type	Description

Response

Field	Type	Description
address	string	A Bitcoin address
derivation_index	integer	The derivation index for this address

listaddresses

List receive and change addresses given start_index and count. Both arguments are optional. Default value for start_index is 0. If no value is passed for count the maximum generated index between receive and change is selected.

Request

Field	Type	Description
start_index	integer(optional)	Index of the first address to list
count	integer(optional)	Number of addresses to list

Response

Field	Type	Description
index	integer	Derivation index
receive	string	Receive address
change	string	Change address

listrevealedaddresses

List revealed receive or change addresses, optionally filtering for those that are unused by any of the current coins in the wallet.

Addresses are returned in order of descending derivation index.

If start_index is omitted or null, then addresses will be returned starting from the last revealed address. Otherwise, addresses will be returned starting from the specified derivation index.

Request

Field	Type	Description
is_change	bool	Whether to return change or otherwise receive addresses.
exclude_used	bool	Whether to exclude those addresses that have been used by a current coin in the wallet.
limit	integer	The maximum number of addresses to list.
start_index	integer(optional)	For pagination, pass the continue_from value from the previous response.

Response

The response contains two fields:

• addresses: an array of revealed addresses, with the structure given below.
• continue_from: used for pagination of results. If not null, this indicates that there may be additional addresses that can be listed and this value can be passed to the next request as start_index to continue with the next page of results.

Each element in the addresses array has the following fields:

Field	Type	Description
index	integer	Derivation index.
address	string	Address.
used_count	integer	The number of current coins in the wallet that are using this address.
label	string or null	Address label, if any.

listcoins

List all our transaction outputs, optionally filtered by status and/or outpoint.

Request

Field	Type	Description
statuses	list of string	List of statuses to filter coins by (see below).
outpoints	list of string	List of outpoints to filter coins by, as txid:vout.

A coin may have one of the following four statuses:

• unconfirmed: deposit transaction has not yet been included in a block and coin has not been included in a spend transaction
• confirmed: deposit transaction has been included in a block and coin has not been included in a spend transaction
• spending: coin (whose deposit transaction may not yet have been confirmed) has been included in an unconfirmed spend transaction
• spent: coin has been included in a confirmed spend transaction

Response

Field	Type	Description
address	string	Address containing the script pubkey of the coin
amount	int	Value of the TxO in satoshis.
derivation_index	int	Derivation index used to create the coin deposit address.
outpoint	string	Transaction id and output index of this coin.
block_height	int or null	Block height the transaction was confirmed at, or null.
spend_info	object	Information about the transaction spending this coin. See Spending transaction info.
is_immature	bool	Whether this coin was created by a coinbase transaction that is still immature.
is_change	bool	Whether the coin deposit address was derived from the change descriptor.
is_from_self	bool	Whether the coin and all its unconfirmed ancestors, if any, are outputs of transactions from this wallet.

Spending transaction info

Field	Type	Description
txid	str	Spending transaction's id.
height	int or null	Block height the spending tx was included at, if confirmed.

createspend

Create a transaction spending one or more of our coins. All coins must exist and not be spent.

If no coins are specified in outpoints, they will be selected automatically from the set of confirmed coins together with any unconfirmed coins that are change outputs (see listcoins for coin status definitions).

Will error if the given coins are not sufficient to cover the transaction cost at 90% (or more) of the given feerate. If on the contrary the transaction is more than sufficiently funded, it will create a change output when economically rationale to do so.

You can create a send-to-self transaction by not specifying any destination. This command will create a single change output. This may be useful to "refresh" coins whose timelocked recovery path may be close to expiry without having to bear the complexity of computing the correct amount for the change output.

The optional change_address parameter allows the caller to specify what address to use for the leftover funds after all destinations have been set. This can be used to "sweep" the wallet: use all the unspent coins as input, set the other destination(s), if any, then set the change_address to the address of the wallet to sweep the funds to. Note however this output would only be created if there is enough remaining funds after sending to the specified destinations. This command WILL NOT ERROR if there isn't enough leftover funds to create the change/sweep output.

This command will refuse to create any output worth less than 5k sats.

Request

Field	Type	Description
destinations	object	Map from Bitcoin address to value.
outpoints	list of string	List of the coins to be spent, as txid:vout.
feerate	integer	Target feerate for the transaction, in satoshis per virtual byte.
change_address	string	Address to be used for leftover amount, if any.

Response

If the spend is created successfully, the following response will be received:

Field	Type	Description
psbt	string	PSBT of the spending transaction, encoded as base64.
warnings	list of string	Warnings, if any, generated during spend creation.

If there are insufficient funds to create the required spend, then the following response will be received:

Field	Type	Description
missing	integer	Additional sats required to create the spend.

updatespend

Store the PSBT of a Spend transaction in database, updating it if it already exists.

Will merge the partial signatures for all inputs if a PSBT for a transaction with the same txid exists in DB.

Request

Field	Type	Description
psbt	string	Base64-encoded PSBT of a Spend transaction.

Response

This command does not return anything for now.

Field	Type	Description

listspendtxs

List stored Spend transactions.

If txids is specified, only list transactions whose txid is in txids(empty list of txids is not allowed).

Request

Field	Type	Description
txids	array of string (optional)	Ids of the transactions to retrieve

Response

Field	Type	Description
spend_txs	array	Array of Spend tx entries

Spend tx entry

Field	Type	Description
psbt	string	Base64-encoded PSBT of the Spend transaction.
updated_at	int or null	UNIX timestamp of the last time this PSBT was updated.

delspendtx

Request

Field	Type	Description
txid	string	Hex encoded txid of the Spend transaction to delete

Response

This command does not return anything for now.

Field	Type	Description

broadcastspend

Request

Field	Type	Description
txid	string	Hex encoded txid of the Spend transaction to broadcast

Response

This command does not return anything for now.

Field	Type	Description

rbfpsbt

Create PSBT to replace, using RBF, the given transaction, which must either point to a PSBT in our database (not necessarily broadcast) or an unconfirmed spend transaction (whether or not any associated PSBT is saved in our database).

This command can be used to either:

• "cancel" the transaction: the replacement will include at least one input from the previous transaction and will have only a single output (change).
• bump the fee: the replacement will include all inputs from the previous transaction and all non-change outputs will be kept the same, with only the change amount being modified as required.

In both cases, the replacement transaction may include additional confirmed coins as inputs if required in order to pay the higher fee (this applies also when replacing a self-send).

If the transaction includes a change output to one of our own change addresses, this same address will be used for change in the replacement transaction, if required.

If the transaction pays to more than one of our change addresses, then the one receiving the highest value will be used as a change address in the replacement and the others will be treated as non-change outputs (i.e. removed for cancel or otherwise kept the same).

If feerate is not passed to the command, the target feerate of the replacement will be set to the minimum value allowed in order to replace this transaction using RBF (see https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md#current-replace-by-fee-policy for further details about this and other conditions that must be satisfied when using RBF).

Request

Field	Type	Description
txid	string	Hex encoded txid of the Spend transaction to be replaced.
is_cancel	bool	Whether to "cancel" the transaction or simply bump the fee.
feerate	integer(optional)	Target feerate for the RBF transaction (in sat/vb).

Response

The response is the same as for createspend.

startrescan

Request

Field	Type	Description
timestamp	int	Date to start rescanning from, as a UNIX timestamp

Response

This command does not return anything for now.

Field	Type	Description

listconfirmed

listconfirmed retrieves a paginated and ordered list of transactions that were confirmed within a given time window. Confirmation time is based on the timestamp of blocks.

Request

Field	Type	Description
start	int	Inclusive lower bound of the time window
end	int	Inclusive upper bound of the time window
limit	int	Maximum number of transactions to retrieve

Response

Field	Type	Description
transactions	array	Array of Transaction resource

Transaction Resource

Field	Type	Description
height	int or null	Block height of the transaction, null if the transaction is unconfirmed
time	int or null	Block time of the transaction, null if the transaction is unconfirmed
tx	string	hex encoded bitcoin transaction

listtransactions

listtransactions retrieves the transactions with the given txids.

Request

Field	Type	Description
txids	array of string	Ids of the transactions to retrieve

Response

Field	Type	Description
transactions	array	Array of Transaction resource

createrecovery

Create a transaction that sweeps coins using a timelocked recovery path to a provided address with the provided feerate.

If outpoints is empty or missing, then all coins for which the given recovery path is currently available will be used. Otherwise, only those specified will be considered. An error will be returned if any coins specified by outpoints are unknown, already spent or otherwise not currently recoverable using the given recovery path.

The timelock parameter can be used to specify which recovery path to use. By default, we'll use the first recovery path available. If created for a later timelock a recovery transaction may be satisfied using an earlier timelock but not the opposite.

Due to the fact coins are generally received at different block heights, not all coins may be spendable through a single recovery path at the same time.

This command will error if no such coins are available or the sum of their value is not enough to cover the requested feerate.

Request

Field	Type	Description
address	str	The Bitcoin address to sweep the coins to.
feerate	integer	Target feerate for the transaction, in satoshis per virtual byte.
timelock	int (optional)	Recovery path to be used, identified by the number of blocks after which it is available.
outpoints	list of str (optional)	List of the coins to be recovered, as txid:vout.

Response

Field	Type	Description
psbt	string	PSBT of the recovery transaction, encoded as base64.

updatelabels

Update the labels from a given map of key/value, with the labelled bitcoin addresses, txids and outpoints as keys and the label as value. If a label already exists for the given item, the new label overrides the previous one. If a null value is passed, the label is deleted.

Request

Field	Type	Description
labels	object	A mapping from an item to be labelled (an address, a txid or an outpoint) to a label string (at most 100 chars long).

getlabels

Retrieve a map of items and their respective labels from a list of addresses, txids and outpoints. Items without labels are not present in the response map.

Request

Field	Type	Description
items	string array	Items (address, txid or outpoint) of which to fetch the label.

Response

Field	Type	Description
labels	object	A mapping of bitcoin addresses, txids and outpoints as keys, and string as values

getlabelsbip329

Retrieve a list of labels in BIP-0329 format, with pagination support.

Request

Field	Type	Description
offset	integer	Index to start returning labels from
limit	integer	Maximum number of labels to return

Response

Field	Type	Description
labels	array	A list of BIP-0329-formatted label objects