com.google.bitcoin.protocols.channels

Class PaymentChannelClientConnection

java.lang.Object

com.google.bitcoin.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, BigInteger 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

Method Summary

Methods

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<BigInteger>	incrementPayment(BigInteger size) 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 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

Constructor Detail

PaymentChannelClientConnection

public PaymentChannelClientConnection(InetSocketAddress server,
                              int timeoutSeconds,
                              Wallet wallet,
                              ECKey myKey,
                              BigInteger 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

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 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.

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(java.math.BigInteger) to begin paying the server.

incrementPayment

public com.google.common.util.concurrent.ListenableFuture<BigInteger> incrementPayment(BigInteger 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)

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.

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