docs: add settlement engine RFC

[kincaidoneil]

This standardizes an agreed API between @emschwartz, @adrianhopebailie, @matdehaast, @sappenin and I, with some minor changes I am proposing from the existing Swagger definition.

Areas that may need improvement:

• Explanation of how accounting works
• Clarity around how implementations should handle idempotency and undoing balance updates
• Not all the HTTP endpoints are nicely documented yet (but everything can still be included in an embedded Swagger definition)

Thoughts? What's unclear or needs better explanation? What's still "unaccounted" for? (no pun intended...)

[gakonst]

Regarding the asset scale, I do not see a clear benefit by making it configurable on a per request basis. IMO it should be a parameter on the settlement engine and the node's account.

Also, I'd expect that it's set to the amount of decimals of the currency, or some multiple of that such that you are able to make payments which are tinier than the minimum denomination (cf sub-sat payments in lightning)

e.g my account is configured to run with 9 decimals (1 satoshi), but the settlement engine is configured with 18. As such, I'd need to send 1e9 units (which would make 1 sat) before settlement happens

[sharafian]

This looks like a good start. I like the protocol itself, but I think the explanation could still use some work, especially because this specification is one of the longer ones.

[adrianhopebailie]

Regarding the asset scale, I do not see a clear benefit by making it configurable on a per request basis. IMO it should be a parameter on the settlement engine and the node's account.

If scale was configured you'd need a way for the SE to be made aware of the scale used by the connector and the connector to be made aware of the scale used by the SE.

This implies either:

1. some handshake between the systems to establish each other's config
2. the operator configures each system with the settings of the other system and we hope they are never out of sync

IMO, it's simpler to just put the scale in the API calls

[kincaidoneil]

Added an initial set of edits putting it in the context of Interledger and explaining how the accounting operates.

All comments regarding content prior to the "Settlement Engine HTTP API" heading hopefully should be addressed; most things after that are yet-to-be addressed.

[dora-gt]

I'm a bit confused here.

Why do we need 4 descriptions for these?
I think we could express the relationship between 2 nodes with either:

1. 2 positive values
   • positive payable value
   • positive receivable value
2. 1 positive/negative value
   • positive = receivable value
   • negative = payable value

I'm sorry if I have misunderstood.

[kincaidoneil]

Good question!

I'd highly recommend implementing it with these 2 values vs 1 single balance, but my goal here is less to explain how to implement it and much more to explain the best model to understand the accounting.

Part of the reason for laying it out this way is asking, how would an accountant talk about this interaction? What terms would they use?

On an implementation level, there are a few reasons to prefer this approach:

• A single value doesn't differentiate between a peer owing you money for packets you've fulfilled, or you owing the peer money for packets they've fulfilled, so you're losing information that might be useful. As an example, in Switch, logic around "does the user have enough capacity to receive this payment?" would take into account how much credit has already been extended from the receivable balance, which wouldn't be possible if there was a single balance. (Not saying we need to support that use case, but might be helpful as an example where this might be useful).
• Solves issues with prefunding: if it's a single balance, because there's way to differentiate between the two, sometimes money you prefund to a connector would cause the connector to trigger a settlement back to you, which is bad.

[dora-gt]

"does the user have enough capacity to receive this payment?"

Do we need capacity to receive money?

Also, it might be better to mention some cases that we might be able to utilize "prefunding".

[sappenin]

Why do we need 4 descriptions for these?
I'd highly recommend implementing it with these 2 values vs 1 single balance,

FWIW, both the Java and Rust implementations currently track balances using two different numbers:

• clearing_balance: correlates to the Accounts Receivable above.
• prepaid_amount: correlates to Accounts Payable above.

[matdehaast]

@emschwartz @adrianhopebailie Is there a preference on this?

I think we should just go with PUT. Its really a nit picky issue that doesn't functionally change anything

[sappenin]

@kincaidoneil Here are some suggestions around around clearer wording for asset units and scales.

• Other than giving some example, we shouldn't repeat "asset or currency" all over. Instead, we should just define "asset" as being lots of things, and then use "asset" everywhere.
• We shouldn't define anything in here in terms of "money" (assets can be any fungible thing) -- though I think it's good to actually use currency in our examples, which is what's there already.

Curious to hear what you think...I'm going to resolve my other comment on this topic.

[kincaidoneil]

Other than giving some example, we shouldn't repeat "asset or currency" all over. Instead, we should just define "asset" as being lots of things, and then use "asset" everywhere.

We shouldn't define anything in here in terms of "money" (assets can be any fungible thing) -- though I think it's good to actually use currency in our examples, which is what's there already.

Sounds good to me 👍

(I did like that "monetary unit" / "fractional monetary unit" are dictionary phrases, but agree they may not be general enough).

[emschwartz]

Can we merge this now? This has been open for a really long time and we'd like to be able to refer to it. All remaining discussions can happen in follow-up PRs

Addressed comments; reviewed version is outdated.