org.bitcoinj.protocols.channels

Class PaymentChannelServer

java.lang.Object

org.bitcoinj.protocols.channels.PaymentChannelServer

public class PaymentChannelServer
extends java.lang.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 class	PaymentChannelServer.DefaultServerChannelProperties Extend this class and override the values you want to change.
static interface	PaymentChannelServer.ServerChannelProperties
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 java.util.concurrent.locks.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.
static java.util.Map<java.lang.Integer,java.lang.Integer>	SERVER_VERSIONS A map of supported versions; keys are major versions, and the corresponding value is the minor version at that major level.

Constructor Summary

Constructors

Constructor and Description
PaymentChannelServer(TransactionBroadcaster broadcaster, Wallet wallet, Coin minAcceptedChannelSize, PaymentChannelServer.ServerChannelProperties serverChannelProperties, 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 PaymentChannelServer.ServerConnection.destroyConnection(PaymentChannelCloseException.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 java.util.concurrent.locks.ReentrantLock lock

SERVER_VERSIONS

public static final java.util.Map<java.lang.Integer,java.lang.Integer> SERVER_VERSIONS

A map of supported versions; keys are major versions, and the corresponding value is the minor version at that major level.

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,
                            PaymentChannelServer.ServerChannelProperties serverChannelProperties,
                            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.

serverChannelProperties - Modify the channel's properties. You may extend PaymentChannelServer.DefaultServerChannelProperties

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 PaymentChannelServer.ServerConnection.destroyConnection(PaymentChannelCloseException.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 PaymentChannelServer.ServerConnection.destroyConnection(PaymentChannelCloseException.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.