Payments¶
Class Name | Payments |
---|---|
Extends | Logger |
Source | payments.ts |
Examples | payments.spec.ts |
Payments are a Service to open unidirectional payment channels to other accounts. You can open a payment channel to another account and do some micropayments offchain.
The heart of the system lies in its sender -> receiver off-chain transactions. They offer a secure way to keep track of the last verified channel balance. The channel balance is calculated each time the sender pays for a resource. He is prompted to sign a so-called balance proof, i.e., a message that provably confirms the total amount of transferred tokens. This balance proof is then sent to the receiver’s server. If the balance proof checks out after comparing it with the last received balance and verifying the sender’s signature, the receiver replaces the old balance value with the new one.
constructor¶
new Payments(options);
Creates a new Payments instance.
Parameters¶
options
-PaymentOptions
: options for Votings constructor.accountStore
-AccountStore
:AccountStore
instancecontractLoader
-ContractLoader
:ContractLoader
instanceexecutor
-Executor
:Executor
instanceweb3
-Web3
:Web3
instance
Returns¶
Payments
instance
Example¶
const payments = new Payments({
accountStore,
contractLoader,
executor,
web3,
});
closeChannel¶
payments.closeChannel(closingSig);
Closes a given payment channel, when a closing signature is available, the channel will be closed cooperately, otherwise the the channel will be close uncooperately and the sender or receiver has to wait a given amount of blocks (500) to get the funds out of the payment channel
Parameters¶
closingSig
-string
(optional): Cooperative-close signature from receiver
Returns¶
Promise
returns void
: resolved when done
confirmPayment¶
payments.confirmPayment(proof);
Persists next_proof to proof. This method must be used after successful payment request, or right after signNewProof is resolved, if implementation don’t care for request status
Parameters¶
proof
-MicroProof
: given microproof object after calling incrementBalanceAndSign
Returns¶
Promise
returns void
: resolved when done
getChannelInfo¶
payments.getChannelInfo(channel);
Get channel details such as current state (one of opened, closed or settled), block in which it was set and current deposited amount
Parameters¶
channel
-MicroChannel
: Channel to get info from. Default to channel
Returns¶
Promise
returns MicroChannelInfo
: member info
getChallengePeriod¶
payments.getChallengePeriod();
Get contract’s configured challenge’s period. As it calls the contract method, can be used for validating that contract’s address has code in current network
Parameters¶
Returns¶
Promise
returns number
: challenge period number, in blocks
getClosingSig¶
payments.getClosingSig(signerId);
Get the closing balance signature signed from the defined account. This signature can be used to transfer it from the recevier to the sender when the sender wants to close the payment channel. Otherwise when the receiver wants to close the channel cooperative he uses the closign signature to close th channel directly.
Parameters¶
signerId
-string
: identity or account which should sign the closing signature (mostly the current active identity/account)
Returns¶
Promise
returns string
: signed closing signature
isChannelValid¶
payments.isChannelValid(channel);
Health check for currently configured channel info
Parameters¶
channel
-MicroChannel
: Channel to get info from. Default to channel
Returns¶
boolean
: True if channel is valid, false otherwise
incrementBalanceAndSign¶
payments.incrementBalanceAndSign(amount);
Ask user for signing a payment, which is previous balance incremented of amount. Warnings from signNewProof applies.
Parameters¶
amount
-BigNumber|string
: Amount to increment in current balance
Returns¶
Promise
returns string
: signed signature
Example¶
console.dir(await payments.incrementBalanceAndSign(new BigNumber(1)));
// Output:
// 0x1234567890ABCDEF
loadChannelFromBlockchain¶
payments.loadChannelFromBlockchain(sender, receiver);
Scan the blockchain for an open channel, and load it with 0 balance. The 0 balance may be overwritten with setBalance if server replies with a updated balance on first request. It should ask user for signing the zero-balance proof. Throws/reject if no open channel was found. Additionally a starting block can be provided to avoid starting from block 0 when looking for payment channels.
Parameters¶
sender
-string
: identity or account of sender/clientreceiver
-string
: Receiver/server’s account addressstartBlock
-number
(optional): block to start scanning for transactions, defaults to0
Returns¶
Promise
returns MicroChannel
: channel info, if a channel was found
Example¶
await payments.loadChannelFromBlockchain('0x2222222222222222222222222222222222222222', '0x2222222222222222222222222222222222222223');
openChannel¶
payments.openChannel(account, receiver, deposit);
Open a channel for account to receiver, depositing some EVE on it. Replaces current channel data
Parameters¶
account
-string
: Sender/client’s identity or accountreceiver
-string
: Receiver/server’s account addressdeposit
-BigNumber|string
: deposit in WEI
Returns¶
Promise
returns MicroChannel
: channel info
Example¶
await payments.openChannel('0x2222222222222222222222222222222222222222', '0x2222222222222222222222222222222222222223', new BigNumber(5));
setChannelManager¶
payments.setChannelManager(channelManager);
sets a new channelmanager contract to the current instance
Parameters¶
channelManager
-string
: the new channelmanager address
Returns¶
void
setChannel¶
payments.setChannel(channel);
Set channel info. Can be used to externally [re]store an externally persisted channel info
Parameters¶
channelManager
-MicroChannel
: Channel info to be set
Returns¶
void
Example¶
payments.setChannel({
account: '0x1234',
receiver: '0x1234'
block: 12346,
proof: {
balance: 1,
sig: '0x12345677899'
}
});
signNewProof¶
payments.signNewProof(proof);
Ask user for signing a channel balance. Notice it’s the final balance, not the increment, and that the new balance is set in next_proof, requiring a confirmPayment call to persist it, after successful request.
Implementation can choose to call confirmPayment right after this call resolves, assuming request will be successful after payment is signed.
Parameters¶
proof
-MicroProof
(optional): Balance proof to be signed
Returns¶
Promise
returns MicroProof
: signature
signMessage¶
payments.signMessage(msg);
Ask user for signing a string with eth_accounts_sign
Parameters¶
msg
-string
: Data to be signed
Returns¶
Promise
returns string
: signed data
topUpChannel¶
payments.topUpChannel(deposit);
Top up current channel, by depositing some [more] EVE to it
Parameters¶
deposit
-BigNumber|string
: EVE (in wei) to be deposited in the channel
Returns¶
Promise
returns void
: resolved when done
Example¶
await payments.topUpChannel(new BigNumber(5));
= Additional Components =¶
Interfaces¶
MicroProof¶
balance
-BigNumber
: balance valuesig
-string
(optional): balance signature
MicroChannel¶
account
-string
: Sender/client’s account addressreceiver
-string
: Receiver/server’s account addressblock
-number
: Open channel block numberproof
-MicroProof
: Current balance proofnext_proof
-MicroProof
(optional): Next balance proof, persisted with confirmPaymentclosing_sig
-string
(optional): Cooperative close signature from receiver
MicroChannelInfo¶
state
-string
: Current channel state, one of ‘opened’, ‘closed’ or ‘settled’block
-number
: Block of current state (opened=open block number, closed=channel close requested block number, settled=settlement block number)deposit
-BigNumber
: Current channel deposited sumwithdrawn
-BigNumber
: Value already taken from the channel