Copyright | (c) Rune K. Svendsen, 2016 |
---|---|
License | PublicDomain |
Maintainer | runesvend@gmail.com |
Stability | experimental |
Portability | POSIX |
Safe Haskell | None |
Language | Haskell2010 |
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:
- sender public key
- receiver public key
- 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:
- hash/transaction ID
- index/vout of the funding output (paying to
getFundingAddress
address), - 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:
- a signing function which, given a hash, produces a signature that verifies against
cpSenderPubKey
inChannelParameters
- the value of the first channel payment
The sender will want to use flip
as the signing
function, where signMsg
senderPrivKeysenderPrivKey
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
as the signing function,
where signMsg
receiverPrivKeyreceiverPrivKey
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.
- channelWithInitialPaymentOf :: ChannelParameters -> FundingTxInfo -> (Hash256 -> Signature) -> BitcoinAmount -> (Payment, SenderPaymentChannel)
- sendPayment :: SenderPaymentChannel -> BitcoinAmount -> (Payment, SenderPaymentChannel)
- channelFromInitialPayment :: ChannelParameters -> FundingTxInfo -> (Hash256 -> Signature) -> Payment -> Either PayChanError ReceiverPaymentChannel
- recvPayment :: ReceiverPaymentChannel -> Payment -> Either PayChanError (BitcoinAmount, ReceiverPaymentChannel)
- getSettlementBitcoinTx :: ReceiverPaymentChannel -> BitcoinAmount -> Either PayChanError Tx
- getRefundBitcoinTx :: SenderPaymentChannel -> BitcoinAmount -> Tx
- getFundingAddress :: ChannelParameters -> Address
Documentation
channelWithInitialPaymentOf Source
:: ChannelParameters | Specifies channel sender and receiver, plus channel expiration date |
-> FundingTxInfo | Holds information about the transaction used to fund the channel |
-> (Hash256 -> Signature) | See |
-> BitcoinAmount | Value of initial payment. Must be greater than or equal to |
-> (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.
:: 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
:: 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 |
-> 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.
:: 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.
:: 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.
:: 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
.