Additions to the docs

documentation/deploy.md

@@ -84,9 +84,24 @@ Refer to
 [examples/e2e.eg.ts](https://github.com/MinaFoundation/mina-fungible-token/blob/main/examples/e2e.eg.ts)
 to see executable end to end example.
 
-## Upgradeability
+## A Note on Upgradeability
 
-Both the token and admin contract have permissions set so that they cannot be upgraded, except in
-case of a non-backwards compatible hard fork of Mina (see
+By default, the token and admin contract have permissions set so that they cannot be upgraded,
+except in case of a non-backwards compatible hard fork of Mina (see
 [Mina documentation on upgradeability](https://docs.minaprotocol.com/zkapps/writing-a-zkapp/feature-overview/permissions#example-impossible-to-upgrade)).
 This is to ensure that the rules around the token are not changed after the token is deployed.
+
+Depending on the maturity of your project, that might or might not be what you want. Disallowing
+contract updates gives a strong guarantee to token holders that the rules around the token will not
+change. For example, if the admin contract ensures a limited supply of the token, or forbids minting
+new tokens after a certain date, then a change of that contract can undo those guarantees. This
+might be the right thing to do if you have figured out exactly how you want the token to behave, and
+are sure that you will not make any changes in the future.
+
+If you do want to reserve the possibility to make changes in the future, then you should alter the
+`deploy()` functions to set the account permissions for the token and admin contracts to allow
+changes to the verification key. If you do that, you will probably also want to allow future changes
+to the account permissions, to eventually disallow further changes to the verification key.
+
+If you are looking to acquire fungible tokens, you should consider that if the deployer used more
+permissive account permissions for the contracts, they might change the contracts in the future.

documentation/introduction.md

@@ -1,14 +1,22 @@
 # Introduction
 
-Mina natively supports custom tokens
-([MIP-4](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-zkapps.md#token-mechanics)). Each
-account on Mina can correspond to a custom token.
+This document describes how to work with the fungible token standard on Mina. The corresponding code
+can be found on [github](https://github.com/MinaFoundation/mina-fungible-token), or installed as an
+[npm package](https://www.npmjs.com/package/mina-fungible-token).
+
+The fungible token standard uses Mina's native support for custom tokens (see
+[MIP-4](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-zkapps.md#token-mechanics)). An
+account on Mina can be created to hold either Mina, or a custom token.
 
 To create a new token, one creates a smart contract, which becomes the owner for the token, and uses
 that contract to set the rules around how the token can be minted, burned and transferred. The
 contract may also set a token symbol. Uniqueness is not enforced for token names. Instead the public
 key of the contract is used to derive the token's unique identifier.
 
+The token contract defines the behavior of the token -- how tokens can be minted, burned,
+transferred, etc. The fungible token standard consists of a smart contract that is suitable for
+fungible tokens.
+
 ## SHOW ME THE CODE
 
 The