com.google.bitcoin.protocols.channels
Class PaymentChannelServer

java.lang.Object
  com.google.bitcoin.protocols.channels.PaymentChannelServer

public class PaymentChannelServer
extends Object

A handler 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 client and which generates protobufs which should be sent to the client.

Does all required verification of messages and properly stores state objects in the wallet-attached StoredPaymentChannelServerStates so that they are automatically closed when necessary and payment transactions are not lost if the application crashes before it unlocks.

Nested Class Summary

static interface

PaymentChannelServer.ServerConnection Implements the connection between this server and the client, providing an interface which allows messages to be sent to the client, requests for the connection to the client to be closed, and callbacks which occur when the channel is fully open or the client completes a payment.

Field Summary

protected ReentrantLock	lock
long	timeWindow The amount of time we request the client lock in their funds.

Constructor Summary

PaymentChannelServer(TransactionBroadcaster broadcaster, Wallet wallet, BigInteger minAcceptedChannelSize, PaymentChannelServer.ServerConnection conn)
Creates a new server-side state manager which handles a single client connection.

Method Summary

void	close() Closes the connection by generating a settle message for the client and calls ServerConnection#destroyConnection(CloseReason).
void	connectionClosed() Called when the connection terminates.
void	connectionOpen() Called to indicate the connection has been opened and messages can now be generated for the client.
void	receiveMessage(Protos.TwoWayChannelMessage msg) Called when a message is received from the client.
PaymentChannelServerState	state() Returns the underlying PaymentChannelServerState object that is being manipulated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

lock

protected final ReentrantLock lock

timeWindow

public long timeWindow

The amount of time we request the client lock in their funds.

The value defaults to 24 hours - 60 seconds and should always be greater than 2 hours plus the amount of time the channel is expected to be used and smaller than 24 hours minus the client <-> server latency minus some factor to account for client clock inaccuracy.

Constructor Detail

PaymentChannelServer

public PaymentChannelServer(TransactionBroadcaster broadcaster,
                            Wallet wallet,
                            BigInteger minAcceptedChannelSize,
                            PaymentChannelServer.ServerConnection conn)

Creates a new server-side state manager which handles a single client connection.

Parameters:

broadcaster - The PeerGroup on which transactions will be broadcast - should have multiple connections.

wallet - The wallet which will be used to complete transactions. Unlike PaymentChannelClient, this does not have to already contain a StoredState manager

minAcceptedChannelSize - The minimum value the client must lock into this channel. A value too large will be rejected by clients, and a value too low will require excessive channel reopening and may cause fees to be require to settle the channel. A reasonable value depends entirely on the expected maximum for the channel, and should likely be somewhere between a few bitcents and a bitcoin.

conn - A callback listener which represents the connection to the client (forwards messages we generate to the client and will close the connection on request)

Method Detail

state

@Nullable
public PaymentChannelServerState state()

Returns the underlying PaymentChannelServerState object that is being manipulated. This object allows you to learn how much money has been transferred, etc. May be null if the channel wasn't negotiated yet.

receiveMessage

public void receiveMessage(Protos.TwoWayChannelMessage msg)

Called when a message is received from the client. Processes the given message and generates events based on its content.

connectionClosed

public void connectionClosed()

Called when the connection terminates. Notifies the StoredServerChannel object that we can attempt to resume this channel in the future and stops generating messages for the client.

Note that this MUST still be called even after either ServerConnection#destroyConnection(CloseReason) or close() is called to actually handle the connection close logic.

connectionOpen

public void connectionOpen()

Called to indicate the connection has been opened and messages can now be generated for the client.

close

public void close()

Closes the connection by generating a settle message for the client and calls ServerConnection#destroyConnection(CloseReason). Note that this does not broadcast the payment transaction and the client may still resume the same channel if they reconnect

Note that connectionClosed() must still be called after the connection fully closes.