Idea to rename "getWithdrawableAmount" to "getRecipientAmount", and "getReturnableAmount" to "getSenderAmount"

[PaulRBerg]

In a similar vein to #222, what would you guys say about renaming getWithdrawableAmount to getRecipientAmount, and getReturnableAmount to getSenderAmount?

"withdrawable" can be confusing, because it's not obvious that the amount is the recipient's.

Alternatives: getRecipientBalance and getSenderBalance, to signal a difference between static amounts (such as the deposit amount) and dynamic streaming balances.

[PaulRBerg]

Some second thoughts - one issue with getRecipientAmount is that it doesn't communicate what kind of amount it is. That is, it's not clear whether the amount is the streamed amount (total aggregate, including withdrawals) or the withdrawable amount (net of withdrawals).

However, I believe that getRecipientBalance still sounds good.

[razgraf]

I like withdrawable, but I'd be ok renaming it if we figure out something better.
I think get__Balance or get__Amount will cause tremendous misunderstandings.

The one place where withdrawable shines brightest is in explaining that those funds are at least one-action away from being in the hands of our users (recipient or else). Funds that are streamed are not inside the user's wallet, but in an intermediary smart contract. Referring to the recipient's-balance or -amount is in direct conflict with the actual balanceOf that user, which may trick the user into thinking they should be looking in their wallet for those funds already.

#222 is different in the sense that (1) we have two types of amounts there, so separating them by sender/recipient makes sense and (2) those funds will be in the hands of the user (in their wallet) by the time of that Event.

[PaulRBerg]

Thanks for for sharing your feedback, @razgraf. Based on the below, I suggest we sleep more on this idea/ topic before making a decision.

I think get__Balance or get__Amount will cause tremendous misunderstandings.

First, there is a major difference between "balance" and "amount" - as I said in the OP, we could use "balance" to signal a difference between static amounts (such as the deposit amount) and dynamic streaming balances.

Second, "tremendous misunderstanding" is an exaggeration. We already have getSender and getRecipient functions - using one of my suggestions would make it easy to group all sender and recipient-related functions together.

I am willing to concede that there might be a little bit of confusion over getRecipientAmount, because the recipient can withdraw. But not for getSenderAmount or getSenderBalance - in the case of the sender, it should be clear what these functions mean. After all, is is us who define the smart contract API, and it's up to us to explain the functions properly in a documentation website. The function names don't exist in a vacuum.

Referring to the recipient's-balance or -amount is in direct conflict with the actual balanceOf that user

Good point, though Sablier is not an ERC-20 contract, so at least because of this it should be understandable that getRecipientBalance refers to something else. "balance" is a common term in smart contracts, actually.

we have two types of amounts there, so separating them by sender/recipient makes sense

Again, good point.

[PaulRBerg]

Locking in favor of #287 and #296.