SEP-41 Token burn / burn_from functions do not document panic cases

[jsmaxi]

The burn and burn_from functions in TokenClient lack documentation about when they will panic. I believe, these functions will panic and revert the tx if the account has insufficient balance, if authorization is missing, or if the amount is invalid (<=0).

Currently the documentation only describes the basic functionality but does not mention any panic/error conditions.

The same may apply to some other token client functions.

https://github.com/stellar/rs-soroban-sdk/blob/07384526b8b052905a27c145a9c972922739106f/soroban-sdk/src/token.rs

https://docs.rs/soroban-sdk/latest/soroban_sdk/token/struct.TokenClient.html

[leighmcculloch]

The SEP-41 Token function errors are not documented because they can be very much implementation specific. In the classic protocol error cases were specified and over time it made it difficult to maintain so we corrected, maybe over corrected, the other way.

It might be reasonable to document some possible cases but with a disclaimer that it is ultimately implementation specific and the SEP doesn't specify or limit the cases.

[jsmaxi]

Thanks for the clarification. I actually thought it may be implementation specific, but it would still be nice to know that they might panic, as you described in issue #1612.

So, for example, when calling TokenClient's burn function in a Soroban contract, rust analyzer would inform that it may panic depending on the token implementation. Callers should be aware that error behavior isn't standardized across tokens, so it's best to check conditions like sufficient balance beforehand.

[leighmcculloch]

What we're really discussing here is whether SEP-41 is underspecified, because the token clients in this SDK just implement a client to interface with SEP-41 implementations and so just documents what SEP-41 states.

I'm transferring this to the discussions forum where we can continue to discuss if SEP-41 is underspecified or not.

And opened an issue here to discuss improving the documentation of all clients with a generic note that they can panic:

• All contract clients should include documentation stating that they can panic rs-soroban-sdk#1612