GDK Create Transaction JSON

This section details how to create various kinds of transaction using GA_create_transaction. Once created, the resulting JSON is generally passed to GA_blind_transaction (on Liquid) to blind its outputs. Following this it is passed to GA_sign_transaction to obtain signatures, then broadcast to the network via GA_send_transaction or GA_broadcast_transaction.

Overview

The caller passes details about the transaction they would like to construct. The returned JSON contains the resulting transaction and an "error" element which is either empty if the call succeeded in creating a valid transaction or contains an error code describing the problem.

Building transactions can be done iteratively, by passing the result of one call into the next after making changes to the returned JSON. This is useful for interactive transaction creation as it allows users to see the effect of changes such as different fee rates interactively, and to fix errors on the fly. Because gdk will create new change addresses when constructing transactions, passing the result of the last call to GA_create_transaction makes each call significantly faster and more efficient compared to passing in the initial JSON.

When using gdk as an integration solution, GA_create_transaction is generally only called once, and if an error occurs the operation is aborted.

Note that the returned JSON will contain additional elements beyond those documented here. The caller should not attempt to change these elements; the documented inputs are the only user-level changes that should be made, and the internal elements may change name or meaning from release to release.

Mandatory and Optional Elements

Only two elements are always mandatory: "addressees" and "utxos". A transaction sending some amount from the wallet can be created using e.g:

{
  "addressees": [ {} ],
  "utxos": { }
}

addressees:

Mandatory. An array of Addressee JSON elements, one for each recipient.

utxos:

Mandatory. The UTXOs to fund the transaction with, Unspent outputs JSON as returned by GA_get_unspent_outputs. Any UTXOs present are candidates for inclusion in the transaction.

Optional elements allow more precise control over the transaction:

fee_rate:

Defaults to the sessions default fee rate setting. The fee rate in satoshi per 1000 bytes to use for fee calculation.

utxo_strategy:

Defaults to "default". Set to "manual" for manual UTXO selection.

randomize_inputs:

Defaults to true. If set to true, the order of the used UTXOs in the created transaction is randomized.

is_partial:

Defaults to false. Used for creating partial/incomplete transactions such as half-swaps. If set to true, no change outputs will be created, fees will not be calculated or deducted from inputs, and the transaction inputs and outputs will not be expected to balance. Sets "randomize_inputs" to false. Consider using GA_create_swap_transaction instead of this element.

transaction_version:

Defaults to 2. The Bitcoin/Liquid transaction version to use.

transaction_locktime:

Defaults to The current block with occasional random variance for privacy. The transaction level locktime to use.

If you wish to customize a transaction further, consider creating a PSBT/PSET directly from the wallets inputs and using GA_psbt_sign to sign it.

Returned metadata

Some data returned when creating a transaction may be read by the user:

fee:

The transaction fee in satoshis.

error:

If not empty, the error description that prevented the transaction being created.

transaction:

The hex-encoded resulting transaction. This may be partially complete or contain dummy data, e.g. missing blinding data or signatures before it is fully completed and signed. The vsize and weight elements described below are adjusted with reasonable estimates for any missing data until the transaction is fully signed.

transaction_vsize:

The expected final vsize of the "transaction" in vbytes.

transaction_weight:

The expected final weight of "transaction" in segwit weight units.

calculated_fee_rate:

The expected fee rate for the final signed transaction. This may differ slightly from the requested "fee_rate" due to variance in the size of witness data such as signatures.

transaction_inputs:

An array of the "utxos" elements that are used by the transaction.

transaction_outputs:

The transaction output details for the outputs of the transaction.

Addressee JSON

Describes an intended recipient for a transaction.

{
  "address": "2NFHMw7GbqnQ3kTYMrA7MnHiYDyLy4EQH6b",
  "satoshi": 100000,
  "asset_id": "6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d",
  "is_greedy": false
}

address:

Mandatory. The address to send to. All address types for the network are supported. Additionally, BIP 21 URLs are supported along with the Liquid adaptation. Note that BIP 70 payment requests are not supported.

satoshi:

Normally mandatory. The amount to send to the recipient in satoshi. May be omitted when "is_greedy" is true.

asset_id:

Mandatory for Liquid, must not be present for Bitcoin. The asset to be sent to the recipient, in display hex format.

is_greedy:

Optional. If set to true, this addressee will consume any remaining value from UTXOs that match its "asset_id" (or all UTXOs in the case of Bitcoin). Only one greedy output per asset is allowed. When set to true, the value of the "satoshi" element is ignored and will be overwritten with the computed value.

Note

When an addressee represents a wallet address, the entire contents of the GA_get_receive_address call made to fetch the address must be passed. If only the address is provided, the addressee will be treated as an external addressee, and e.g. the summary values of the transaction in the top-level “satoshi” element will not be correct.

Coin selection

Callers can control the UTXOs used when creating a transaction. When using "utxo_strategy": "default", Bitcoin and Liquid-Bitcoin UTXOs are selected from the "utxos" element. The caller can reorder and filter these UTXOs using the query parameters to GA_get_unspent_outputs to control which UTXOs are used (and their ordering, if "randomize_inputs" is set to false). For asset UTXOs under Liquid, the default strategy attempts to select the minimum number of UTXOs to use without regard for their ordering in the "utxos" element.

For finer control, setting "utxo_strategy" to "manual" allows the UTXOs to be used to be placed directly into the "transaction_inputs" element by the caller. In this case, "utxos" is unused, and all given UTXOs will be added to the resulting transaction.

The sum of input UTXOs for a given asset must be sufficient to cover the amounts sent to any addressees receiving it, or an error will occur unless "is_partial" is true. Excess amounts will either be returned to the wallet as change, or if an addressee has "is_greedy" set to true then the remainder will be assigned to it. When "utxo_strategy" is set to "default", UTXOs from the "utxos" element will be omitted from the created transaction if they are not needed.

Finally, creating a PSBT/PSET and using GA_psbt_sign to sign it allows exact specification of all transaction details including UTXOs.

Re-deposit

A re-deposit is just a standard sending transaction with the addressee being an address from the users wallet as returned from GA_get_receive_address, and is_greedy" in the addressee being set to "true" to consume all of the UTXOs to redeposit.

Fee bump

A fee bump or RBF transaction increases the fee rate of an outgoing transaction that the caller has already submitted to the mempool, but which is not yet confirmed.

To create a fee bump, the caller should include the transaction to bump in the "previous_transaction" element. This must be in the format returned by GA_get_transactions. Additionally the new fee rate to bump to must be given in "fee_rate", and any additional UTXOs to be used for providing the funds for the fee increase given in "utxos".

{
  "previous_transaction": {},
  "fee_rate": 5000,
  "utxos": { }
}

previous_transaction:

The transaction to bump, as returned from Transaction list JSON.

fee_rate:

The new fee rate in satoshi per 1000 bytes to use for fee calculation. This must be higher than the existing fee rate in "previous_transaction".

Sweeping

A sweep transaction moves coins from an address with a known private key to another address. Unlike a simple send transaction, the coins to be moved are not associated with the users wallet in any way. Sweeping is typically used to move coins from a paper wallet into the users wallet.

To create a sweep transaction, use GA_get_unspent_outputs_for_private_key to fetch the unspent outputs to sweep. Including these in the "utxos" element when creating a transaction will automatically handle signing them.

Note that you should generally set "is_greedy" for one of the transaction addressees when sweeping to ensure that all of the UTXOs are spent together.

It is also possible to send the swept coin to an address that does not belong to the callers wallet. Currently it is not possible to include sweep inputs along with wallet inputs to combine spending.