Is "storage.balance" a globally available storage property?

[PaulRBerg]

I am reading through guide 3.1 from the Sway Book, which is documenting smart contracts.

In one of the code snippets, the following function is introduced:

#[storage(read, write)]
    fn receive_funds() {
        if msg_asset_id() == BASE_ASSET_ID {
            // If we received `BASE_ASSET_ID` then keep track of the balance.
            // Otherwise, we're receiving other native assets and don't care
            // about our balance of tokens.
            storage.balance += msg_amount();
        }
    }

However, I can't see a definition for a balance storage field. Is it that this is a globally available storage property in all Sway contracts, and defining it is not necessary?

[otrho]

storage.balance is referring to a storage variable as per this section. It looks like it might be good to update the earlier example you're referring to to include a storage declaration:

storage {
    balance: u64  = 0
}

OTOH maybe it was left out to try to avoid introducing too many new concepts at once. @mohammadfawaz @Braqzen

[PaulRBerg]

Thanks, @otrho, makes sense now.

It would definitely be worth including the storage declaration in that contract script - this particular storage variable name balance is all the more confusing for someone coming from the EVM, because all addresses in Ethereum actually do have a global property balance, which can be accessed like this: <address>.balance and doesn't have to be defined by the user.

Re introducing too many new concepts - storage is not a new concept in this guide, it is explained as part of the #[storage(read, write)] annotation.

[Braqzen]

Most sections in the Sway Book omit concepts that are not relevant to the content being covered; however, it also demonstrates relevant concepts without mentioning them at times.

I suggest taking a look at the Sway Reference as that guide attempts to demonstrate the relevant concepts in and of themselves and link to further reading, in the guide, if necessary.

Also, re-affirming that the storage block does not, at least at this time, have any globally predefined variables such as balance. Storage contains only the variables that are defined explicitly by the user; therefore, storage.balance exists because the field balance has been defined by the author in the storage block although it may not have been shown in the relevant section and thus the confusion.

[PaulRBerg]

Thanks for the additional color, @Braqzen.

I understand the general principle of avoiding exhaustiveness for brevity purposes, but I still believe that in this case it would be worth it to add an explanatory note about what storage.balance is - otherwise EVM devs will simply be confused.

But at any rate, this is your language and your documentation website - I am just thinking out loud.

re-affirming that the storage block does not, at least at this time, have any globally predefined variables such as balance

This is interesting as a separate point. Doesn't Sway - or the Fuel VM - provide any mechanism for accessing the native asset balance? Do contract developers always have to manually add a bespoke balance storage field to keep track of this?

[Braqzen]

Fuel takes inspiration from Ethereum; however, they are not the same and in my opinion despite potential marketing around the Ethereum network we should avoid placating to any language. I prefer being agnostic rather than favouring one language for any reason.

The documentation can certainly be improved and that is the reason the reference has been written. It was meant to be a replacement rather than a different form.

Voicing your opinion is a good idea and suggestions are welcome. A good way to make a suggestion actionable is to create an issue so that it's on the radar as a discussion may not be as noticeable.

As for the access of an asset balance Sway has assembly which can be used to access the balance, among many other things. That being said, assembly is something that a dev should not need to access and thus we have some standard library functions which allow you to retrieve the asset balance of a contract via a function call.
You may use balance() directly or alternatively there are 3 functions that can be used.

If you would like to keep manual tracking of the balance / creation / destruction of assets then you would need to do that yourself via the storage block and some field. Note that once an asset leaves the contract that has created it you have no way of knowing where it is or what has happened to it since the model type is a UTXO rather than the account model in Ethereum where all the tokens always remain in the contract and some numbers are shifted between one address and another.

[PaulRBerg]

Thank you for the thoughtful reply, @Braqzen, and thanks for linking to the standard library functions available for querying an account's balance.