Interledger Protocol Proposal
Standardized Deposit and Withdrawal
Currently, there is no standardized way for users of an ILP service to deposit or withdraw funds from their account. In other words, there is no prescribed means of moving money into or out of the ILP system, nor the API support to update account balances and issue transactions on the appropriate ledger.
This is an important core component of any ILP service provider that is facing the edges of the network (as opposed to acting solely as a connector), and requiring each node to independently scope and implement such a system could significantly hinder adoption due to increased cost and security risk creating a substantial hurdle.
Consequently, we propose that (1) such a standard be created and (2) that reference implementations for various ledgers be produced. In sticking with the general ILP philosophy, this solution should be standardized across ledgers with the lower layer ledger mechanics (Layer 1 & 2) abstracted. We additionally argue that systems such as the ILP account system and the ledger interface/key management system should be self-contained and only publicly expose atomic, complete functions to ensure security, prevent dependencies, and avoid code/function duplication.
We propose expanding the current Settlement Engine concept to a General Ledger Interface (GLI), which handles all settlement functions on behalf of an ILP node for a given ledger. The GLI will facilitate ILP node to ILP node (i.e. ILP peering) settlements as well as the on-ledger deposit and withdrawal transactions.
The GLI would be the sole custodial module of the access to its particular settlement rail (the key manager in the case of a cryptocurrency), which restricts complexity bloat in access management and, more importantly, avoids any race conditions that could arise during withdrawals with separate key managers.
Besides the ledger itself, the GLI will only interface with the ILP node. This insulates its safety critical functionality and also ensures that the ledger settlement details are appropriately abstracted from any service built on top of the ILP node.
We believe the alternative — requiring the user service to bypassing the ILP node to interface with the settlement module directly — is an inferior system design choice for several reasons:
- Breaks down the layering structure and removes the abstraction that is one of the key value propositions of ILP (services interacting with ILP on L3 should not have to interface with L1/L2)
- Creates a large number of potential edge cases since both ILP node and service provider will both be communicating with the settlement module
- Increases the complexity of deploying and managing a service
Deposit and withdrawal would further require two additional, asynchronous API methods at the ILP node, one for each action. When these API functions are called, the ILP node interfaces with the GLI to provide the response and, if appropriate, execute a transaction on the ledger. The asynchronous API methods should provide a service that is similar to the features provided by “reliable transaction submission” in which the status shall guarantee the finality of the on-ledger transaction. Conventionally there should be two status provided by these APIs: the first status confirms/rejects the submission of the withdraw/deposit request and the second status confirms/rejects the finality of the submitted transaction.
The Deposit API function would instruct the ILP node to return an “address” (which would vary in form, depending on the currency rail), with all the necessary information for a user to deposit into the system. In the case of XRP, this would involve the GLI providing an XRP address plus a tag (or an X-address) that is forwarded to the client via the ILP node. Then, the GLI would listen on the ledger for the transaction and report it to the ILP node, which would update the appropriate account balance and send a success notification to the client.
The Withdraw API function would provide the ILP node with a similar “address” that has all the necessary information for the withdrawal transaction plus amount and account. The GLI would then execute the transaction on the ledger and provide confirmation to the ILP node, which would update the appropriate account balance and send a success notification to the client.
The GLI could either be an expansion of the Settlement Engine specification itself or a broader module that includes the Settlement Engine, the Deposit/Withdrawal Engine, and a Key Management System. In the case of the latter, access to the custodied funds would need to be serialized and controlled via a semaphore to prevent unforeseen race conditions.
Handling withdrawal can be tricky in the presence of unsettled channels with ILP peers. For example: User X wishes to withdraw 100 XRP from ILP service provider A who is currently has 0 XRP in its XRP Settlement Engine address and 100 XRP owed in a channel with ILP node B. A must decide whether that should force a settlement of its channel with B or if it should return an error on the Withdraw request.