The goal is just to level-set and have a discussion about what we need to consider in designing a settlement architecture and propose some ideas. Mapping the Solution Space as @emschwartz suggested.
The current architecture looks like this:
All of the Settlement Business Logic and the Settlement System Interface are in the plugins AND all ILP packets go through the plugins too. @emschwartz gave a nice breakdown of the pros and cons of this approach in Plugin Architecture and Ledger Integrations. To summarise; the plugin has all the info it needs to implement sophisticated Settlement Business Logic BUT it is all tightly coupled with the interface to the Settlement System, the interface to the other connector and must be implemented in Javascript (or at least wrapped in a Javascript adaptor).
NOTE: Not shown here, but adding significant complexity is the lifecycle management aspects of the current architecture. A plugin can be in numerous lifecycle states (connecting, connected, disconnected, terminated etc) which are not granular enough to indicate the state of the multiple connections the plugin maintains (to the peer, to the settlement system etc).
The Settlement Engine
We’ve talked a lot about a “Settlement Engine” but I don’t believe we all agree on what that is. Below are my understandings of the two proposals on the table and an attempt to come to agreement on some definitions.
I’ve given the “Settlement Engine” a specific definition which I think is consistent with the use of the descriptor “Engine” in other architectures; it is responsible for orchestrating complex business logic.
I’ve also defined what I call the “Ledger Adaptor” as a separate component that simply holds settlement system-specific integration logic. i.e. The Ledger Adaptor knows how to speak to a settlement system but it only performs operations on that system when instructed to do so by the Settlement Engine.
The interface to the Ledger Adaptor is unsurprisingly familiar (sendMoney, receiveMoney, sendData, receiveData) but in contrast to the Javascript Ledger Interface, calling these APIs is not expected to have side-effects.
E.g. Calling sendMoney on the Ledger Adaptor results in a payment being sent over the settlement system. This may succeed or fail and the Settlement Engine decides how to proceed once the result of this operation is known.
The Ledger Adaptor is also able to call sendData on the Settlement Engine which is simply a way of requesting that a message is passed to the corresponding Ledger Adaptor on the peer. (e.g. To exchange a Payment Channel claim)
This SHOULD be in the form of an ILP packet addressed to peer.settle.* hence I have proposed that this would be “injected” by the Settlement Engine into the outgoing middleware pipeline but really this is up to implementors.
Note that the Settlement Engine could also initiate a message to the other Settlement Engine.
In both proposed architectures the Settlement Engine tracks the various balances and balance change events in both the clearing accounts (Peer ILP balances) and settlement accounts (Settlement system balances) and decides when to make a settlement on the settlement system (call sendMoney on the Ledger Adaptor).
The Settlement Engine also receives notifications of incoming settlements from the Ledger Adaptor. Not shown, but required is a mechanism for the Settlement Engine to query the Ledger Adaptor for balances on the settlement system.
The major difference between the two proposals is where the Settlement Engine is implemented.
Proposal 1 - Internal Settlement Engine
In this architecture the Settlement Engine is internal to the connector.
The interface that needs to be defined is between connectors and Ledger Adaptors. It likely includes:
- sendMoney (perform a settlement)
- receiveMoney (acknowledge an incoming settlement)
- sendData (send a message to the Ledger Adaptor on the peer)
- receiveData (accept a message from the Ledger Adaptor on the other peer)
- getBalance (get the current balance of the settlement account, i.e. available liquidity for settlements)
Proposal 2 - External Settlement Engine
In this architecture the Settlement Engine is external to the connector.
An interface needs to be defined between the Settlement Engine and the Connector AND between the Ledger Adaptor and the Settlement Engine:
Settlement Engine → Ledger Adaptor:
- sendMoney (perform a settlement)
- receiveMoney (acknowledge an incoming settlement)
- receiveData (accept a message from the Ledger Adaptor on the other peer)
- getBalance (get the current balance of the settlement account, i.e. available liquidity for settlements)
Settlement Engine → Connector
- getBalance (get the current balance of the clearing account, i.e. ILP balance)
- setBalance (update the current balance of the clearing account, apply a delta)
- sendData (send a message to the Settlement Engine on the peer)
- receiveData (accept a message from the Settlement Engine on the other peer)
Next steps…
If we agree on what is being proposed then I think we can proceed to discussing the pros and cons of the two designs and decide which we should use (or even find a way to support both).