bitcoin-payment-channel-0.1.0.0: Library for working with Bitcoin payment channels

Copyright(c) Rune K. Svendsen, 2016
LicensePublicDomain
Maintainerrunesvend@gmail.com
Stabilityexperimental
PortabilityPOSIX
Safe HaskellNone
LanguageHaskell2010

Data.Bitcoin.PaymentChannel

Description

In order to set up a payment channel between a sender and a receiver, the two parties must first agree on three parameters for the channel:

  1. sender public key
  2. receiver public key
  3. channel expiration date

These parameters are contained in ChannelParameters, from which a channel funding address can be derived using getFundingAddress. The transaction which pays to this address is the channel funding transaction, and information about it is contained in a FundingTxInfo. So, the channel funding transaction will contain an output which pays to the address returned by getFundingAddress, and once this transaction is created and in the blockchain, a SenderPaymentChannel and ReceiverPaymentChannel instance can be created, after first creating the FundingTxInfo instance. FundingTxInfo contains three pieces of information about the funding transaction:

  1. hash/transaction ID
  2. index/vout of the funding output (paying to getFundingAddress address),
  3. value of the funding output (paying to getFundingAddress address)

With ChannelParameters and FundingTxInfo, the sender can create a new SenderPaymentChannel, plus the first channel payment, using channelWithInitialPaymentOf. channelWithInitialPaymentOf takes two additional arguments:

  1. a signing function which, given a hash, produces a signature that verifies against cpSenderPubKey in ChannelParameters
  2. the value of the first channel payment

The sender will want to use flip signMsg senderPrivKey as the signing function, where senderPrivKey is the private key from which cpSenderPubKey is derived. channelWithInitialPaymentOf will return the first channel Payment as well as the new SenderPaymentChannel state. The new state is stored, and the Payment transferred to the receiver.

The receiver will now create its own channel state object, ReceiverPaymentChannel, using channelFromInitialPayment. channelFromInitialPayment takes the same ChannelParameters and FundingTxInfo as was provided by the sender, and, in addition, the receiver signing function (used to produce the settlement transaction that closes the payment channel), and the first channel Payment, received from the sender. The receiver will want to use flip signMsg receiverPrivKey as the signing function, where receiverPrivKey is the private key from which cpReceiverPubKey is derived.

Now the payment channel is open and ready for transmitting value. A new Payment is created by the sender with sendPayment, which yields a new payment, that increases the total value transmitted to the receiver by the specified amount, and an updated SenderPaymentChannel state. The receiver will verify and register this Payment on its side using recvPayment, which, on success, returns the value received with this payment plus the updated ReceiverPaymentChannel state object.

Payments can flow from the sender to receiver until either the channel is exhausted, or getting close to expiration (see important note below). In either case the receiver will use getSettlementBitcoinTx to create the settlement Bitcoin transaction, and publish this transaction to the Bitcoin network. The settlement Bitcoin transaction pays the total value transmitted over the channel to the receiver and the rest back to the sender.

IMPORTANT: Channel setup is risk free because the sender can derive a refund Bitcoin transaction using getRefundBitcoinTx, which returns the bitcoins used to fund the channel back to the sender. This refund transaction, however, is not valid until the expiration date specified in ChannelParameters, but it is paramount that the value receiver gets a settlement transaction included in a block before the refund transaction becomes valid. Due to the fact that Bitcoin network time is allowed to drift up to two hours from actual time, and the fact that finding new Bitcoin blocks does not occur according to any schedule, it would be wise for the receiver to publish a settlement transaction at least 4 hours before the specified channel expiration time, and possibly earlier, if the receiver wants to be cautious.

Synopsis

Documentation

channelWithInitialPaymentOf Source

Arguments

:: ChannelParameters

Specifies channel sender and receiver, plus channel expiration date

-> FundingTxInfo

Holds information about the transaction used to fund the channel

-> (Hash256 -> Signature)

See spcSignFunc

-> BitcoinAmount

Value of initial payment. Must be greater than or equal to minimumInitialPayment

-> (Payment, SenderPaymentChannel)

Initial payment and new sender state object

Create a new SenderPaymentChannel. A SenderPaymentChannel object is created by supplying information about the channel and the funding transaction, as well as the value of the first payment. Returns a new SenderPaymentChannel state object and the first channel payment.

sendPayment Source

Arguments

:: SenderPaymentChannel

Sender state object

-> BitcoinAmount

Amount to send (the actual payment amount is capped so that it doesn't overflow the maximum channel value)

-> (Payment, SenderPaymentChannel)

Payment and updated sender state object

Create new payment of specified value.

channelFromInitialPayment Source

Arguments

:: ChannelParameters

Specifies channel sender and receiver, plus channel expiration date

-> FundingTxInfo

Holds information about the transaction used to fund the channel

-> (Hash256 -> Signature)

Function which produces a signature, over a hash, which verifies against cpReceiverPubKey

-> Payment

Initial channel payment

-> Either PayChanError ReceiverPaymentChannel

Receiver state object

Create new ReceiverPaymentChannel. A channel is initialized with various information about the payment channel, as well as the first channel payment produced by the sender.

recvPayment Source

Arguments

:: ReceiverPaymentChannel

Receiver state object

-> Payment

Payment to verify and register

-> Either PayChanError (BitcoinAmount, ReceiverPaymentChannel)

Value received plus new receiver state object

Register, on the receiving side, a payment made by sendPayment on the sending side. Returns error if either the signature or payment amount is invalid, and otherwise the amount received with this Payment and a new state object.

getSettlementBitcoinTx Source

Arguments

:: ReceiverPaymentChannel

Receiver state object

-> BitcoinAmount

Bitcoin transaction fee

-> Either PayChanError Tx

Settling Bitcoin transaction

The value transmitted over the channel is settled when this transaction is in the Blockchain. The receiver will want to make sure a transaction produced by this function is included in a Bitcoin block before the refund transaction becomes valid (see getRefundBitcoinTx). The sender can only close the channel before expiration by requesting this transaction from the receiver and publishing it to the Bitcoin network. Returns NoValueTransferred if no payment has been received yet.

getRefundBitcoinTx Source

Arguments

:: SenderPaymentChannel

Sender state object

-> BitcoinAmount

Refund transaction fee

-> Tx

Refund Bitcoin transaction

Produces a Bitcoin transaction which sends all channel funds back to the sender. Will not be accepted by the Bitcoin network until the expiration time specified in ChannelParameters. Receiver beware of Bitcoin network time drift and the unpreditable nature of finding new blocks.

getFundingAddress :: ChannelParameters -> Address Source

Derive a Bitcoin address, for funding a payment channel, from ChannelParameters. The transaction which pays to this address is the channel funding transaction, and information about this transaction is contained in FundingTxInfo.