Document Coins usage in smart contract

[Ben-Rey]

There seems to be confusion regarding the use of coins in smart contracts, whether it's for a function call or during deployment.

Some example of questions:

• How are coins allocated for storage during a smart contract call?
• Explain that there isn't a "payable" function.
• Discuss coin allocation for deployment. Is it solely for storage?
• What occurs when no more space is available? Who manages the storage, and who bears the cost?

@damip Please challenge the questions if they appear unclear or illogical.

[damip]

Here are succinct responses that should be added to the docs.

Transferring coins

• pure coin transfers are allowed (provided enough balance):
  • from any account the context has write access to
  • towards any account the context has write access to
  • towards any externally owned account
• moving coins towards a smart contract account without having write access to it requires calling an exported function of that smart contract and setting the "coins" parameter of the call
  • at the beginning of the call, those coins are transferred to the called account
  • if the call fails, the coin transfer is rolled back
  • for now, all exported smart contract functions are considered payable in Massa which means that they can all be called with non-zero "coins"

Storage charges

When calling create_sc, two charges happen:

• the caller of the create_sc is charged with 0.001 coins for the creation of a new ledger entry
• the caller of the create_sc is charged with 0.0001 coins per byte of bytecode stored on the newly created SC

Space is always available because occupying space requires locking coins. The available space is therefore naturally limited by the total supply of coins in circulation, but as long as you have coins you can always store.

Storage is paid by the address at the top of the call stack. When storage bytes are freed, the unlocked coins are given to the address on top of the call stack.

[Ben-Rey]

Very clear thanks !

[qdrn]

It's a good opportunity to explain in which context accounts have write access.

[qdrn]

Not directly related but in the previous documentation there was this document that was created which documented the stack https://github.com/massalabs/massa-docs/blob/main/web3-dev/smart-contracts/address-stack.rst.