org.bitcoinj.wallet

Class SendRequest

java.lang.Object

org.bitcoinj.wallet.SendRequest

public class SendRequest
extends java.lang.Object

A SendRequest gives the wallet information about precisely how to send money to a recipient or set of recipients. Static methods are provided to help you create SendRequests and there are a few helper methods on the wallet that just simplify the most common use cases. You may wish to customize a SendRequest if you want to attach a fee or modify the change address.

Field Summary

Fields

Modifier and Type	Field and Description
org.bouncycastle.crypto.params.KeyParameter	aesKey The AES key to use to decrypt the private keys before signing.
Address	changeAddress "Change" means the difference between the value gathered by a transactions inputs (the size of which you don't really control as it depends on who sent you money), and the value being sent somewhere else.
CoinSelector	coinSelector If not null, the CoinSelector to use instead of the wallets default.
boolean	emptyWallet When emptyWallet is set, all coins selected by the coin selector are sent to the first output in tx (its value is ignored and set to Wallet.getBalance() - the fees required for the transaction).
boolean	ensureMinRequiredFee Requires that there be enough fee for a default Bitcoin Core to at least relay the transaction.
ExchangeRate	exchangeRate If not null, this exchange rate is recorded with the transaction during completion.
Coin	feePerKb A transaction can have a fee attached, which is defined as the difference between the input values and output values.
java.lang.String	memo If not null, this memo is recorded with the transaction during completion.
Wallet.MissingSigsMode	missingSigsMode Specifies what to do with missing signatures left after completing this request.
boolean	recipientsPayFees If false (default value), tx fee is paid by the sender If true, tx fee is paid by the recipient/s.
boolean	shuffleOutputs If true (the default), the outputs will be shuffled during completion to randomize the location of the change output, if any.
boolean	signInputs If true (the default), the inputs will be signed.
Transaction	tx A transaction, probably incomplete, that describes the outline of what you want to do.

Method Summary

Modifier and Type	Method and Description
void	allowUnconfirmed() Shortcut for req.coinSelector = AllowUnconfirmedCoinSelector.get();.
static SendRequest	childPaysForParent(Wallet wallet, Transaction parentTransaction, Coin feeRaise) Construct a SendRequest for a CPFP (child-pays-for-parent) transaction.
static SendRequest	emptyWallet(Address destination)
static SendRequest	forTx(Transaction tx) Simply wraps a pre-built incomplete transaction provided by you.
SendRequest	fromPaymentDetails(Protos.PaymentDetails paymentDetails) Copy data from payment request.
void	setFeePerVkb(Coin feePerVkb)
static SendRequest	to(Address destination, Coin value) Creates a new SendRequest to the given address for the given value.
static SendRequest	to(NetworkParameters params, ECKey destination, Coin value) Creates a new SendRequest to the given pubkey for the given value.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

tx

public Transaction tx

A transaction, probably incomplete, that describes the outline of what you want to do. This typically will mean it has some outputs to the intended destinations, but no inputs or change address (and therefore no fees) - the wallet will calculate all that for you and update tx later.

Be careful when adding outputs that you check the min output value (TransactionOutput.getMinNonDustValue(Coin)) to avoid the whole transaction being rejected because one output is dust.

If there are already inputs to the transaction, make sure their out point has a connected output, otherwise their value will be added to fee. Also ensure they are either signed or are spendable by a wallet key, otherwise the behavior of Wallet.completeTx(SendRequest) is undefined (likely RuntimeException).

emptyWallet

public boolean emptyWallet

When emptyWallet is set, all coins selected by the coin selector are sent to the first output in tx (its value is ignored and set to Wallet.getBalance() - the fees required for the transaction). Any additional outputs are removed.

changeAddress

public Address changeAddress

"Change" means the difference between the value gathered by a transactions inputs (the size of which you don't really control as it depends on who sent you money), and the value being sent somewhere else. The change address should be selected from this wallet, normally. If null this will be chosen for you.

feePerKb

public Coin feePerKb

A transaction can have a fee attached, which is defined as the difference between the input values and output values. Any value taken in that is not provided to an output can be claimed by a miner. This is how mining is incentivized in later years of the Bitcoin system when inflation drops. It also provides a way for people to prioritize their transactions over others and is used as a way to make denial of service attacks expensive.

This is a dynamic fee (in satoshis) which will be added to the transaction for each virtual kilobyte in size including the first. This is useful as as miners usually sort pending transactions by their fee per unit size when choosing which transactions to add to a block. Note that, to keep this equivalent to Bitcoin Core definition, a virtual kilobyte is defined as 1000 virtual bytes, not 1024.

ensureMinRequiredFee

public boolean ensureMinRequiredFee

Requires that there be enough fee for a default Bitcoin Core to at least relay the transaction. (ie ensure the transaction will not be outright rejected by the network). Defaults to true, you should only set this to false if you know what you're doing.

Note that this does not enforce certain fee rules that only apply to transactions which are larger than 26,000 bytes. If you get a transaction which is that large, you should set a feePerKb of at least Transaction.REFERENCE_DEFAULT_MIN_TX_FEE.

signInputs

public boolean signInputs

If true (the default), the inputs will be signed.

aesKey

public org.bouncycastle.crypto.params.KeyParameter aesKey

The AES key to use to decrypt the private keys before signing. If null then no decryption will be performed and if decryption is required an exception will be thrown. You can get this from a password by doing wallet.getKeyCrypter().deriveKey(password).

coinSelector

public CoinSelector coinSelector

If not null, the CoinSelector to use instead of the wallets default. Coin selectors are responsible for choosing which transaction outputs (coins) in a wallet to use given the desired send value amount.

shuffleOutputs

public boolean shuffleOutputs

If true (the default), the outputs will be shuffled during completion to randomize the location of the change output, if any. This is normally what you want for privacy reasons but in unit tests it can be annoying so it can be disabled here.

missingSigsMode

public Wallet.MissingSigsMode missingSigsMode

Specifies what to do with missing signatures left after completing this request. Default strategy is to throw an exception on missing signature (Wallet.MissingSigsMode.THROW).

See Also:

Wallet.MissingSigsMode

exchangeRate

public ExchangeRate exchangeRate

If not null, this exchange rate is recorded with the transaction during completion.

memo

public java.lang.String memo

If not null, this memo is recorded with the transaction during completion. It can be used to record the memo of the payment request that initiated the transaction.

recipientsPayFees

public boolean recipientsPayFees

If false (default value), tx fee is paid by the sender If true, tx fee is paid by the recipient/s. If there is more than one recipient, the tx fee is split equally between them regardless of output value and size.

Method Detail

setFeePerVkb

public void setFeePerVkb(Coin feePerVkb)

allowUnconfirmed

public void allowUnconfirmed()

Shortcut for req.coinSelector = AllowUnconfirmedCoinSelector.get();.

to

public static SendRequest to(Address destination,
                             Coin value)

Creates a new SendRequest to the given address for the given value.

Be careful to check the output's value is reasonable using TransactionOutput.getMinNonDustValue(Coin) afterwards or you risk having the transaction rejected by the network.

to

public static SendRequest to(NetworkParameters params,
                             ECKey destination,
                             Coin value)

Creates a new SendRequest to the given pubkey for the given value.

Be careful to check the output's value is reasonable using TransactionOutput.getMinNonDustValue(Coin) afterwards or you risk having the transaction rejected by the network. Note that using to(Address, Coin) will result in a smaller output, and thus the ability to use a smaller output value without rejection.

forTx

public static SendRequest forTx(Transaction tx)

Simply wraps a pre-built incomplete transaction provided by you.

emptyWallet

public static SendRequest emptyWallet(Address destination)

childPaysForParent

public static SendRequest childPaysForParent(Wallet wallet,
                                             Transaction parentTransaction,
                                             Coin feeRaise)

Construct a SendRequest for a CPFP (child-pays-for-parent) transaction. The resulting transaction is already completed, so you should directly proceed to signing and broadcasting/committing the transaction. CPFP is currently only supported by a few miners, so use with care.

fromPaymentDetails

public SendRequest fromPaymentDetails(Protos.PaymentDetails paymentDetails)

Copy data from payment request.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object