org.bitcoinj.protocols.channels

Class PaymentChannelClientConnection

java.lang.Object

org.bitcoinj.protocols.channels.PaymentChannelClientConnection

public class PaymentChannelClientConnection
extends Object

A simple utility class that runs the micropayment protocol over a raw TCP socket using NIO, standalone.

Constructor Summary

Constructors

Constructor and Description
PaymentChannelClientConnection(InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, String serverId) Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open.
PaymentChannelClientConnection(InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, String serverId, long timeWindow, org.spongycastle.crypto.params.KeyParameter userKeySetup) Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open.
PaymentChannelClientConnection(InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, String serverId, long timeWindow, org.spongycastle.crypto.params.KeyParameter userKeySetup, PaymentChannelClient.VersionSelector versionSelector) Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open.
PaymentChannelClientConnection(InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, String serverId, PaymentChannelClient.VersionSelector versionSelector) Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open.

Method Summary

Modifier and Type	Method and Description
void	disconnectWithoutSettlement() Disconnects the network connection but doesn't request the server to settle the channel first (literally just unplugs the network socket and marks the stored channel state as inactive).
ListenableFuture<PaymentChannelClientConnection>	getChannelOpenFuture() Gets a future which returns this when the channel is successfully opened, or throws an exception if there is an error before the channel has reached the open state.
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	settle() Closes the connection, notifying the server it should settle the channel by broadcasting the most recent payment transaction.
PaymentChannelClientState	state() Gets the PaymentChannelV1ClientState 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

Constructor Detail

PaymentChannelClientConnection

public PaymentChannelClientConnection(InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      String serverId)
                               throws IOException,
                                      ValueOutOfRangeException

Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open. The server is requested to keep the channel open for PaymentChannelClient.DEFAULT_TIME_WINDOW seconds. If the server proposes a longer time the channel will be closed.

Parameters:

server - The host/port pair where the server is listening.

timeoutSeconds - The connection timeout and read timeout during initialization. This should be large enough to accommodate ECDSA signature operations and network latency.

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must be unencrypted. 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 this channel is allowed to request

serverId - A unique ID which is used to attempt reopening of an existing channel. This must be unique to the server, and, if your application is exposing payment channels to some API, this should also probably encompass some caller UID to avoid applications opening channels which were created by others.

Throws:

IOException - if there's an issue using the network.

ValueOutOfRangeException - if the balance of wallet is lower than maxValue.

PaymentChannelClientConnection

public PaymentChannelClientConnection(InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      String serverId,
                                      PaymentChannelClient.VersionSelector versionSelector)
                               throws IOException,
                                      ValueOutOfRangeException

Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open. The server is requested to keep the channel open for PaymentChannelClient.DEFAULT_TIME_WINDOW seconds. If the server proposes a longer time the channel will be closed.

Parameters:

server - The host/port pair where the server is listening.

timeoutSeconds - The connection timeout and read timeout during initialization. This should be large enough to accommodate ECDSA signature operations and network latency.

wallet - The wallet which will be paid from, and where completed transactions will be committed. Must be unencrypted. 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 this channel is allowed to request

serverId - A unique ID which is used to attempt reopening of an existing channel. This must be unique to the server, and, if your application is exposing payment channels to some API, this should also probably encompass some caller UID to avoid applications opening channels which were created by others.

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

Throws:

IOException - if there's an issue using the network.

ValueOutOfRangeException - if the balance of wallet is lower than maxValue.

PaymentChannelClientConnection

public PaymentChannelClientConnection(InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      String serverId,
                                      long timeWindow,
                                      @Nullable
                                      org.spongycastle.crypto.params.KeyParameter userKeySetup)
                               throws IOException,
                                      ValueOutOfRangeException

Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open. The server is requested to keep the channel open for seconds. If the server proposes a longer time the channel will be closed.

Parameters:

server - The host/port pair where the server is listening.

timeoutSeconds - The connection timeout and read timeout during initialization. This should be large enough to accommodate ECDSA signature operations and network latency.

wallet - The wallet which will be paid from, and where completed transactions will be committed. Can be encrypted if user key is supplied when needed. 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 this channel is allowed to request

serverId - A unique ID which is used to attempt reopening of an existing channel. This must be unique to the server, and, if your application is exposing payment channels to some API, this should also probably encompass some caller UID to avoid applications opening channels which were created by others.

timeWindow - The time in seconds, relative to now, on how long this channel should be kept open.

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

Throws:

IOException - if there's an issue using the network.

ValueOutOfRangeException - if the balance of wallet is lower than maxValue.

PaymentChannelClientConnection

public PaymentChannelClientConnection(InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      String serverId,
                                      long timeWindow,
                                      @Nullable
                                      org.spongycastle.crypto.params.KeyParameter userKeySetup,
                                      PaymentChannelClient.VersionSelector versionSelector)
                               throws IOException,
                                      ValueOutOfRangeException

Attempts to open a new connection to and open a payment channel with the given host and port, blocking until the connection is open. The server is requested to keep the channel open for seconds. If the server proposes a longer time the channel will be closed.

Parameters:

server - The host/port pair where the server is listening.

timeoutSeconds - The connection timeout and read timeout during initialization. This should be large enough to accommodate ECDSA signature operations and network latency.

wallet - The wallet which will be paid from, and where completed transactions will be committed. Can be encrypted if user key is supplied when needed. 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 this channel is allowed to request

serverId - A unique ID which is used to attempt reopening of an existing channel. This must be unique to the server, and, if your application is exposing payment channels to some API, this should also probably encompass some caller UID to avoid applications opening channels which were created by others.

timeWindow - The time in seconds, relative to now, on how long this channel should be kept open.

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

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

Throws:

IOException - if there's an issue using the network.

ValueOutOfRangeException - if the balance of wallet is lower than maxValue.

Method Detail

getChannelOpenFuture

public ListenableFuture<PaymentChannelClientConnection> getChannelOpenFuture()

Gets a future which returns this when the channel is successfully opened, or throws an exception if there is an error before the channel has reached the open state.

After this future completes successfully, you may call incrementPayment(Coin) or incrementPayment(Coin, com.google.protobuf.ByteString, KeyParameter) to begin paying the server.

incrementPayment

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

Increments the total value which we pay the server.

Parameters:

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

Throws:

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

IllegalStateException - If the channel has been closed or is not yet open (see 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

Increments the total value which we pay the server.

Parameters:

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

info - Information about this payment increment, 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.

Throws:

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

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

state

public PaymentChannelClientState state()

Gets the PaymentChannelV1ClientState 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.

settle

public void settle()

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

disconnectWithoutSettlement

public void disconnectWithoutSettlement()

Disconnects the network connection but doesn't request the server to settle the channel first (literally just unplugs the network socket and marks the stored channel state as inactive).