interledgerjs / ilp-plugin-ethereum

Settle Interledger payments with ETH and ERC-20 tokens

Interledger Ethereum Payment Channel Plugin

🚨 Expect breaking changes while this plugin is in beta.

Overview

Settle Interledger packets with streaming micropayments of ETH or an ERC-20 token.

Two plugins peer with one another over WebSockets and exchange Interledger packets denominated in ETH or a particular ERC-20 token. One or both peers may collateralize a unidirectional, or one-way payment channel from themselves to the other peer. Then, they may send settlements as payment channel claims at configurable frequency. Two peers may extend nearly no credit to one another and require settlements before or after every ILP packet, or extend greater credit to one another and settle less frequently.

Machinomy smart contracts are used for the unidirectional ETH and ERC-20 payment channels.

Install

npm install ilp-plugin-ethereum

Node.js 10+ is required.

Roadmap

• ETH payment channel client
• Optimizations for streaming payments
• ERC-20 payment channel client
• More robust testing
• Refactor plugin architecture to use HTTP-based interface
• Eliminate internal boilerplate code
• Update Machinomy contract to support MetaMask and hardware wallets
• Smart liquidity management and negotiation for incoming capacity
• Audit codebase

API

Here are the available options to pass to the plugin. Additional configuration options are also inherited from ilp-plugin-btp if the plugin is a client, and ilp-plugin-mini-accounts if the plugin is a server.

All ILP packet amounts and accounting must use units of gwei, or units to 9 decimal places (wei was such a small unit that it introduced issues calculating an exchange rate). For payment channel claims, the plugin converts the amount into wei, or if using an ERC-20 token, converts to the number of decimal places of the token.

ethereumPrivateKey

• Required
• Type: string
• Private key of the Ethereum account used to sign transactions, corresponding to the address which peers must open channels to

ethereumProvider

• Type:
  • "homestead" to use Infura & Etherscan on mainnet
  • "ropsten" to use Infura & Etherscan on the Ropsten proof of work testnet
  • "kovan" to use Infura & Etherscan on the Kovan proof of authority testnet (Parity)
  • "rinkeby" to use Infura & Etherscan on the Rinkeby proof of authority testnet (Geth)
  • ethers.providers.Provider to supply a custom provider
• Default: "homestead"
• Provider used to connect to an Ethereum node for a particular chain/testnet

ethereumWallet

• Type: ethers.Wallet
• Ethers wallet used to sign transactions
• Must be connected to a provider to query the network
• Supercedes and may be provided in lieu of ethereumPrivateKey and ethereumProvider

role

• Type:
  • "client" to connect to a single peer or server that is explicity specified
  • "server" to enable multiple clients to openly connect to the plugin
• Default: "client"

Settlement

Clients do not automatically open channels, nor settle automatically. Channels must be funded or closed through the internal API of the plugin. Sending payment channel claims can be triggered by invoking sendMoney on the plugin, and the money handler is called upon receipt of incoming payment channel claims (set using registerMoneyHandler).

Servers do automatically open channels. If a client has opened a channel with a value above the configurable minIncomingChannelAmount, the server will automatically open a channel back to the client with a value of outgoingChannelAmount. When the channel is half empty, the server will also automatically top up the value of the channel by the outgoingChannelAmount.

The balance configuration has been simplified for servers. Clients must prefund before sending any packets through a server, and if a client fulfills packets sent to them through a server, the server will automatically settle such that they owe 0 to the client. This configuration was chosen because it assumes the server would extend no credit to an anonymous client, and clients extend little credit to servers, necessitating frequent settlements.

Closing Channels

Both clients and servers operate a channel watcher to automatically close a disputed channel if it's profitable to do so, and both will automatically claim channels if the other peer requests one to be closed.

Transaction Fees

In the current version of this plugin, there is no accounting for transaction fees on servers. In previous versions, transaction fees where added to the client's balance, which forced them to prefund the fee, but this made accounting nearly impossible from the client's perspective: it was opaque, and there was no negotiation. The balances of the two peers would quickly get out of sync.

Since clients must manually open & close channels, they do have the ability to authorize transaction fees before sending them to the chain.

Future Work

The current model introduces problems with locking up excessive liquidity for servers, and doesn't provide sufficient denial of service protections against transaction fees. Ultimately, clients will likely have to purchase incoming capacity (possibly by amount and/or time) through prefunding the server, and pay for the server's transaction fees to open and close a channel back to them. However, this may require a more complex negotiation and fee logic that is nontrivial to implement.

tokenAddress

• Type: string
• Ethereum address of the ERC-20 token contract
• Used to send and receive a particular ERC-20 token asset, instead of ether
• Each payment channel can be used with only ETH, or only a predefined ERC-20 token

contractAddress

• Type: string
• Custom Ethereum address for the Machinomy payment channel contact
• Useful for private blockchains or testing with Ganache

maxPacketAmount

• Type: BigNumber, number, or string
• Default: Infinity
• Maximum amount in gwei above which an incoming packet should be rejected

outgoingChannelAmount

• Type: BigNumber, number, or string
• Default: 50000000 gwei, or 0.05 ether
• Amount in gwei to use as a default to fund an outgoing channel up to
• Note: this is primarily relevant to servers, since clients that don't automatically open channels may manually specify the amount

minIncomingChannelAmount

• Type: BigNumber, number, or string
• Default: Infinity gwei (channels will never automatically be opened)
• Value in gwei that a peer's incoming channel must exceed if an outgoing channel to the peer should be automatically opened

channelWatcherInterval

• Type: BigNumber, number, or string
• Default 60000 ms, or 1 minute
• Number of milliseconds between each run of the channel watcher, which checks if the peer started a dispute and if so, claims the channel if it's profitable

outgoingDisputePeriod

• Type: BigNumber, number, or string
• Default: 34560 blocks, or approximately 6 days, assuming 15 second blocks
• Number of blocks for dispute period when opening new outgoing channels

While the channel is open, the sender may begin the dispute period. If the receiver does not claim the channel before the specified number of blocks elapses and the dispute period ends, all the funds can go back to the sender. Disputing a channel can be useful if the receiver is unresponsive or excessive collateral is locked up.

minIncomingDisputePeriod

• Type: BigNumber, number, or string
• Default: 17280 blocks, or approximately 3 days, assuming 15 second blocks
• Minimum number of blocks for the dispute period in order to accept an incoming channel

In case the sender starts a dispute period, the receiver may want to allot themselves enough time to claim the channel. Incoming claims from channels with dispute periods below this floor will be rejected outright.

ilp-plugin-ethereum's Issues

Support custom signing keys in Machinomy paychan contracts

Since each claim requires the private key to sign it (and each stream requires signing many claims), only custodial wallets may use this. With custom signing keys, MetaMask and hardware wallet integration for client software would be feasible.

Error: Cannot find module 'machinomy/lib/payment'

Add unit tests

What happened to the unit tests? I noticed the branch is gone.

A lot of those tests were testing balance/account/store logic as well as packet construction very thoroughly. If they are gone, it is very possible that somebody could edit the plugin and cause a minor breaking change (like balance logic not being calculated properly or persisted to the store) and the integration tests would still pass. I feel this could be pretty dangerous considering the plugin is in beta and will have updates.

Include a link to the source code of the smart contract used

This would be helpful for anyone looking at how this plugin works under the hood

Race condition when opening client channel

There is a race condition in the code that establishes a client channel.

support a design map

Incorrect log when request peer to close channel fails

ilp-plugin-ethereum/src/account.ts

Line 1243 in 316ac9f

const updatedChannel = this.refreshChannel(

This line should await the updated channel state before logging that it was successful (and log if the state is not updated).

Add more intelligent nonce management for concurrent txs

Refer to MetaMask/metamask-extension#3475 and https://github.com/MetaMask/nonce-tracker/blob/master/index.js for ideas

Logs incorrectly report fee in unit of ERC-20, rather than ETH

e.g. Depositing 10 DAI to channel for fee of 0.00048373 DAI

Add persistent channel watcher

If a server ever goes offline and comes back online, the channel watcher currently does not watch open channels if the client is not connected.

Not working with Machinomy ^1.6.1

It looks like this plugin is incompatible with machinomy v.1.6.1 despite it as a dependency.

An example:
This function call: https://github.com/interledgerjs/ilp-plugin-ethereum-asym-client/blob/58a71f3c6310188ea668dfd21d431eeb98ba1f69/index.js#L93-L96
Doesn't match what machinomy expects: https://github.com/machinomy/machinomy/blob/b816cb4621bf6e0e51324920a7762dcc262abe49/index.ts#L264-L269

I found a few others incompatibilities well.

Upgrade to Ethers v5 beta

Limit incoming queue to a single claim

On a T04 errors, the plugin sends the latest claim to the peer. Often, this requires verifying the signature, which if many T04s are triggered, can overwhelm the plugin/connector.

Alternatively, only allow a single validate claim task in the queue, and if a new one is enqueued, drop any others without running them.

Estimate gas for ERC-20 approve, then add open/deposit hardcoded gas limit

As opposed to having a hardcoded gas limit for the two combined operations. (Machinomy gas usage for those operations is probably pretty constant, but ERC-20 implementations could in theory use more or less gas.)

Return ILP Reject packets instead of throwing

Same as interledgerjs/ilp-plugin-xrp-asym-server#20

Built-in mechanism to start settling

This would trigger the counterparty to claim if it's profitable to do so, enabling the sender to get their collateral back.