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.
new Payments(options);
Creates a new Payments instance.
options
-PaymentOptions
: options for Votings constructor.accountStore
-AccountStore
_:AccountStore
_ instancecontractLoader
-ContractLoader
_:ContractLoader
_ instanceexecutor
-Executor
_:Executor
_ instanceweb3
-Web3
_:Web3
_ instance
Payments
instance
const payments = new Payments({
accountStore,
contractLoader,
executor,
web3,
});
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
closingSig
-string
(optional): Cooperative-close signature from receiver
Promise
returns void
: resolved when done
await payments.closeChannel('0x00000000000000000000000000000000c0274ac7');
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
proof
-MicroProof
_: given microproof object after calling incrementBalanceAndSign
Promise
returns void
: resolved when done
payments.confirmPayment({
balance: 1,
sig: '0x1234567899'
});
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
channel
-MicroChannel
_: Channel to get info from. Default to channel
Promise
returns MicroChannelInfo
_: member info
await payments.getChannelInfo();
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
Promise
returns number
: challenge period number, in blocks
console.dir(await payments.getChallengePeriod());
// Output:
// 500
payments.getClosingSig(account);
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.
account
-string
: AccountId which should sign the closing signature (mostly the current active account)
Promise
returns string
: signed closing signature
console.dir(await payments.getClosingSig(account));
// Output:
// 0x1234567890ABCDEF
payments.isChannelValid(channel);
Health check for currently configured channel info
channel
-MicroChannel
_: Channel to get info from. Default to channel
boolean
: True if channel is valid, false otherwise
console.dir(payments.isChannelValid(channel));
// Output:
// True
payments.incrementBalanceAndSign(amount);
Ask user for signing a payment, which is previous balance incremented of amount. Warnings from signNewProof applies.
amount
-BigNumber|string
: Amount to increment in current balance
Promise
returns string
: signed signature
console.dir(await payments.incrementBalanceAndSign(new BigNumber(1)));
// Output:
// 0x1234567890ABCDEF
payments.loadChannelFromBlockchain(account, 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.
account
-string
: Sender/client's account addressreceiver
-string
: Receiver/server's account address
Promise
returns MicroChannel
_: channel info, if a channel was found
await payments.loadChannelFromBlockchain('0x2222222222222222222222222222222222222222', '0x2222222222222222222222222222222222222223');
payments.openChannel(account, receiver, deposit);
Open a channel for account to receiver, depositing some EVE on it. Replaces current channel data
account
-string
: Sender/client's account addressreceiver
-string
: Receiver/server's account addressdeposit
-BigNumber|string
: deposit in WEI
Promise
returns MicroChannel
_: channel info
await payments.openChannel('0x2222222222222222222222222222222222222222', '0x2222222222222222222222222222222222222223', new BigNumber(5));
payments.setChannelManager(channelManager);
sets a new channelmanager contract to the current instance
channelManager
-string
: the new channelmanager address
void
payments.setChannelManager('0x2222222222222222222222222222222222222222');
payments.setChannel(channel);
Set channel info. Can be used to externally [re]store an externally persisted channel info
channelManager
-MicroChannel
_: Channel info to be set
void
payments.setChannel({
account: '0x1234',
receiver: '0x1234'
block: 12346,
proof: {
balance: 1,
sig: '0x12345677899'
}
});
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.
proof
-MicroProof
_ (optional): Balance proof to be signed
Promise
returns MicroProof
_: signature
payments.signNewProof({
balance: 1,
sig: '0x12345677899'
});
payments.signMessage(msg);
Ask user for signing a string with eth_accounts_sign
msg
-string
: Data to be signed
Promise
returns string
: signed data
await payments.signMessage('This is a message');
payments.topUpChannel(deposit);
Top up current channel, by depositing some [more] EVE to it
deposit
-BigNumber|string
: EVE (in wei) to be deposited in the channel
Promise
returns void
: resolved when done
await payments.topUpChannel(new BigNumber(5));
balance
-BigNumber
: balance valuesig
-string
(optional): balance signature
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
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