Package org.bitcoinj.wallet

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

      • tx

        public final 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 AesKey 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.

      • 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​(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.

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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object