Class PaymentChannelClient

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.

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)

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

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.

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.

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

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.

settle

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.

incrementPayment

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.

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.