Token Interface spendable_balance

[crude thicket]

Hi all,

The token interfaces spendable_balance function is a recurring conversation.

I keep hearing from people over time that it's surprising the function is in the token interface because it seems like something bespoke to Stellar assets.

A few times people have proposed the function be removed from the interface so that other tokens only have to implement balance.

I'd like us to have one final conversation on this, to see if we could get some consensus in removing it from the token interface.

The function would still live in the Stellar Asset Contract. There would be no changes to the host or environment, we would just remove the function from the token interface so that custom tokens do not have to implement it.

This would require one change to the Rust SDK, and any other contract SDK, but zero other changes to tooling.

Thoughts everyone?

Conversation that prompted this final push: https://github.com/stellar/stellar-protocol/pull/1402#discussion_r1355842565
cc @finite owl @somber ledge @cyan hemlock @signal flame @dapper forge

[signal flame]

the question is who would use spenadble_balance then. it seems like balance() is mostly useful for off-chain, while spendable balance is useful on-chain. but using spendable locks your contracts into SAC, which is a bit annoying

(or everyone would use balance and shoot themselves into leg with SAC at some point)

[cyan hemlock]

I don't think we can remove the spendable_balance function from the interface without modifying the balance function of the SAC to reflect only the spendable balance, and expose the unspendable balance through some other function (like @finite owl proposed total_balance here: https://github.com/stellar/rs-soroban-sdk/issues/1080#issuecomment-1705564703)

What I think will happen is that applications will expose functions like "swap all tokens" which will call the balance() function and then fail because not all of it is spendable

[crude thicket]

I think even with total balance we're causing SAC behaviors to bleed into balance. We're forcing folks to think about all tokens having a total balance and a non-total balance.

[crude thicket]

This type of application behavior is reasonable, but wouldn't the onchain behavior still be a fixed amount? The off-chain application would lookup the balance and fix it.

[cyan hemlock]

but how would the off-chain application know it? you'll need to introduce custom SAC behavior somewhere

[crude thicket]

Instead of total_balance, I think it would be reasonable for the SAC:

balance = non-reserved balance
reserved_balance = a separate balance amount that is reserved and not usable

Instead of one balance being a subcomponent of another, we have two separate balances that are transferred between.

[cyan hemlock]

ok, that requires a sac change, no?

[finite owl]

We could just include a SAC specific total_balance function, as it is outside the scope of this interface IMO.

Or the reserved_balance idea from Leigh.

[crude thicket]

It does you're right. I'm just leaning into the suggestd view above that balance should be spendable.

[signal flame]

the concern with having balance to be spendable was that it would cause issues for wallets.

FWIW I also would support spendable-only balance and I advocated for that before as well

[finite owl]

Will wallets ever read balances from a SAC tho? (I am not a wallet dev) but I would lean into just using the account object from Horizon for these.

[signal flame]

also there are no liabilities for contracts and the account balances can be retrieved from the trustlines

[cyan hemlock]

yeah I raised the concern, and I indeed think some applications will present wrong SAC balances

[signal flame]

yeah, exactly that - even if wallets support custom accounts in the future, balance would be correct for them (because spendable == total)

[cyan hemlock]

I'm not religious about any of this, I'm just concerned about introducing changes now.

If there's strong support for this change, and the devs can do it without introducing timeline delays due to the SAC changes then ok

[crude thicket]

The thing I like about reserved_balance is it is less likely someone will use it by accident.

Folks can develop against total_balance and balance and 50% of the time probably see no errors.

The same problem exists today with balance and spendable_balance.

As a developer reading the spec, I'm a coin toss on which to use.

The impact of which to use may also not be apparent to a developer.

If I write a contract and I don't really care about spendable, I might cause my contract to expose a tokens balance. Then someoen using my contract will see the balance amoutn returned and try to do something with it like spend it.

My contract doesn't actually care about balance vs spendable, but has unfortunately broken other contracts who use my contract while interacting with someones balance.

[signal flame]

yeah, I think the reserved_balance seems much better from that standpoint

[serene lynx]

What is the advantage to removing it? And im not sure i clearly understood the difference between balance and spendable balance. Im assuming its due to like native xlm might have part of your balance locked for reserves and for issued assets it would be relative for when you have an open offer.

[serene lynx]

This makes sense

I think reserved would be easier for someone unfamiliar to understand maybe. You can then still calculate spendable quite simply

[signal flame]

you won't need to - balance will be spendable (I feel like that's the general common sense to assume that from a contract dev standpoint)

[serene lynx]

Yes that is likely best. I cant think of a reason why the reserve balance is relevant very often unless you need to check some address holds some balance spendable or otherwise for some reason which is probably rare.

[serene lynx]

https://tenor.com/view/this-is-the-way-this-is-the-way-mandalorian-mandalorian-i-have-spoken-baby-yoda-gif-24159898

[round flame]

Does anything prevent balance function to return something like a tuple (balance, spendable) or even more complex object to reflect reserved or in liability ?

[signal flame]

that would complicate interface even further

[muted jetty]

Does anyone knows how to get the contract address of assets

How can I use assets on a smart contract when all the assets has is a code and issuer address

[signal flame]

in soroban SDK you can use env.deployer().with_stellar_asset()

it expects the Asset XDR though, but Asset consists of code and issuer account id

[muted jetty]

Yeah. So how can one use assets on the contract if what you need is the code and issuer account.

All the docs usually talks about contract address for token.

[signal flame]

it's because the default way to interact with contracts is to use Address. you're probably better off generating the Address off-chain and use Address in your contracts. it also will make your contracts more testable and interoperable with non-SAC tokens

off-chain generation is not hard, but it requires some XDR building, so you'll need to use whatever client SDK you have for that

[gaunt tiger]

I'm also trying to do this, using the Soroban CLI. In case it's relevant https://discord.com/channels/897514728459468821/1162214588469739630

sorry to crash the spendable_balance post 😅 . Fwiw I like the suggestion of a separate variable for reserve balance and regular "balance" can be shorthand for spendable balance.

I'm still wrapping my head around the differences between stellar assets and ERC20 tokens. I think that'll be a speed bump for devs like me onboarding from EVM. But if I can read balance in the same way as I do in Ethereum that's a win.

[muted jetty]

How can I generate the address of chain

[crude thicket]

im not sure i clearly understood the difference between balance and spendable balance
I think this is part of the problem between them. The difference is subtle.

[serene lynx]

?

[crude thicket]

What I mean is that because it is difficult to clearly understand the difference between them, it's easy to pick the wrong one when deciding which to call on a token.

[serene lynx]

Ah yes i agree. I thought we decided to only have balance and reservedbalance?

[crude thicket]

Removing spendable_balance: https://github.com/stellar/stellar-protocol/pull/1408

If you approve of this change, please use the approve feature of the PR to signal so.

[wraith rain]

I think that removing the spendable_balance from the token interface makes sense. It's a unique limitation for SAC and should apply only for SACs. SACs, in my opinion, should be returning their spendable_balance in the balance methods. In addition, SACs should also have a reserved_balance method. My reasoning is that we want all users to be able to transact the balance without any errors. the fact that a fractional amount would be "locked" is limited for SACs - and SAC-specific applicaitions could provide special handling for these.

I'm not sure if my view here aligns more with @cyan hemlock 's or @crude thicket 's.

[serene lynx]

Ill review it now

Gimme 15 minutes have to find my phone for 2fa code for github sorry

[crude thicket]

Yup, sounds 100% aligned with my comments above.

[serene lynx]

I also dont love making changes at this stage but this one makes sense and it should be easy to implement.

We should just make sure to make an effort to alert contract devs of what is happening since it may result in some small implementation changes

[crude thicket]

@signal flame Does the existing SAC spendable_balance also exclude liabilities? Or only reserves?

For example, if someone has created an offer.

[signal flame]

liabilities are excluded as well

it is truly the balance that can be spent (you can't spend selling liabilities)

[serene lynx]

Maybe we should leave spendable balance for a set period of time even if it returns the same as balance now so existing contract implementations dont break

[crude thicket]

I guess the term reserved_balance is not entirely accurate then.

Unless the SAC also exposes a liabilities_balance.

[serene lynx]

I think reserved balance is accurate because it would be the balance of all reserves and liabilities?

[crude thicket]

Making a SACs total balance being balance + liabilities_balance + reserved_balance.

[serene lynx]

I see no reason to differentiate the two

[signal flame]

yeah

[crude thicket]

The term "reserve" historically specifically refers to the balance reserved for subentries. I don't think we should redefine it, or at least redefining it will be confusing for some.

[signal flame]

I'm fine with reserved as general term for representing the balance that belongs to the account, but is not spendable. could be called in other way to not coincide with historic meaning

but also I don't think the overlap matters much TBH, these are pretty distinct contexts

[serene lynx]

Yeah maybe we should call it something other than reserved but i dont see a need to have both

[signal flame]

we could just call it non_spendable_balance 🙂

[serene lynx]

Yep maybe you can add that comment to the pr since i already approved it with reserve

[crude thicket]

unspendable_balance. According to the dictionary, unspendable is a word.

[serene lynx]

There ya go

[crude thicket]

There's something nice about not creating new concepts though. If we lean purely on existing concepts:
balance
buying_liabilities_balance
selling_liabilities_balance
reserved_balance

[serene lynx]

We should consider how this can affect existing contracts...

[serene lynx]

Will adding the extra function for liabilities increase the size of other contracts some how and/or cause any confusion...

I dont see a reason liabilities and reserves need diferentiated on soroban when we dont yet expose any dex or amm features

Just knowing its not transferrable is enough imo

[crude thicket]

Admittedly when I started this thread, I was only thinking about reserved balance, and not liabilities, and so I was thinking that the distinction on spendable vs unspendable existed only for the native asset (lumens), and not any other asset.

It's more feasible/reasonable for a non-native asset that contracts may want to read the total amount being held independent of whether it is spendable.

cc @cyan hemlock

[serene lynx]

Yes they may want to see the entire balance but they can get it from balance plus unspendable_balance adding buy/sell liabilities plus reserve makes an extra step?

What would the benefit be to knowing the balance tied up in offers or claimabale balances

Knowing it seperate from the total unspendable balance i mean

Bc claimable balances are also a liability

I see no issue changing reserved_balance to unspendable_balance or possibly having a total balance endpoint. But i dont see an advantage to adding these extra methods yet

[signal flame]

the 'unspendable' (or rather full) balance is only useful for off-chain users, e.g. wallets. but I'm not sure this has to belong to the token interface at all (chances are the wallet already supports stellar assets and it won't want to duplicate the asset balance as a separate token balance as well)

[crude thicket]

Reserve balance "disappearing" on chain isn't such a big deal as it only impacts the native asset.

Liabilities balance "disappearing" on chain could be surprising. If holding a certain amount of an asset provides some benefit, and then creating an offer for it causes your benefit to disappear.

[serene lynx]

unspendable has a use... but does buy liability sell liability``claimable liabilityand reserve liability
I feel like adding 4 methods is overkill at this stage. Later if we add l0 dex and amm host functions its different

[crude thicket]

@cyan hemlock Maybe the correct action in this case is to fail if all tokens can't be swapped. If a user clicks "Swap All Tokens" and some of the tokens are locked up in an offer, doesn't it make sense to fail?

[signal flame]

If holding a certain amount of an asset provides some benefit, and then creating an offer for it causes your benefit to disappear.
it's not possible to tie any 'benefit' with the balance, is it? outside of a single transaction boundary, that is (even then, it's quite footgun-y)

[crude thicket]

I think that's making some assumptions, contracts could assign benefit based on balance, such as benefit to vote at a certain level.

[signal flame]

in general, contracts can't make any assumptions about any external balance. l

[signal flame]

that's fine. but this balance would only matter during the particular calls

[serene lynx]

Cant assume they would require the user to tie up the balance to vote in which case theyd probably wanna know if the user has any of a token rather than can spend any

But no matter what i think balance should return spendable balance. Whether we have for the rest a total balance, a unspendable balance or all 4 liability granularly accessible seems not as relevant to me.

Gotta go run an errand thanks guys

[crude thicket]

What I'm getting at is the SAC balance should return the total balance. It's likely a footgun to allow contracts to think they are transfering all value out of an account, when they're infact only transferring the non-liabilities portion.

[serene lynx]

Hmm i see your concern with that

[signal flame]

I think this optimizes for an unrealistic use case

transferring the whole balance from an external account is not something you should/can reliably do in in the contracts

[crude thicket]

What does external account mean on Soroban?

[signal flame]

by 'external' I mean 'not owned by the contract'

[crude thicket]

That's the use case @cyan hemlock shared at the top which is the only reason we're making balance return the spendable balance.

[serene lynx]

Its reasonable to assume when u call balance youre expecting a number that can be used.

[signal flame]

again, this won't work well. transfer will resolve to an exact value for the signing purpose and at this point why would you bother getting it programmatically from the contract?

[crude thicket]

And to your point a contract account cannot have liabilities?

Or a reserved balance.

[signal flame]

why not?

[crude thicket]

Contract accounts can't have subentries.

And can't create offers on classic Stellar.

[signal flame]

it can have arbitrary restrictions based on the implementation

[crude thicket]

I'm talking about the SAC.

[signal flame]

that's not on the token side though

right, but it doesn't mean that a custom account that holds SAC doesn't have any restrictions w.r.t. transfers

basically my point is that address.balance() >= my_transfer_value does not guarantee transfer(address, to, my_transfer_value) to succeed

so maybe it's not worth spending time optimizing for that

[crude thicket]

The only reason the spendable_balance fn exists on tokens is to support the SAC having liabilities and reserves.

[signal flame]

and maybe it doesn't really matter which balance we return...

so might as well return the full balance...

[crude thicket]

We should just return the total balance from balance.

I think we're coming to the same conclusion from different reasoning.

[signal flame]

yeah

I guess for cases where you care for immediate token balance for the purpose of something like voting, liabilities don't matter. it doesn't matter whether you're going to sell token now or whether you just transfer it in ledger N+1 - in any case the only thing you can ever now is how much token the user holds in ledger N and nothing more than that

[crude thicket]

Right. And anything beyond that is making assumptions about how a token or account might operate.

So basically:

balance should return the total balance because:

• If you're trying to transfer the full balance of a token for an account and the account has liabilities, it makes sense to fail because you can't truthfully transfer the full balance.
• For G accounts the user has to be actively involved in signing a tx containing the exact amount anyway, so a contract being able to query the amount isn't really helpful.
• There's nothing that would guarantee for a customt token that an amount is always transferrable.

[serene lynx]

Good point and didnt think of it.

This reasoning all makes sense to me.

Thanks

[crude thicket]

So I think the new change: is still drop spendable balance, keep balance as is (total).

And we should still remove spendable balance from SAC to make sure no one depends on it incorrectly. And if this decision is wrong we can add spendable balance, or some other fn like it, back to the sac later.

[serene lynx]

I should delete my approval or add comments i guess. But assuming you will update the pr?

[crude thicket]

I updated the PR description in:
https://github.com/stellar/stellar-protocol/pull/1408
and opened an env issue:
https://github.com/stellar/rs-soroban-env/issues/1118

[serene lynx]

WIll rereview this afternoon

[past burrow]

if we think about how those things are used, maybe this is not exactly right? I think Solana for example has different methods for getting the balance to display to users (total balance stringified) vs balance to use in contract logic. For contract logic, I am not sure how balance is used, but it probably has to be "liquid" (so "spendable balance")? The UI one is interesting as I am not sure what the solution would be in general: aggregating liabilities is probably not doable at the token contract level as liabilities may have different levels of risk? How is this done in other ecosystems?

[crude thicket]

I think the concept of how liquid a token balance is token specific, and custom tokens could define any logic they want on that. Whatever concepts we add around what is spendable or not will be making some assumptions.

[crude thicket]

The "UI view" of solana tokens is afaik just dealing with fixed point math. See the amount_to_ui functions here https://docs.rs/spl-token/latest/spl_token/. Or are you referring to something else?

[past burrow]

I was pointing to UI methods because I think we’re trying to solve different problems. It seems weird to me that we’d assume that people would liquidate their positions when dealing with the SAC but not expect the same from other contracts.

[crude thicket]

we’d assume that people would liquidate their positions when dealing with the SAC but not expect the same from other contracts
I didn't think we were assuming this. Maybe I'm misunderstanding, but I think we were saying SACs have some limits on their balance availability, due to liabilities on all SACs and additional reserves on native SAC. And any custom token could have any limit on balance availability they defined. Trying to representing available balances vs complete balances is difficult and flawed and not super beneficial.

[cyan hemlock]

Ok, final thoughts and temperature check.

I actually still hold the (minority) opinion that having a separation between balance() and spendable_balance() allows tokens, including (but limited to) the SAC, to convey nuanced important information in a standardized way. I recognize it adds some complexity for consumers but I don't think the cost outweighs the benefit. However, I'm willing to admit defeat here.

If people feel strongly about removing it from the interface then we should probably remove it from the SAC too. This harms the "completeness" of the SAC and forces the consumer to either revert to other systems (like horiozn) or special-case handling these failures to get the full picture. But the danger of people relying on a function that might not exist in custom tokens is probably worse.

Please vote for your desired solution (this is a temperature check, not a democratic process):

1️⃣ Leave spendable_balance() in the token interface and in the SAC
2️⃣ Remove spendable_balance() from the token interface and leave it in the SAC
3️⃣ Remove spendable_balance() from the token interface and from the SAC

[crude thicket]

If we remove it from the SAC, we can add it back. So the risk of wrong decision is small.

3️⃣ is basically deferring the decision about what to do here to a point in time where we might have more information.

[cyan hemlock]

argh, using number emojis for votes is .. confusing

[serene lynx]

🔢

[crude thicket]

How is this done in other ecosystems?

On Ethereum tokens are moved into other addresses. On Ethereum there are frozen or locked balances. There's https://eips.ethereum.org/EIPS/eip-5753 which allows locking of an entire balance. It's not really the same, but in any case the balance isn't altered, and transfer will fail if attempted.

I'm not finding a similar concept of partial locking of a balance on Solana.

Are partially locking balances unique to Stellar? cc @cyan hemlock

[serene lynx]

are balances locked when there is an allowance to another address? i don't think so

[crude thicket]

Balances are not locked.

[serene lynx]

The only time i can think of a balance being locked on ethereum is like a staking contract, but usually you deposit your tokens to that staking contract and get something else in return. OR on certain custom token contracts where there is some type of authorization required and all balances are locked without the contract having some other auth to give the user permissions. Since eth isn't ever wrapped and eth is the only "lower level" token on ethereum i don't think the concept transfers

[past burrow]

I would imagine that aggregation to find "how much do I really have" across contracts is done in a custom way (like: wallet is the one responsible for querying various endpoints to find the total value of assets controlled by a specific key) --> if we're going to leave one thing in the generic contract, shouldn't it be "usable_balance"? Liabilities from offers, unclaimed claimable balances in classic can be thought of as balances stored by some other contracts?

[serene lynx]

One thing that's not entirely clear when i looked at the PR is the balance a sac will return from balance with spendable_balance removed. will it still be the full balance? And sorry for being easily confused but i thought there was talk of having a reseved balance or was that just something i made up in my head and assumed

I know leigh said he updated the pr so just making sure i'mclear. The proposed change removes spendable_balance from both sac and token interface and leaves the rest the same? I think we would want people to be able to make the same assumptions about balance on both the sac and custom contracts.

It seems to me that we would still want a way to find out if there is part of the balance unusable even if we know a transaction will fail if that balance IS unusable and we try to say transfer it, wouldn't it be better to tell the user WHY it failed?

[signal flame]

if we're going to leave one thing in the generic contract, shouldn't it be "usable_balance"
the issue of usable_balance is not truly usable, unless its your own contract's balance. I think 'this is the value stored in your trustline/account/SAC data entry' is the simplest semantics out there.
I'm generally not quite sold on the use cases for external balance() beyond the voting-like cases. for actual spending transfer should be used and no assumptions can be made

wouldn't it be better to tell the user WHY it failed?
that should be provided by the transfer() implementation. I would consider doing something like if token.balance(addr) >= amount { token.transfer(addr, to, amount} an antipattern

[serene lynx]

I have mixed feelings on this still. I guess since I haven't built tons of implementations yet and don't know the potential use cases it's like easier to say keep our options open.

[signal flame]

do try_transfer if you want to handle failures gracefully

[serene lynx]

but it'll still only say that it succeed or fail, not necessarily say, there's 500 tokens reserved and your balance is 700, so you can't transfer 600

but it's like when is that really needed, never

[signal flame]

it actually should tell you what happened via diagnostic events

moreover, you'll also get back a ContractError so you'll even be able to customize your behavior

[serene lynx]

Where is the code for the sac i know it's a host function but

[crude thicket]

keep our options open
Option 3️⃣ keeps our options open the most. It defers any decision.

[signal flame]

e.g. for balance you'll get back ContractError::BalanceError

[signal flame]

it's actually a contract (or rather 'behaves like a contract'). so you can do try_call on it and handle the errors

[serene lynx]

right behaves like the contract but is it inside of soroban-env now?

sorry wanted to look at the actual implementation not just the interface

been a few months

[serene lynx]

Lets do this then I reacted to 3.

[signal flame]

yes, it's implemented in rs-soroban-env https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-host/src/native_contract/token/contract.rs

[serene lynx]

technically it's still a change, but i understand it's easy enough to add it back.

[serene lynx]

yep that's what i was looking for thank you

and the pr has no change to that just yet but would the logic for balance as it currently is there be changed? Just removing https://github.com/stellar/rs-soroban-env/blob/6c675f1869fc8e320c6e0598382f5ed663c6c7a1/soroban-env-host/src/native_contract/token/balance.rs#L58

[signal flame]

we'll also need to do a bit of cleanup

[past burrow]

I am fine with keeping options open (so delete one of the 2 to reduce confusion), but I still don't understand why "total balance" is the better choice: smart contracts are going to return the equivalent of "spendable balance", but the SAC will return some bigger number that is not actionable from the Soroban side. Which is why I was asking if we should instead delete the balance method. We can potentially re-add it later (with a better name), either just at the SAC level or in a SEP that deals with liabilities if that's the concept that needs to be standardized on.

[serene lynx]

but the SAC will return some bigger number that is not actionable from the Soroban side.

i'd say that was part of my concern which is why i think i'm having mixed feelings about it.

to be clear though i'm okay with the proposed solution in #3 and if it turns out we need to change it later we can.

[crude thicket]

Smart contacts will return a balance but it might be frozen, it's not guaranteed to be spendable.

Where I think spendable falls apart is if the holding of a token provided some benefit. Such as allowing a user to be authorized to perform some action. Creating an offer classic side for the token would result in the benefit not being valid if balance was the spendable amount.

Which is more important:

• contracts being able to withdraw all value from an account without erroring on an account with liabilities, which is a sane failure, because if a contract needs to withdraw all funds it can't while offers exists no matter what way we implement balance.
• or, contracts being unable to provide benefits for holding token that are in an offer, which seems surprising.

If decide to keep only spendable balance, let's make that an implementation detail of the SAC implementation of the token interface, and not part of the interface itself. So that we don't bring that concept to all custom tokens.

I.e. The token interface balance is just balance. The SAC interface into Stellar trust lines only makes spendable amounts visible.

[signal flame]

The SAC interface into Stellar trust lines only makes spendable amounts visible.
I'm like 90% sure someone will use balance() in the wallet and get users confused

[cyan hemlock]

More like 100%.

[cyan hemlock]

I think that balance() should give visibility into the full holdings

Thanks for all the view points. There seems to be almost consensus about removing spendable_balance() from the interface. Removing it from the SAC itself makes sense as to not confuse people and as @crude thicket points out it can be easily re-added later

[crude thicket]

+1 on balance being total. I'm more in favor of removing spendable than removing total because I think out of the failure cases both create, it is logical to be unable to withdraw a full amount and it is surprising a balance hides some amounts.

I think it is logical to be unable to withdraw a full balance because if the goal is to truly empty an account and there are liabilities you can't empty the account. And it's not necessarily okay to hide that from a contract and let them think they're withdrawing all when they're withdrawing only some.

[serene lynx]

Im able to finally agree with it being the total after a couple days of thinking about it.

So basically my approval on gh is still good.

[past burrow]

OK so from a spec point of view balance should only be used from wallets thenas a UI helper and is advisory/implementation defined (ie: some implementations like SAC will include liabilities, but others may not). we should have some wording around that so that people don't rely on what gets returned from contracts

as in: nobody should call balance from contracts and make decisions based on that

[signal flame]

you can call balance() - as @crude thicket pointed above you might want to know the 'stake' that account holds. I think this is the only more or less valid case for balance and I think it also should care about total balance

also balance() is safe to use for the current contract address - as you own the balance, you can easily programmatically drain it

[past burrow]

for the stake thing yes as long as it's consistent (as in: not double counting assets between users). second point I do not understand

[crude thicket]

I don't think contracts need to avoid calling balance if they need the balance. The one case is if they want to change a transfer amount based on balance like "withdraw all funds", but I'm suspicious of the validity of that type of transfer, since trying to transfer out the entire balance of a Stellar account is flawed in general because of liabilities.

Second point is from @signal flame I think is about contracts holding a balance has no classic stellar oddities.

[past burrow]

yeah that's my point that you can't really use the amount without knowing about implementation details. so you can't use it from the wallet to adjust payments

you can only do that with something stronger like spendable_balance

[crude thicket]

But using balance is always flawed for Stellar accounts, no matter how we structure it? If the goal is to withdraw all, a spendable balance doesn't let you wtihdraw all.

And "withdraw all" withdrawing all except liabilities locked up in offers isn't intuitive, to me atleast. It seems like surprising behavior, so possibly footgunny.

Possibly dangerous. If contract is supposed ot withdraw all of a voting token, but accidentally doesn't because user had an offer that created a liability.

[past burrow]

the flaw is in that if this was a soroban token, people would actually not have that balance reported in their balance

(instead you have some other token from a pool for example)

if we want to have some way to compute some "send max" in a way that does require custom code in clients for the SAC, either you need spendable_balance or we need balance to be that

(and if frozen that amount is 0 which is kinda confusing)

typo: does not above

[signal flame]

'withdraw all' is only possible to do for the contract's balance (modulo possible token implementation restrictions). but it doesn't make any sense for external accounts; it's not 'withdraw all', it's 'withdraw the snapshot of balance that I fetched during preflight'

so any semantics is equally broken

[crude thicket]

@signal flame unless allowances are in use.

An allowance above balance would allow a contract to withdraw from an account its max, limited by liabilities.

[signal flame]

true. one more reason to not use unlimited allowances 🙂

[crude thicket]

But yeah, we're hoping Auth will be used instead of allowances because they're safer, at which point wallet needs to sign the transfer amount, which means wallet is involved.

Thanks to preflight though wallet just needs to "approve" the amount, not come up with the amount.

Contract dev writes logic that requires withdraw all. Wallet is managing a G account, sees approval to transfer 500. Wallet knows 20 liabilities, wallet/user can choose to release offers first to actually do withdraw all.

vs the flow with spendable:

[signal flame]

also if we consider unlimited allowances to be a generally bad practice, then even with regular allowances we run into the same issue of allowing up to a certain snapshot of the balance

[crude thicket]

Contract dev writes logic that requires withdraw all, using spendable balance. Wallet is managing a G account, sees approval to transfer 480. After withdraw all account still holds 20. Surprise and shock for everyone.

@signal flame it might be reasonable though for a contract dev to write logic that says withdraw up to max(balance, allowance).

I guess there's no way with an allowance to write an infallible transfer with a SAC.

But this is maybe good precedent to set, because a transfer should never be assumed to be infallible?

Unless the balance is held by a smart contract.

Coming back to your point that contracts shouldn't rely on balances of external accounts.

[signal flame]

even then, you might have some weird token implementations with additional restrictions. any contract function is fallible - I think it's fine. e.g. if you develop any protocol built on allowances (e.g. subscription), you still need to account for the fact that user might just move their balance elsewhere.

[serene lynx]

I wouldn't call it a flaw, it's just... that it is something we need to make clear to developers especially those coming from EVM world because the concept of our tokens with trustlines and the SAC will be completely new to them.

[crude thicket]

I think we've revisited the same topics several times at this point.