org.bitcoinj.protocols.channels

Class PaymentChannelClientConnection

java.lang.Object

org.bitcoinj.protocols.channels.PaymentChannelClientConnection

public class PaymentChannelClientConnection
extends java.lang.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(java.net.InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, java.lang.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(java.net.InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, java.lang.String serverId, org.bouncycastle.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(java.net.InetSocketAddress server, int timeoutSeconds, Wallet wallet, ECKey myKey, Coin maxValue, java.lang.String serverId, org.bouncycastle.crypto.params.KeyParameter userKeySetup, IPaymentChannelClient.ClientChannelProperties clientChannelProperties) 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).
com.google.common.util.concurrent.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.
com.google.common.util.concurrent.ListenableFuture<PaymentIncrementAck>	incrementPayment(Coin size) Increments the total value which we pay the server.
com.google.common.util.concurrent.ListenableFuture<PaymentIncrementAck>	incrementPayment(Coin size, com.google.protobuf.ByteString info, org.bouncycastle.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(java.net.InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      java.lang.String serverId)
                               throws java.io.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:

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

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

PaymentChannelClientConnection

public PaymentChannelClientConnection(java.net.InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      java.lang.String serverId,
                                      @Nullable
                                      org.bouncycastle.crypto.params.KeyParameter userKeySetup)
                               throws java.io.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. 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.

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

Throws:

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

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

PaymentChannelClientConnection

public PaymentChannelClientConnection(java.net.InetSocketAddress server,
                                      int timeoutSeconds,
                                      Wallet wallet,
                                      ECKey myKey,
                                      Coin maxValue,
                                      java.lang.String serverId,
                                      @Nullable
                                      org.bouncycastle.crypto.params.KeyParameter userKeySetup,
                                      IPaymentChannelClient.ClientChannelProperties clientChannelProperties)
                               throws java.io.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 timeoutSeconds 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.

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

clientChannelProperties - Modifier to change the channel's configuration.

Throws:

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

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

Method Detail

getChannelOpenFuture

public com.google.common.util.concurrent.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, ByteString, KeyParameter) to begin paying the server.

incrementPayment

public com.google.common.util.concurrent.ListenableFuture<PaymentIncrementAck> incrementPayment(Coin size)
                                                                                         throws ValueOutOfRangeException,
                                                                                                java.lang.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())

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

incrementPayment

public com.google.common.util.concurrent.ListenableFuture<PaymentIncrementAck> incrementPayment(Coin size,
                                                                                                @Nullable
                                                                                                com.google.protobuf.ByteString info,
                                                                                                @Nullable
                                                                                                org.bouncycastle.crypto.params.KeyParameter userKey)
                                                                                         throws ValueOutOfRangeException,
                                                                                                java.lang.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())

java.lang.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).