PaymentChannelServerState (bitcoinj 0.14 API)

java.lang.Object
- org.bitcoinj.protocols.channels.PaymentChannelServerState

Direct Known Subclasses:

PaymentChannelV1ServerState, PaymentChannelV2ServerState
```
public abstract class PaymentChannelServerState
extends Object
```
A payment channel is a method of sending money to someone such that the amount of money you send can be adjusted after the fact, in an efficient manner that does not require broadcasting to the network. This can be used to implement micropayments or other payment schemes in which immediate settlement is not required, but zero trust negotiation is. Note that this class only allows the amount of money received to be incremented, not decremented.

There are two subclasses that implement this one, for versions 1 and 2 of the protocol - PaymentChannelV1ServerState and PaymentChannelV2ServerState.

This class implements the core state machine for the server side of the protocol. The client side is implemented by PaymentChannelV1ClientState and PaymentChannelServerListener implements the server-side network protocol listening for TCP/IP connections and moving this class through each state. We say that the party who is sending funds is the client or initiating party. The party that is receiving the funds is the server or receiving party. Although the underlying Bitcoin protocol is capable of more complex relationships than that, this class implements only the simplest case.

To protect clients from malicious servers, a channel has an expiry parameter. When this expiration is reached, the client will broadcast the created refund transaction and take back all the money in this channel. Because this is specified in terms of block timestamps, it is fairly fuzzy and it is possible to spend the refund transaction up to a few hours before the actual timestamp. Thus, it is very important that the channel be closed with plenty of time left to get the highest value payment transaction confirmed before the expire time (minimum 3-4 hours is suggested if the payment transaction has enough fee to be confirmed in the next block or two).

To begin, we must provide the client with a pubkey which we wish to use for the multi-sig contract which locks in the channel. The client will then provide us with an incomplete refund transaction and the pubkey which they used in the multi-sig contract. We use this pubkey to recreate the multi-sig output and then sign that to the refund transaction. We provide that signature to the client and they then have the ability to spend the refund transaction at the specified expire time. The client then provides us with the full, signed multi-sig contract which we verify and broadcast, locking in their funds until we spend a payment transaction or the expire time is reached. The client can then begin paying by providing us with signatures for the multi-sig contract which pay some amount back to the client, and the rest is ours to do with as we wish.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class PaymentChannelServerState.State
The different logical states the channel can be in.

Nested Classes
Modifier and Type	Class and Description
`static class`	`PaymentChannelServerState.State` The different logical states the channel can be in.

Field Summary

Fields
Modifier and Type	Field and Description
`protected byte[]`	`bestValueSignature`
`protected Coin`	`bestValueToMe`
`protected TransactionBroadcaster`	`broadcaster`
`protected Transaction`	`contract`
`protected long`	`minExpireTime`
`protected ECKey`	`serverKey`
`protected StateMachine<PaymentChannelServerState.State>`	`stateMachine`
`protected StoredServerChannel`	`storedServerChannel`

Constructor Summary

Constructors
Constructor and Description
`PaymentChannelServerState(TransactionBroadcaster broadcaster, Wallet wallet, ECKey serverKey, long minExpireTime)` Creates a new state object to track the server side of a payment channel.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract ListenableFuture<Transaction>`	`close()` Closes this channel and broadcasts the highest value payment transaction on the network.
`protected abstract Script`	`createOutputScript()`
`Coin`	`getBestValueToMe()` Gets the highest payment to ourselves (which we will receive on settle(), not including fees)
`protected abstract ECKey`	`getClientKey()`
`abstract TransactionOutput`	`getClientOutput()`
`Transaction`	`getContract()` Gets the multisig contract which was used to initialize this channel
`Script`	`getContractScript()`
`long`	`getExpiryTime()`
`abstract Coin`	`getFeePaid()` Gets the fee paid in the final payment transaction (only available if settle() did not throw an exception)
`abstract int`	`getMajorVersion()`
`protected abstract Script`	`getSignedScript()` Gets the script that signatures should sign against.
`PaymentChannelServerState.State`	`getState()`
`protected abstract Multimap<PaymentChannelServerState.State,PaymentChannelServerState.State>`	`getStateTransitions()`
`protected Coin`	`getTotalValue()`
`boolean`	`incrementPayment(Coin refundSize, byte[] signatureBytes)` Called when the client provides us with a new signature and wishes to increment total payment by size.
`protected SendRequest`	`makeUnsignedChannelContract(Coin valueToMe)`
`ListenableFuture<PaymentChannelServerState>`	`provideContract(Transaction contract)` Called when the client provides the multi-sig contract.
`void`	`storeChannelInWallet(PaymentChannelServer connectedHandler)` Stores this channel's state in the wallet as a part of a `StoredPaymentChannelServerStates` wallet extension and keeps it up-to-date each time payment is incremented.
`protected void`	`updateChannelInWallet()`
`protected void`	`verifyContract(Transaction contract)` Verifies that the given contract meets a set of extra requirements

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - stateMachine
```
protected StateMachine<PaymentChannelServerState.State> stateMachine
```
  - broadcaster
```
protected final TransactionBroadcaster broadcaster
```
  - bestValueSignature
```
protected byte[] bestValueSignature
```
  - bestValueToMe
```
protected Coin bestValueToMe
```
  - serverKey
```
protected ECKey serverKey
```
  - minExpireTime
```
protected long minExpireTime
```
  - storedServerChannel
```
protected StoredServerChannel storedServerChannel
```
  - contract
```
protected Transaction contract
```
- Constructor Detail
  - PaymentChannelServerState
```
public PaymentChannelServerState(TransactionBroadcaster broadcaster,
                                 Wallet wallet,
                                 ECKey serverKey,
                                 long minExpireTime)
```
    Creates a new state object to track the server side of a payment channel.
    
    Parameters:
    
    broadcaster - The peer group which we will broadcast transactions to, this should have multiple peers
    
    wallet - The wallet which will be used to complete transactions
    
    serverKey - The private key which we use for our part of the multi-sig contract (this MUST be fresh and CANNOT be used elsewhere)
    
    minExpireTime - The earliest time at which the client can claim the refund transaction (UNIX timestamp of block)
- Method Detail
  - getMajorVersion
```
public abstract int getMajorVersion()
```
  - getState
```
public PaymentChannelServerState.State getState()
```
  - getStateTransitions
```
protected abstract Multimap<PaymentChannelServerState.State,PaymentChannelServerState.State> getStateTransitions()
```
  - provideContract
```
public ListenableFuture<PaymentChannelServerState> provideContract(Transaction contract)
                                                            throws VerificationException
```
    Called when the client provides the multi-sig contract. Checks that the previously-provided refund transaction spends this transaction (because we will use it as a base to create payment transactions) as well as output value and form (ie it is a 2-of-2 multisig to the correct keys).
    
    Parameters:
    
    contract - The provided multisig contract. Do not mutate this object after this call.
    
    Returns:
    
    A future which completes when the provided multisig contract successfully broadcasts, or throws if the broadcast fails for some reason Note that if the network simply rejects the transaction, this future will never complete, a timeout should be used.
    
    Throws:
    
    VerificationException - If the provided multisig contract is not well-formed or does not meet previously-specified parameters
  - makeUnsignedChannelContract
```
protected SendRequest makeUnsignedChannelContract(Coin valueToMe)
```
  - incrementPayment
```
public boolean incrementPayment(Coin refundSize,
                                byte[] signatureBytes)
                         throws VerificationException,
                                ValueOutOfRangeException,
                                InsufficientMoneyException
```
    Called when the client provides us with a new signature and wishes to increment total payment by size. + Verifies the provided signature and only updates values if everything checks out. If the new refundSize is not the lowest we have seen, it is simply ignored.
    
    Parameters:
    
    refundSize - How many satoshis of the original contract are refunded to the client (the rest are ours)
    
    signatureBytes - The new signature spending the multi-sig contract to a new payment transaction
    
    Returns:
    
    true if there is more value left on the channel, false if it is now fully used up.
    
    Throws:
    
    VerificationException - If the signature does not verify or size is out of range (incl being rejected by the network as dust).
    
    ValueOutOfRangeException
    
    InsufficientMoneyException
  - close
```
public abstract ListenableFuture<Transaction> close()
                                             throws InsufficientMoneyException
```
    Closes this channel and broadcasts the highest value payment transaction on the network.
    
    Returns:
    
    a future which completes when the provided multisig contract successfully broadcasts, or throws if the broadcast fails for some reason. Note that if the network simply rejects the transaction, this future will never complete, a timeout should be used.
    
    Throws:
    
    InsufficientMoneyException - If the payment tx would have cost more in fees to spend than it is worth.
  - getBestValueToMe
```
public Coin getBestValueToMe()
```
    Gets the highest payment to ourselves (which we will receive on settle(), not including fees)
  - getFeePaid
```
public abstract Coin getFeePaid()
```
    Gets the fee paid in the final payment transaction (only available if settle() did not throw an exception)
  - getContract
```
public Transaction getContract()
```
    Gets the multisig contract which was used to initialize this channel
  - getExpiryTime
```
public long getExpiryTime()
```
  - updateChannelInWallet
```
protected void updateChannelInWallet()
```
  - storeChannelInWallet
```
public void storeChannelInWallet(@Nullable
                                 PaymentChannelServer connectedHandler)
```
    Stores this channel's state in the wallet as a part of a StoredPaymentChannelServerStates wallet extension and keeps it up-to-date each time payment is incremented. This will be automatically removed when a call to PaymentChannelV1ServerState.close() completes successfully. A channel may only be stored after it has fully opened (ie state == State.READY).
    
    Parameters:
    
    connectedHandler - Optional PaymentChannelServer object that manages this object. This will set the appropriate pointer in the newly created StoredServerChannel before it is committed to wallet. If set, closing the state object will propagate the close to the handler which can then do a TCP disconnect.
  - getClientOutput
```
public abstract TransactionOutput getClientOutput()
```
  - getContractScript
```
public Script getContractScript()
```
  - getSignedScript
```
protected abstract Script getSignedScript()
```
    Gets the script that signatures should sign against. This is never a P2SH script, rather the script that would be inside a P2SH script.
    
    Returns:
  - verifyContract
```
protected void verifyContract(Transaction contract)
```
    Verifies that the given contract meets a set of extra requirements
    
    Parameters:
    
    contract -
  - createOutputScript
```
protected abstract Script createOutputScript()
```
  - getTotalValue
```
protected Coin getTotalValue()
```
  - getClientKey
```
protected abstract ECKey getClientKey()
```

Class PaymentChannelServerState

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

stateMachine

broadcaster

bestValueSignature

bestValueToMe

serverKey

minExpireTime

storedServerChannel

contract

Constructor Detail

PaymentChannelServerState

Method Detail

getMajorVersion

getState

getStateTransitions

provideContract

makeUnsignedChannelContract

incrementPayment

close

getBestValueToMe

getFeePaid

getContract

getExpiryTime

updateChannelInWallet

storeChannelInWallet

getClientOutput

getContractScript

getSignedScript

verifyContract

createOutputScript

getTotalValue

getClientKey