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 instance
- contractLoader - ContractLoader: ContractLoader instance
- executor - Executor: Executor instance
- web3 - 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

Example

await payments.closeChannel('0x00000000000000000000000000000000c0274ac7');

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

Example

payments.confirmPayment({
  balance: 1,
  sig: '0x1234567899'
});

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

Example

await payments.getChannelInfo();

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

Example

console.dir(await payments.getChallengePeriod());
// Output:
// 500

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

Example

console.dir(await payments.getClosingSig(account));
// Output:
// 0x1234567890ABCDEF

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

Example

console.dir(payments.isChannelValid(channel));
// Output:
// True

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/client
receiver - string: Receiver/server’s account address
startBlock - number (optional): block to start scanning for transactions, defaults to 0

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 account
receiver - string: Receiver/server’s account address
deposit - 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

Example

payments.setChannelManager('0x2222222222222222222222222222222222222222');

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

Example

payments.signNewProof({
  balance: 1,
  sig: '0x12345677899'
});

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

Example

await payments.signMessage('This is a message');

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 value
sig - string (optional): balance signature

MicroChannel

account - string: Sender/client’s account address
receiver - string: Receiver/server’s account address
block - number: Open channel block number
proof - MicroProof: Current balance proof
next_proof - MicroProof (optional): Next balance proof, persisted with confirmPayment
closing_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 sum
withdrawn - BigNumber: Value already taken from the channel