com.google.bitcoin.core
Class Wallet.SendRequest

java.lang.Object
  com.google.bitcoin.core.Wallet.SendRequest

Enclosing class:

Wallet

public static class Wallet.SendRequest
extends 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

org.spongycastle.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.
static BigInteger	DEFAULT_FEE_PER_KB If you want to modify the default fee for your entire app without having to change each SendRequest you make, you can do it here.
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 reference client to at least relay the transaction.
BigInteger	fee A transaction can have a fee attached, which is defined as the difference between the input values and output values.
BigInteger	feePerKb A transaction can have a fee attached, which is defined as the difference between the input values and output values.
Transaction	tx A transaction, probably incomplete, that describes the outline of what you want to do.

Method Summary

static Wallet.SendRequest	emptyWallet(Address destination)
static Wallet.SendRequest	forTx(Transaction tx) Simply wraps a pre-built incomplete transaction provided by you.
static Wallet.SendRequest	to(Address destination, BigInteger value) Creates a new SendRequest to the given address for the given value.
static Wallet.SendRequest	to(NetworkParameters params, ECKey destination, BigInteger value) Creates a new SendRequest to the given pubkey for the given value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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(BigInteger)) 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(Wallet.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.

fee

public BigInteger fee

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 constant fee (in satoshis) which will be added to the transaction. It is recommended that it be at least Transaction.REFERENCE_DEFAULT_MIN_TX_FEE if it is set, as default reference clients will otherwise simply treat the transaction as if there were no fee at all.

Once Wallet.completeTx(com.google.bitcoin.core.Wallet.SendRequest) is called, this is set to the value of the fee that was added.

You might also consider adding a feePerKb to set the fee per kb of transaction size (rounded down to the nearest kb) as that is how transactions are sorted when added to a block by miners.

feePerKb

public BigInteger 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 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 the reference client definition, a kilobyte is defined as 1000 bytes, not 1024.

You might also consider using a fee to set the fee added for the first kb of size.

DEFAULT_FEE_PER_KB

public static BigInteger DEFAULT_FEE_PER_KB

If you want to modify the default fee for your entire app without having to change each SendRequest you make, you can do it here. This is primarily useful for unit tests.

ensureMinRequiredFee

public boolean ensureMinRequiredFee

Requires that there be enough fee for a default reference client 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 fee and feePerKb of at least Transaction.REFERENCE_DEFAULT_MIN_TX_FEE.

aesKey

public org.spongycastle.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.

Method Detail

to

public static Wallet.SendRequest to(Address destination,
                                    BigInteger value)

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

Be very careful when value is smaller than Transaction.MIN_NONDUST_OUTPUT as the transaction will likely be rejected by the network in this case.

to

public static Wallet.SendRequest to(NetworkParameters params,
                                    ECKey destination,
                                    BigInteger 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(BigInteger) afterwards or you risk having the transaction rejected by the network. Note that using to(Address, java.math.BigInteger) will result in a smaller output, and thus the ability to use a smaller output value without rejection.

forTx

public static Wallet.SendRequest forTx(Transaction tx)

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

emptyWallet

public static Wallet.SendRequest emptyWallet(Address destination)