org.bitcoinj.protocols.channels

Class PaymentChannelV1ClientState

java.lang.Object

org.bitcoinj.protocols.channels.PaymentChannelClientState

org.bitcoinj.protocols.channels.PaymentChannelV1ClientState

public class PaymentChannelV1ClientState
extends PaymentChannelClientState

Version 1 of the payment channel state machine - uses time locked multisig contracts.

Nested Class Summary

Nested classes/interfaces inherited from class org.bitcoinj.protocols.channels.PaymentChannelClientState

PaymentChannelClientState.IncrementedPayment, PaymentChannelClientState.State

Field Summary

Fields inherited from class org.bitcoinj.protocols.channels.PaymentChannelClientState

stateMachine, storedChannel, valueToMe

Constructor Summary

Constructors

Constructor and Description
PaymentChannelV1ClientState(Wallet wallet, ECKey myKey, ECKey serverMultisigKey, Coin value, long expiryTimeInSeconds) Creates a state object for a payment channel client.

Method Summary

Modifier and Type	Method and Description
Transaction	getCompletedRefundTransaction() Once the servers signature over the refund transaction has been received and provided using provideRefundSignature(byte[], KeyParameter) then this method can be called to receive the now valid and broadcastable refund transaction.
Transaction	getContract() Returns the transaction that locks the money to the agreement of both parties.
protected Transaction	getContractInternal() Gets the contract without changing the state machine
protected Script	getContractScript()
protected long	getExpiryTime()
Transaction	getIncompleteRefundTransaction() Returns a partially signed (invalid) refund transaction that should be passed to the server.
int	getMajorVersion()
Coin	getRefundTxFees() Returns the fees that will be paid if the refund transaction has to be claimed because the server failed to settle the channel properly.
protected Script	getSignedScript() Gets the script that is signed.
protected Multimap<PaymentChannelClientState.State,PaymentChannelClientState.State>	getStateTransitions()
Coin	getTotalValue() Gets the total value of this channel (ie the maximum payment possible)
protected Coin	getValueToMe()
void	initiate(org.spongycastle.crypto.params.KeyParameter userKey) Creates the initial multisig contract and incomplete refund transaction which can be requested at the appropriate time using getIncompleteRefundTransaction() and getContract().
void	provideRefundSignature(byte[] theirSignature, org.spongycastle.crypto.params.KeyParameter userKey) When the servers signature for the refund transaction is received, call this to verify it and sign the complete refund ourselves.

Methods inherited from class org.bitcoinj.protocols.channels.PaymentChannelClientState

checkNotExpired, disconnectFromChannel, editContractSendRequest, getState, getValueRefunded, getValueSpent, incrementPaymentBy, initiate, initWalletListeners, isSettlementTransaction, storeChannelInWallet, updateChannelInWallet, watchCloseConfirmations

Methods inherited from class java.lang.Object

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

Constructor Detail

PaymentChannelV1ClientState

public PaymentChannelV1ClientState(Wallet wallet,
                                   ECKey myKey,
                                   ECKey serverMultisigKey,
                                   Coin value,
                                   long expiryTimeInSeconds)
                            throws VerificationException

Creates a state object for a payment channel client. It is expected that you be ready to PaymentChannelClientState.initiate() after construction (to avoid creating objects for channels which are not going to finish opening) and thus some parameters provided here are only used in PaymentChannelClientState.initiate() to create the Multisig contract and refund transaction.

Parameters:

wallet - a wallet that contains at least the specified amount of value.

myKey - a freshly generated private key for this channel.

serverMultisigKey - a public key retrieved from the server used for the initial multisig contract

value - how many satoshis to put into this contract. If the channel reaches this limit, it must be closed.

expiryTimeInSeconds - At what point (UNIX timestamp +/- a few hours) the channel will expire

Throws:

VerificationException - If either myKey's pubkey or serverKey's pubkey are non-canonical (ie invalid)

Method Detail

getStateTransitions

protected Multimap<PaymentChannelClientState.State,PaymentChannelClientState.State> getStateTransitions()

Specified by:

getStateTransitions in class PaymentChannelClientState

getMajorVersion

public int getMajorVersion()

Specified by:

getMajorVersion in class PaymentChannelClientState

initiate

public void initiate(@Nullable
                     org.spongycastle.crypto.params.KeyParameter userKey)
              throws ValueOutOfRangeException,
                     InsufficientMoneyException

Creates the initial multisig contract and incomplete refund transaction which can be requested at the appropriate time using getIncompleteRefundTransaction() and getContract(). The way the contract is crafted can be adjusted by overriding PaymentChannelV1ClientState#editContractSendRequest(org.bitcoinj.core.Wallet.SendRequest). By default unconfirmed coins are allowed to be used, as for micropayments the risk should be relatively low.

Specified by:

initiate in class PaymentChannelClientState

Parameters:

userKey - Key derived from a user password, needed for any signing when the wallet is encrypted. The wallet KeyCrypter is assumed.

Throws:

ValueOutOfRangeException - if the value being used is too small to be accepted by the network

InsufficientMoneyException - if the wallet doesn't contain enough balance to initiate

getContract

public Transaction getContract()

Returns the transaction that locks the money to the agreement of both parties. Do not mutate the result. Once this step is done, you can use PaymentChannelClientState.incrementPaymentBy(Coin, KeyParameter) to start paying the server.

Specified by:

getContract in class PaymentChannelClientState

getContractInternal

protected Transaction getContractInternal()

Description copied from class: PaymentChannelClientState

Gets the contract without changing the state machine

Specified by:

getContractInternal in class PaymentChannelClientState

Returns:

getContractScript

protected Script getContractScript()

Specified by:

getContractScript in class PaymentChannelClientState

getSignedScript

protected Script getSignedScript()

Description copied from class: PaymentChannelClientState

Gets the script that is signed. In the case of a P2SH contract this is the script inside the P2SH script.

Specified by:

getSignedScript in class PaymentChannelClientState

Returns:

getIncompleteRefundTransaction

public Transaction getIncompleteRefundTransaction()

Returns a partially signed (invalid) refund transaction that should be passed to the server. Once the server has checked it out and provided its own signature, call provideRefundSignature(byte[], KeyParameter) with the result.

provideRefundSignature

public void provideRefundSignature(byte[] theirSignature,
                                   @Nullable
                                   org.spongycastle.crypto.params.KeyParameter userKey)
                            throws VerificationException

When the servers signature for the refund transaction is received, call this to verify it and sign the complete refund ourselves.

If this does not throw an exception, we are secure against the loss of funds and can safely provide the server with the multi-sig contract to lock in the agreement. In this case, both the multisig contract and the refund transaction are automatically committed to wallet so that it can handle broadcasting the refund transaction at the appropriate time if necessary.

Throws:

VerificationException

getValueToMe

protected Coin getValueToMe()

Specified by:

getValueToMe in class PaymentChannelClientState

getExpiryTime

protected long getExpiryTime()

Specified by:

getExpiryTime in class PaymentChannelClientState

getRefundTxFees

public Coin getRefundTxFees()

Description copied from class: PaymentChannelClientState

Returns the fees that will be paid if the refund transaction has to be claimed because the server failed to settle the channel properly. May only be called after PaymentChannelClientState.initiate()

Specified by:

getRefundTxFees in class PaymentChannelClientState

getCompletedRefundTransaction

public Transaction getCompletedRefundTransaction()

Once the servers signature over the refund transaction has been received and provided using provideRefundSignature(byte[], KeyParameter) then this method can be called to receive the now valid and broadcastable refund transaction.

getTotalValue

public Coin getTotalValue()

Gets the total value of this channel (ie the maximum payment possible)

Specified by:

getTotalValue in class PaymentChannelClientState