org.bitcoinj.protocols.channels

Class PaymentChannelServer

java.lang.Object

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

Nested Classes

Modifier and Type	Class and Description
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

Fields

Modifier and Type	Field and Description
static long	DEFAULT_MAX_TIME_WINDOW
static long	DEFAULT_MIN_TIME_WINDOW
static long	HARD_MIN_TIME_WINDOW
protected ReentrantLock	lock
protected long	maxTimeWindow Maximum channel duration, in seconds, that the client can request.
protected long	minTimeWindow Minimum channel duration, in seconds, that the client can request.
int	SERVER_MAJOR_VERSION
int	SERVER_MINOR_VERSION

Constructor Summary

Constructors

Constructor and Description
PaymentChannelServer(TransactionBroadcaster broadcaster, Wallet wallet, Coin minAcceptedChannelSize, long minTimeWindow, long maxTimeWindow, PaymentChannelServer.ServerConnection conn) Creates a new server-side state manager which handles a single client connection.
PaymentChannelServer(TransactionBroadcaster broadcaster, Wallet wallet, Coin minAcceptedChannelSize, PaymentChannelServer.ServerConnection conn) Creates a new server-side state manager which handles a single client connection.

Method Summary

Modifier and Type	Method and Description
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

SERVER_MAJOR_VERSION

public final int SERVER_MAJOR_VERSION

See Also:

Constant Field Values

SERVER_MINOR_VERSION

public final int SERVER_MINOR_VERSION

See Also:

Constant Field Values

DEFAULT_MAX_TIME_WINDOW

public static final long DEFAULT_MAX_TIME_WINDOW

See Also:

Constant Field Values

maxTimeWindow

protected final long maxTimeWindow

Maximum channel duration, in seconds, that the client can request. Defaults to 1 week. Note that the server needs to be online for the whole time the channel is open. Failure to do this could cause loss of all payments received on the channel.

DEFAULT_MIN_TIME_WINDOW

public static final long DEFAULT_MIN_TIME_WINDOW

See Also:

Constant Field Values

HARD_MIN_TIME_WINDOW

public static final long HARD_MIN_TIME_WINDOW

See Also:

Constant Field Values

minTimeWindow

protected final long minTimeWindow

Minimum channel duration, in seconds, that the client can request. Should always be larger than than 2 hours, defaults to 4 hours

Constructor Detail

PaymentChannelServer

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

Creates a new server-side state manager which handles a single client connection. The server will only accept a channel with time window between 4 hours and 1 week. Note that the server need to be online for the whole time the channel is open. Failure to do this could cause loss of all payments received on the channel.

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)

PaymentChannelServer

public PaymentChannelServer(TransactionBroadcaster broadcaster,
                            Wallet wallet,
                            Coin minAcceptedChannelSize,
                            long minTimeWindow,
                            long maxTimeWindow,
                            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.

minTimeWindow - The minimum allowed channel time window in seconds, must be larger than 7200.

maxTimeWindow - The maximum allowed channel time window in seconds. Note that the server need to be online for the whole time the channel is open. Failure to do this could cause loss of all payments received on the channel.

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.