org.bitcoinj.protocols.channels

Class PaymentChannelClient

java.lang.Object

org.bitcoinj.protocols.channels.PaymentChannelClient

All Implemented Interfaces:

IPaymentChannelClient

public class PaymentChannelClient
extends Object
implements IPaymentChannelClient

A class which handles most of the complexity of creating a payment channel connection by providing a simple in/out interface which is provided with protobufs from the server and which generates protobufs which should be sent to the server.

Does all required verification of server messages and properly stores state objects in the wallet-attached StoredPaymentChannelClientStates so that they are automatically closed when necessary and refund transactions are not lost if the application crashes before it unlocks.

Though this interface is largely designed with stateful protocols (eg simple TCP connections) in mind, it is also possible to use it with stateless protocols (eg sending protobufs when required over HTTP headers). In this case, the "connection" translates roughly into the server-client relationship. See the javadocs for specific functions for more details.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PaymentChannelClient.VersionSelector

Nested classes/interfaces inherited from interface org.bitcoinj.protocols.channels.IPaymentChannelClient

IPaymentChannelClient.ClientConnection, IPaymentChannelClient.Factory

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_TIME_WINDOW The default maximum amount of time for which we will accept the server locking up our funds for the multisig contract.
protected ReentrantLock	lock

Constructor Summary

Constructors

Constructor and Description
PaymentChannelClient(Wallet wallet, ECKey myKey, Coin maxValue, Sha256Hash serverId, IPaymentChannelClient.ClientConnection conn) Constructs a new channel manager which waits for connectionOpen() before acting.
PaymentChannelClient(Wallet wallet, ECKey myKey, Coin maxValue, Sha256Hash serverId, IPaymentChannelClient.ClientConnection conn, PaymentChannelClient.VersionSelector versionSelector) Constructs a new channel manager which waits for connectionOpen() before acting.
PaymentChannelClient(Wallet wallet, ECKey myKey, Coin maxValue, Sha256Hash serverId, long timeWindow, org.spongycastle.crypto.params.KeyParameter userKeySetup, IPaymentChannelClient.ClientConnection conn) Constructs a new channel manager which waits for connectionOpen() before acting.
PaymentChannelClient(Wallet wallet, ECKey myKey, Coin maxValue, Sha256Hash serverId, long timeWindow, org.spongycastle.crypto.params.KeyParameter userKeySetup, IPaymentChannelClient.ClientConnection conn, PaymentChannelClient.VersionSelector versionSelector) Constructs a new channel manager which waits for connectionOpen() before acting.

Method Summary

Modifier and Type	Method and Description
void	connectionClosed() Called when the connection terminates.
void	connectionOpen() Called to indicate the connection has been opened and messages can now be generated for the server.
Coin	getMissing() Returns the amount of satoshis missing when a server requests too much value.
ListenableFuture<PaymentIncrementAck>	incrementPayment(Coin size) Increments the total value which we pay the server.
ListenableFuture<PaymentIncrementAck>	incrementPayment(Coin size, com.google.protobuf.ByteString info, org.spongycastle.crypto.params.KeyParameter userKey) Increments the total value which we pay the server.
void	receiveMessage(Protos.TwoWayChannelMessage msg) Called when a message is received from the server.
void	settle() Closes the connection, notifying the server it should settle the channel by broadcasting the most recent payment transaction.
PaymentChannelClientState	state() Gets the PaymentChannelClientState object which stores the current state of the connection with the server.

Methods inherited from class java.lang.Object

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

Field Detail

lock

protected final ReentrantLock lock

DEFAULT_TIME_WINDOW

public static final long DEFAULT_TIME_WINDOW

The default maximum amount of time for which we will accept the server locking up our funds for the multisig contract.

24 hours less a minute is the default as it is expected that clients limit risk exposure by limiting channel size instead of limiting lock time when dealing with potentially malicious servers.

See Also:

Constant Field Values

Constructor Detail

PaymentChannelClient

public PaymentChannelClient(Wallet wallet,
                            ECKey myKey,
                            Coin maxValue,
                            Sha256Hash serverId,
                            IPaymentChannelClient.ClientConnection conn)

Constructs a new channel manager which waits for connectionOpen() before acting. A default time window of DEFAULT_TIME_WINDOW will be used.

Parameters:

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must already have a StoredPaymentChannelClientStates object in its extensions set.

myKey - A freshly generated keypair used for the multisig contract and refund output.

maxValue - The maximum value the server is allowed to request that we lock into this channel until the refund transaction unlocks. Note that if there is a previously open channel, the refund transaction used in this channel may be larger than maxValue. Thus, maxValue is not a method for limiting the amount payable through this channel.

serverId - An arbitrary hash representing this channel. This must uniquely identify the server. If an existing stored channel exists in the wallet's StoredPaymentChannelClientStates, then an attempt will be made to resume that channel.

conn - A callback listener which represents the connection to the server (forwards messages we generate to the server)

PaymentChannelClient

public PaymentChannelClient(Wallet wallet,
                            ECKey myKey,
                            Coin maxValue,
                            Sha256Hash serverId,
                            IPaymentChannelClient.ClientConnection conn,
                            PaymentChannelClient.VersionSelector versionSelector)

Constructs a new channel manager which waits for connectionOpen() before acting. A default time window of DEFAULT_TIME_WINDOW will be used.

Parameters:

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must already have a StoredPaymentChannelClientStates object in its extensions set.

myKey - A freshly generated keypair used for the multisig contract and refund output.

maxValue - The maximum value the server is allowed to request that we lock into this channel until the refund transaction unlocks. Note that if there is a previously open channel, the refund transaction used in this channel may be larger than maxValue. Thus, maxValue is not a method for limiting the amount payable through this channel.

serverId - An arbitrary hash representing this channel. This must uniquely identify the server. If an existing stored channel exists in the wallet's StoredPaymentChannelClientStates, then an attempt will be made to resume that channel.

conn - A callback listener which represents the connection to the server (forwards messages we generate to the server)

versionSelector - An enum indicating which versions to support: VERSION_1: use only version 1 of the protocol VERSION_2_ALLOW_1: suggest version 2 but allow downgrade to version 1 VERSION_2: suggest version 2 and enforce use of version 2

PaymentChannelClient

public PaymentChannelClient(Wallet wallet,
                            ECKey myKey,
                            Coin maxValue,
                            Sha256Hash serverId,
                            long timeWindow,
                            @Nullable
                            org.spongycastle.crypto.params.KeyParameter userKeySetup,
                            IPaymentChannelClient.ClientConnection conn)

Constructs a new channel manager which waits for connectionOpen() before acting.

Parameters:

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must already have a StoredPaymentChannelClientStates object in its extensions set.

myKey - A freshly generated keypair used for the multisig contract and refund output.

maxValue - The maximum value the server is allowed to request that we lock into this channel until the refund transaction unlocks. Note that if there is a previously open channel, the refund transaction used in this channel may be larger than maxValue. Thus, maxValue is not a method for limiting the amount payable through this channel.

serverId - An arbitrary hash representing this channel. This must uniquely identify the server. If an existing stored channel exists in the wallet's StoredPaymentChannelClientStates, then an attempt will be made to resume that channel.

timeWindow - The time in seconds, relative to now, on how long this channel should be kept open. Note that is is a proposal to the server. The server may in turn propose something different. See IPaymentChannelClient.ClientConnection.acceptExpireTime(long)

userKeySetup - Key derived from a user password, used to decrypt myKey, if it is encrypted, during setup.

conn - A callback listener which represents the connection to the server (forwards messages we generate to the server)

PaymentChannelClient

public PaymentChannelClient(Wallet wallet,
                            ECKey myKey,
                            Coin maxValue,
                            Sha256Hash serverId,
                            long timeWindow,
                            @Nullable
                            org.spongycastle.crypto.params.KeyParameter userKeySetup,
                            IPaymentChannelClient.ClientConnection conn,
                            PaymentChannelClient.VersionSelector versionSelector)

Constructs a new channel manager which waits for connectionOpen() before acting.

Parameters:

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must already have a StoredPaymentChannelClientStates object in its extensions set.

myKey - A freshly generated keypair used for the multisig contract and refund output.

maxValue - The maximum value the server is allowed to request that we lock into this channel until the refund transaction unlocks. Note that if there is a previously open channel, the refund transaction used in this channel may be larger than maxValue. Thus, maxValue is not a method for limiting the amount payable through this channel.

serverId - An arbitrary hash representing this channel. This must uniquely identify the server. If an existing stored channel exists in the wallet's StoredPaymentChannelClientStates, then an attempt will be made to resume that channel.

timeWindow - The time in seconds, relative to now, on how long this channel should be kept open. Note that is is a proposal to the server. The server may in turn propose something different. See IPaymentChannelClient.ClientConnection.acceptExpireTime(long)

userKeySetup - Key derived from a user password, used to decrypt myKey, if it is encrypted, during setup.

conn - A callback listener which represents the connection to the server (forwards messages we generate to the server)

versionSelector - An enum indicating which versions to support: VERSION_1: use only version 1 of the protocol VERSION_2_ALLOW_1: suggest version 2 but allow downgrade to version 1 VERSION_2: suggest version 2 and enforce use of version 2

Method Detail

getMissing

public Coin getMissing()

Returns the amount of satoshis missing when a server requests too much value.

When InsufficientMoneyException is thrown due to the server requesting too much value, an instance of PaymentChannelClient needs access to how many satoshis are missing.

receiveMessage

public void receiveMessage(Protos.TwoWayChannelMessage msg)
                    throws InsufficientMoneyException

Called when a message is received from the server. Processes the given message and generates events based on its content.

Specified by:

receiveMessage in interface IPaymentChannelClient

Throws:

InsufficientMoneyException

connectionClosed

public void connectionClosed()

Called when the connection terminates. Notifies the StoredClientChannel object that we can attempt to resume this channel in the future and stops generating messages for the server.

For stateless protocols, this translates to a client not using the channel for the immediate future, but intending to reopen the channel later. There is likely little reason to use this in a stateless protocol.

Note that this MUST still be called even after either ClientConnection#destroyConnection(org.bitcoinj.protocols.channels.PaymentChannelCloseException.CloseReason) or settle() is called, to actually handle the connection close logic.

Specified by:

connectionClosed in interface IPaymentChannelClient

settle

public void settle()
            throws IllegalStateException

Closes the connection, notifying the server it should settle the channel by broadcasting the most recent payment transaction.

Note that this only generates a CLOSE message for the server and calls ClientConnection#destroyConnection(CloseReason) to settle the connection, it does not actually handle connection close logic, and connectionClosed() must still be called after the connection fully closes.

Specified by:

settle in interface IPaymentChannelClient

Throws:

IllegalStateException - If the connection is not currently open (ie the CLOSE message cannot be sent)

connectionOpen

public void connectionOpen()

Called to indicate the connection has been opened and messages can now be generated for the server.

Attempts to find a channel to resume and generates a CLIENT_VERSION message for the server based on the result.

Specified by:

connectionOpen in interface IPaymentChannelClient

state

public PaymentChannelClientState state()

Gets the PaymentChannelClientState object which stores the current state of the connection with the server.

Note that if you call any methods which update state directly the server will not be notified and channel initialization logic in the connection may fail unexpectedly.

incrementPayment

public ListenableFuture<PaymentIncrementAck> incrementPayment(Coin size)
                                                       throws ValueOutOfRangeException,
                                                              IllegalStateException

Increments the total value which we pay the server. Note that the amount of money sent may not be the same as the amount of money actually requested. It can be larger if the amount left over in the channel would be too small to be accepted by the Bitcoin network. ValueOutOfRangeException will be thrown, however, if there's not enough money left in the channel to make the payment at all. Only one payment can be in-flight at once. You have to ensure you wait for the previous increase payment future to complete before incrementing the payment again.

Parameters:

size - How many satoshis to increment the payment by (note: not the new total).

Returns:

a future that completes when the server acknowledges receipt and acceptance of the payment.

Throws:

ValueOutOfRangeException - If the size is negative or would pay more than this channel's total value (PaymentChannelClientConnection.state().getTotalValue())

IllegalStateException - If the channel has been closed or is not yet open (see PaymentChannelClientConnection.getChannelOpenFuture() for the second)

incrementPayment

public ListenableFuture<PaymentIncrementAck> incrementPayment(Coin size,
                                                              @Nullable
                                                              com.google.protobuf.ByteString info,
                                                              @Nullable
                                                              org.spongycastle.crypto.params.KeyParameter userKey)
                                                       throws ValueOutOfRangeException,
                                                              IllegalStateException,
                                                              ECKey.KeyIsEncryptedException

Increments the total value which we pay the server. Note that the amount of money sent may not be the same as the amount of money actually requested. It can be larger if the amount left over in the channel would be too small to be accepted by the Bitcoin network. ValueOutOfRangeException will be thrown, however, if there's not enough money left in the channel to make the payment at all. Only one payment can be in-flight at once. You have to ensure you wait for the previous increase payment future to complete before incrementing the payment again.

Specified by:

incrementPayment in interface IPaymentChannelClient

Parameters:

size - How many satoshis to increment the payment by (note: not the new total).

info - Information about this update, used to extend this protocol.

userKey - Key derived from a user password, needed for any signing when the wallet is encrypted. The wallet KeyCrypter is assumed.

Returns:

a future that completes when the server acknowledges receipt and acceptance of the payment.

Throws:

ValueOutOfRangeException - If the size is negative or would pay more than this channel's total value (PaymentChannelClientConnection.state().getTotalValue())

IllegalStateException - If the channel has been closed or is not yet open (see PaymentChannelClientConnection.getChannelOpenFuture() for the second)

ECKey.KeyIsEncryptedException - If the keys are encrypted and no AES key has been provided,