getBalance should return balance - minimum_allowed_balance about ilp-plugin-bells HOT 10 OPEN

I'd vote to add a separate getAvailableBalance call to the ledger plugin API. Sometimes I may want to know how much I owe/am owed and sometimes I want to know how much I have available to spend.

from ilp-plugin-bells.

The other option would be to have just one call which returns an object with balance min, max, current.

from ilp-plugin-bells.

I like the idea of having just one method that returns the relevant information

from ilp-plugin-bells.

ilp-plugin-virtual now has a getPeerBalance method which we could probably merge with this? @sharafian

from ilp-plugin-bells.

Yeah, getLimit and getPeerBalance implement this functionality, but are exported only by plugin virtual. getMax is trivial to implement, because it's just a config option. Some ledgers won't have maximum balances, though.

from ilp-plugin-bells.

One potential issue with querying them all via one method is that the way these numbers are used could be very different. Purely for the sake of example: 90% of the time you care only about getBalance and getLimit which are a quick local query. Very rarely you want getPeerBalance and getPeerLimit which could be a remote request. If we make it all one method, you're always to query all of them.

A possible solution (and perhaps a good idea from a simplicity and performance perspective) would be to keep a view of the balance in memory. I.e. every time the balance changes, the server/peer/blockchain/whatever sends you an update. The issues with that are 1) some ledgers may not support this and 2) it couldn't be transactional. (I.e. you might be looking at a stale balance)

So, what about:

• getBalance() => Promise.<String>
• getRemoteBalance() => Promise.<String>
• getMinBalance() => Promise.<String>
• getMaxBalance() => Promise.<String>

from ilp-plugin-bells.

I like the getMinBalance and getMaxBalance, but I don't understand the distinction between getBalance and getRemoteBalance in any cases other than plugin-virtual. What would the difference be in, say, plugin-bells?

from ilp-plugin-bells.

What would the difference be in, say, plugin-bells?

None. It would only be different for symmetric plugins with no consensus mechanism.

from ilp-plugin-bells.

Banks also have a concept of 'cleared balance', due historically to cheques which used to take several days to clear.
Creditcards have a concept of reservations.
There could be balance locked up in-flight in interledger payments
On blockchains, there could be money that has been submitted to the blockchain but not yet verified.
And as discussed, on trustlines there can be part of the balance which is 'disputed'.

So in general, I think there can be many ways in which part of your balance is (temporarily) unavailable for use in payments.

So I would try to always cache the remote balance (even if there is an update delay), and then my counter-proposal would be:

• getBalance() => Promise.<String> - the most pessimistic number (so excluding in-flight and also excluding disputed balance, according to latest cache of remote situation).
• getMinBalance() => Promise.<String> - the amount this ledger allows you to go under zero
• getMaxBalance() => Promise.<String> - how much you (as a user) trust this ledger for
• getDetailedBalance() => Promise.<Object> ->

var detailedBalance = {
  cleared: 'same as getBalance()',
  sending: 'locked up in unfulfilled/unrejected outgoing transactions',
  receiving: 'value of incoming transactions you didn\'t fulfill/reject yet',
  disputed: 'money you think you received, but peer thinks timed out, minus vice versa',
};

For blockchain-based ledgers, sending/receiving could also be used for payments that were already fulfilled, but not yet verified. I think it gives a more informed view of the status of a user's balance on a ledger.

from ilp-plugin-bells.

Interesting, definitely like that direction!

from ilp-plugin-bells.