Merge pull request #400 from anoma/tiago/update-masp-docs

Update masp docs

packages/docs/pages/users/shielded-accounts.mdx

@@ -3,19 +3,19 @@
 Namada affords users data-protection through its multi-asset shielded pool (MASP), which supports shielded transfers with any native or non-native asset.
 The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that 
 extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary 
-assets. All assets in the pool share the same anonymity set -- meaning that the more transactions are issued to MASP, the stronger the 
-data protection guarantees for all users.  
-
-The MASP allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note". 
-From the users perspective, the construction of these zero knowledge proofs occur behind the scenes.  
+assets. Assets of the same kind in the shielded pool share the same anonymity set -- meaning that the more transactions are issued to MASP, the stronger the
+data protection guarantees for all users. For instance, if a single account has [shielded](./shielded-accounts/shielding.mdx) BTC, then subsequently withdrew
+these funds from the MASP (into the same account), we can trace the BTC back to their origin (even if in the MASP they could have been transacted between
+multiple distinct accounts privately). Now, if multiple accounts shield BTC, and at a later point in time BTC is [unshielded](./shielded-accounts/unshielding.mdx),
+the BTC could belong to any of the accounts that initially shielded the assets.
 
 Users of the MASP are [rewarded](./shielded-accounts/shielded-rewards.mdx) for their contributions to the shielded set in the form of native protocol tokens (NAM).
 
 ### Inspiration
 
 The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. 
 In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner. 
-This circuit is called the Convert Circuit (CC for short).  
+This circuit is called the Convert Circuit (CC for short).
 
 If you are familiar with Zcash, the set of interactions you can execute with Namada's MASP are similar:
 - [Shielding transfers](./shielded-accounts/shielding.mdx): transparent to shielded address

packages/docs/pages/users/shielded-accounts/glossary.mdx

@@ -2,11 +2,11 @@
 
 - __Transparent address__:  
 Has a `tnam` prefix. When transferring from one transparent address to another, transaction details
-such as the sender, reciever and amount are publicy visible.
+such as the sender, receiver and amount are publicly visible.
 
 - __Shielded address (aka: Payment address)__:  
-Has a `znam` prefix. This is the public-facing address which can be shared with others in order to recieve funds. When transferring from one
-shielded address to another, transaction details such as the sender, reciever and amount are hidden from anyone who does not have an associated
+Has a `znam` prefix. This is the public-facing address which can be shared with others in order to receive funds. When transferring from one
+shielded address to another, transaction details such as the sender, receiver and amount are hidden from anyone who does not have an associated
 spending or viewing key.
 
 - __Spending key__:  

packages/docs/pages/users/shielded-accounts/masp-keys.mdx

@@ -47,7 +47,8 @@ viewing key derived from the spending key inherits its birthday.
 
 Birthdays can also be provided when adding or deriving keys. By re-adding an existing key with a new birthday, you can
 update a key's birthday in the wallet. Keys passed to shielded-sync directly (as opposed to being stored in the wallet),
-can also be passed in with birthdays. This is done simply by by appending `<<{BIRTHDAY}` to the end of the key.
+can also be passed in with birthdays. This is done simply by appending `<<$BLOCK` to the end of the key, where `$BLOCK`
+would be the block height of the key's birthday (for instance, `zvknam...<<99`).
 
 #### Displaying your spending key and viewing key
 You can display your viewing key with:
@@ -86,15 +87,15 @@ namadaw derive --alias $SPENDING_KEY_ALIAS --shielded
 
 ### Adding an existing key or payment address to your wallet
 
-If you know the raw value of a spending key, viewing key or payment address, you can add it to your wallet under an alias so you can more conveniently refer to it later.
+If you know the bech32 encoding of a spending key (`zsknam...`), viewing key (`zvknam...`) or payment address (`znam...`), you can add it to your wallet under an alias so you can more conveniently refer to it later.
 
 ```bash copy
-namadaw add --alias $ALIAS --value $HEX_VALUE
+namadaw add --alias $ALIAS --value $BECH32_ENCODING
 ```
-where `$HEX_VALUE` is the hex value of a spending key, viewing key or payment address.
+where `$BECH32_ENCODING` is one of: spending key, viewing key or payment address.
 
 ### Removing a key/address
 You can remove all keys/addresses associated with an alias from your wallet with:
 ```bash copy
 namadaw remove --alias $ALIAS --do-it
-```
+```