org.bitcoinj.protocols.channels

Interface IPaymentChannelClient

All Known Implementing Classes:

PaymentChannelClient

public interface IPaymentChannelClient

A class implementing this interface supports the basic operations of a payment channel. An implementation is provided in PaymentChannelClient, but alternative implementations are possible. For example, an implementor might send RPCs to a separate (locally installed or even remote) wallet app rather than implementing the algorithm locally.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IPaymentChannelClient.ClientConnection Implements the connection between this client and the server, providing an interface which allows messages to be sent to the server, requests for the connection to the server to be closed, and a callback which occurs when the channel is fully open.
static interface	IPaymentChannelClient.Factory An implementor of this interface creates payment channel clients that "talk back" with the given connection.

Method Summary

Modifier and Type	Method and Description
void	connectionClosed() Called when the connection to the server terminates.
void	connectionOpen() Called to indicate the connection has been opened and messages can now be generated for 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() Settles the channel, notifying the server it can broadcast the most recent payment transaction.

Method Detail

receiveMessage

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.

Throws:

InsufficientMoneyException

connectionClosed

void connectionClosed()

Called when the connection to the server terminates.

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 PaymentChannelClient.ClientConnection#destroyConnection(org.bitcoinj.protocols.channels.PaymentChannelCloseException.CloseReason) or settle() is called, to actually handle the connection close logic.

settle

void settle()
     throws IllegalStateException

Settles the channel, notifying the server it can broadcast the most recent payment transaction.

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

Throws:

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

connectionOpen

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.

incrementPayment

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.

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.

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,