Merge pull request #414 from anoma/ian/namadillo-guide

Add content for Namadillo MASP and Transfer sections

packages/docs/pages/users/namadillo/ibc.mdx

@@ -1,4 +1,4 @@
-import { Callout } from 'nextra-theme-docs'
+import { Callout, Steps } from 'nextra-theme-docs'
 
 # IBC Transfers with Namadillo
 
@@ -7,4 +7,101 @@ Namada mainnet will launch with most functionality aside from staking and govern
 few weeks. Therefore, some sections of Namadillo will not be accessible immediately after launch until its respective functionality has been activated on mainnet.  
 
 Until then, you can experiment with all aspects of Namadillo on [testnet](../networks/testnets.mdx).
-</Callout>
+</Callout>
+
+You can connect Namadillo to your [Keplr wallet](https://www.keplr.app/) to transfer assets between Namada and IBC compatible chains, such as 
+*Osmosis* and the *Cosmos Hub*. Namadillo supports both transparent and shielded IBC transfers.
+
+- **Transparent IBC transfers:** Transfers between a transparent (`tnam...`) address and another chain. After receiving 
+assets to your transparent address, they will be added to your transparent balance. You can (optionally) shield them at a later time. But as always, keep in 
+mind that a third party can view all balances and transactions of any transparent address at any point in the chain's history. You can use your 
+transparent address to both send and receive assets over IBC.
+- **Shielded IBC transfers:** Transfers between a shielded (`znam...`) address and another chain. 
+These transfers move immediately to/from your shielded balance without needing to pass through your transparent address first. This 
+[reduces](../../introduction/privacy.mdx) the chances of leaking information about your on-chain activity.  
+
+When using Namadillo, you can only use your shielded address to receive assets. (To send them over 
+IBC, you must first unshield them.)
+
+## Connecting To Keplr
+To send IBC assets to Namada, you will need an account on the source chain (e.g. *Osmosis*, *Cosmos Hub*, etc.) containing the assets you wish to send.  
+
+[Keplr wallet](https://www.keplr.app/) is the most widely used wallet app for Cosmos SDK chains. Namadillo has Keplr integration to allow IBC transfers 
+to and from your existing Keplr accounts.  
+
+This rest of this section assumes you have already created and funded an account on the source chain using Keplr. For help getting started with Keplr, 
+please refer to https://help.keplr.app/start.  
+
+Once you've installed Keplr and created or imported an account on the source chain, follow these steps to connect Keplr with Namadillo:
+
+1. Click *IBC Transfer* in the left sidebar of Namadillo **(1)** to open the IBC panel.
+2. Click *Connect Wallet* **(2)**.
+3. Click *Approve* in Keplr when the *Requesting Connection* **(3)** popup appears
+
+![Connect Keplr](../../../public/images/namadillo/keplr.png)
+*Connecting your Keplr wallet to Namadillo*
+
+## Sending IBC Transfers 'To Namada' (from another chain)
+You can bring assets from another chain to your Namada shielded or transparent balance; think of this as 'depositing' assets from other chains into 
+Namada.  
+
+Begin by selecting '*To Namada*' **(1)** in the *IBC Transfer* section and follow these steps:  
+
+![Ibc in details](../../../public/images/namadillo/ibc-in1.png)
+*Making an IBC transfer into Namada (i.e. Depositing assets)*
+
+<Steps>
+### Enter the transfer details
+- **(2)**: Click to select the *network you wish to bring assets from* (e.g. Osmosis, Cosmos Hub, etc.). Once you've selected a network, your address 
+on the sending chain will be read from Keplr and displayed here.
+- **(3)**: Click to select the asset you wish to transfer.
+- **(4)**: Enter the amount to transfer.
+- **(5)**: Click to specify whether to send the asset to your shielded or transparent address.
+- **(6)**: Your receiving address will be automatically filled from the Keychain extension. If you selected *Shielded* directly above, this will show 
+your shielded address; if you selected *Transparent* it will show your transparent address. The address shown will match the currently selected account 
+in the Keychain extension.
+- **(7)**: The transaction fee for this transfer -- note that fees are paid in the asset being transferred.
+- **(8)**: When you've chosen a source network, asset, amount, and whether to send to your shielded or transparent address, click *Submit* to begin the transfer.
+
+### Click 'Submit' and approve your transaction
+After entering the required transfer info, click *Submit*, at which point you'll be prompted to approve the transaction.  
+
+Note that when IBC transferring assets to Namada, you'll be asked to confirm the transaction in Keplr (not Namada Keychain).  
+
+![IBC in confirm](../../../public/images/namadillo/ibc-in2.png)
+*Confirming the transaction in Keplr*
+</Steps>
+
+## Sending IBC Transfers 'From Namada' (to another chain)
+You can also transfer assets (including, but not limited to, NAM) to another chain. Remember that you can only make outgoing IBC transfers from your transparent 
+address -- if you wish to transfer shielded assets, you must unshield them first.  
+
+Begin by selecting '*From Namada*' **(1)** in the *IBC Transfer* section and follow these steps:  
+
+![IBC out details](../../../public/images/namadillo/ibc-out1.png)
+*IBC Transferring assets out of Namada*
+
+<Steps>
+### Enter the transfer details
+- **(2)**: Your transparent address (from which the transfer is being sent). This is automatically filled from the Keychain extension based on your 
+currently selected account. Note that outgoing IBC transfers using Namadillo cannot be made from a shielded account.
+- **(3)**: Click to select the asset you wish to transfer.
+- **(4)**: Enter the amount to transfer.
+- **(5)**: Select *My Address* to automatically set the receiver to your Keplr address on the destination chain. Select *Custom Address* to enter a different address. 
+(See below for more details.)
+- **(6)**: Click here to select the destination chain.
+- **(7)**: The transaction fee for this transfer -- note that fees are paid in NAM.
+- **(8)**: When you've chosen an asset, amount, destination chain, and receiving address, click *Submit* to begin the transfer.  
+
+**Setting a custom receiver address:**  
+By selecting *Custom Address*, you can send assets to an address not in your Keplr wallet. Choosing this option also (optionally) lets you attach 
+a memo to the transaction. *Make sure the receiver is a valid address on the destination chain* -- e.g. if the destination chain is *Osmosis*, the 
+address should have an *osmo* prefix.
+
+
+![IBC custom receiver](../../../public/images/namadillo/ibc-out2.png)
+
+### Click 'Submit' and approve your transaction
+After entering the required transfer info, click *Submit*. You'll be prompted to approve the transaction and it will begin processing. When the transfer 
+has completed, the status will update to show *Transfer Completed*.
+</Steps> 

packages/docs/pages/users/namadillo/masp.mdx

@@ -1,4 +1,4 @@
-import { Callout } from 'nextra-theme-docs'
+import { Callout, Steps } from 'nextra-theme-docs'
 
 # Shielding Assets with Namadillo
 
@@ -7,4 +7,89 @@ Namada mainnet will launch with most functionality aside from staking and govern
 few weeks. Therefore, some sections of Namadillo will not be accessible immediately after launch until its respective functionality has been activated on mainnet.  
 
 Until then, you can experiment with all aspects of Namadillo on [testnet](../networks/testnets.mdx).
-</Callout>
+</Callout>
+
+One of Namada's flagship features is the ability to move your assets into the **Multi-Asset Shielded Pool** (*a.k.a.* the 
+*MASP* or *Shielded Pool*). Moving assets into the pool to your shielded balance is referred to as *shielding*, and moving assets out of the pool to your transparent balance 
+is referred to as *unshielding*. By holding eligible assets in the MASP you'll earn rewards in the form of *NAM*, which will automatically 
+be added to your shielded balance each epoch.  
+
+You can use the *MASP* tab of Namadillo to manage your shielded assets and rewards, including: 
+- viewing your current asset balances
+- shielding and unshielding assets
+- viewing your estimated shielded rewards per epoch  
+
+You can also transfer shielded assets from your shielded account to another shielded recipient (*i.e.* a **Shielded Transfer**) in Namadillo's *Transfer* tab. 
+For instructions on the steps to make a shielded transfer using Namadillo, refer to the [Transfer](./transfer.mdx) section of this guide.
+
+## Shielded Assets (MASP) Dashboard
+Select **MASP** from Namadillo's left sidebar to open the dashboard **(below)**. On the dashboard, you can see:
+- **(1)** and **(2)**: Your total shielded balance and shielded NAM balances, respectively.
+- **(3)**: Your estimated shielded rewards per epoch.
+- **(4)**: A list of all your currently owned shielded assets.
+- **(5)**: Click any of the buttons marked **Shield Assets** to shield an asset, moving it from your transparent balance to your shielded balance.
+- **(6)**: Click the **Unshield** button beside any of your shielded assets to unshield some or all of that asset  
+
+![MASP dashboard](../../../public/images/namadillo/shield1.png)
+*Clicking 'MASP' in the left sidebar lets you manage your shielded assets*
+
+## Shielding Assets
+From the Shielded Assets (MASP) Dashboard, follow these steps to shield an asset:
+<Steps>
+### Click any of the buttons marked 'Shield Assets'
+This will open the Shielding dialog as shown below.
+
+### Choose an asset type and amount
+Your transparent and shielded addresses will be automatically entered based on your active account in the Keychain browser extension. 
+First, check that they match the expected values. If not, open the Keychain extension to switch to the correct account.  
+
+- **(1)**: Click here to select an asset type.
+- **(2)**: Enter the amount you wish to shield here.
+- **(3)**: After choosing an asset and amount, click **Submit** to begin shielding.  
+
+![Shielding step 2](../../../public/images/namadillo/shield2.png)
+*Choosing the asset and amount to shield*
+
+### Click 'Submit' and approve your transaction
+After entering the required info, click **Submit**. You will be prompted by the extension to approve the transaction; if you're using 
+a Ledger, you will be prompted to confirm on the device, otherwise you will be prompted to enter your password. **Note: it may take slightly longer 
+to construct the shielding transaction and show the confirmation dialog compared with other transaction types.**  
+
+After confirming, an animation will play to show that your shielding transaction is being processed. After roughly 10 seconds, the display will update 
+with *Shielded Transfer Complete* as in the following image:  
+
+![Shielding step 3](../../../public/images/namadillo/shield3.png)
+*Shielding transaction confirmation*
+</Steps>
+
+## Unshielding Assets
+The process for unshielding assets is very similar to shielding them. 
+
+<Steps>
+### Find your current shielded assets
+Click **MASP** in Namadillo's sidebar to open the MASP dashboard, and find the list of your current shielded assets in the **Shielded Overview** section.
+
+### Click 'Unshield'
+Click the button marked **Unshield** beside the asset you wish to unshield. This will open the Unshield dialog, where your selected asset type, shielded address and transparent 
+address will all be automatically entered. You will need to enter the amount you wish to unshield and click 'Submit' when you're ready.  
+
+![Unshielding](../../../public/images/namadillo/unshield.png)
+*Unshielding an asset*
+
+### Click 'Submit' and approve your transaction
+Follow the prompts to approve your transaction and wait for it to process, as explained in the previous section on 
+[shielding](#click-submit-and-approve-your-transaction).
+</Steps>
+
+## Viewing your estimated Shielded Rewards
+Shielded rewards accrue each epoch based on the amount of assets you have shielded, and are automatically added to your shielded *NAM* balance. You can 
+view an estimate of your expected rewards per epoch both in the **MASP** and **Overview** (homepage) sections of Namadillo.  
+
+<Callout type="warning">
+**Note:** your actual shielded rewards will depend on the total asset amounts held in the MASP by all users. Therefore, the number shown is only an estimate.
+
+</Callout>
+
+Not all asset types will earn shielded rewards at the same rate; you can view the reward rate of each shielded asset in the **MASP dashboard** in the 
+**Shielded Overview** section, which contains a list of your current shielded assets. Check the column named **SSR Rate** for the reward rate of eligible assets (if no rate is listed, 
+that asset is not eligible for shielded rewards).

packages/docs/pages/users/namadillo/transfer.mdx

@@ -1,4 +1,4 @@
-import { Callout } from 'nextra-theme-docs'
+import { Callout, Steps } from 'nextra-theme-docs'
 
 # Shielded and Transparent Transfers with Namadillo
 
@@ -7,4 +7,57 @@ Namada mainnet will launch with most functionality aside from staking and govern
 few weeks. Therefore, some sections of Namadillo will not be accessible immediately after launch until its respective functionality has been activated on mainnet.  
 
 Until then, you can experiment with all aspects of Namadillo on [testnet](../networks/testnets.mdx).
-</Callout>
+</Callout>
+
+Namadillo supports both shielded and transparent transfers of NAM and any other token asset.  
+
+- **Shielded Transfers:** Are sent from one shielded (`znam...`) address to another. This helps prevent third-parties from knowing the details of your 
+transactions\*. 
+- **Transparent Transfers:** Are sent from one transparent (`tnam...`) address to another. A third party viewing the transaction will be able 
+to see the sending address, receiving address, token and amount. Remember that a third party can view the balances and transaction history 
+of any transparent address at any point in the chain's history.  
+
+<Callout type='info'>
+**\* Note:** while shielded transfers keep your transaction details secure within the protocol itself, be careful not to leak extra information that could allow others to make inferences about 
+your activity based on your usage patterns.  
+
+Consider the analogy of borrowing books from a library. If you regularly borrow books on a very specific topic, and only a few people are interested in that topic, others might start guessing 
+that you're the one borrowing them. Even though the library doesn't reveal your name, your borrowing pattern gives you away.  
+
+See [this section](../../introduction/privacy.mdx) for more information and best practices.
+</Callout>
+
+## Sending a transfer
+<Steps>
+### Select 'Transfer' from the left sidebar
+This will open the *Transfer* dialog, as shown in the image below.
+
+### Choose the transfer type (Shielded/Transparent)
+Click the toggle **(marked 1, in the below image)** to switch between shielded and transparent transfers.
+
+### Enter the transfer info
+First, check that the sending address displayed near the top of the dialog is the one you expect. If not, open the Keychain extension to switch between your 
+accounts.  
+
+![Transfer dialog](../../../public/images/namadillo/transfer1.png)
+*The Transfer dialog for sending both shielded and transparent transfers*  
+
+- **(2)**: Your sending address (automatically filled from the Keychain extension).
+- **(3)**: Click here to choose the asset you wish to send.
+- **(4)**: Enter the amount you wish to send here.
+- **(5)**: Enter the recipient address here. If you've selected shielded transfer, the recipient must be a `znam` (shielded) address. 
+If you've selected transparent transfer, the recipient must be a `tnam` (transparent) address.
+- **(6)**: (Optionally) enter the memo here. If you're sending (depositing) to a centralized exchange, you are often required by the exchange to 
+attach a specific memo in order for your transfer to be processed correctly. Check with your exchange to see what they require.
+- **(7)**: Click to submit your transfer after filling in the required info.
+
+### Click 'Submit' and approve your transaction
+After entering the required transfer info, click **Submit**. You will be prompted by the extension to approve the transaction; if you're using 
+a Ledger, you will be prompted to confirm on the device, otherwise you will be prompted to enter your password.  
+
+After confirming, you'll see a grey dialog box in the top right corner of Namadillo to let you know that your transaction has been submitted 
+and is being processed. After roughly 10 seconds, you will see either a green or red dialog box to let you know if your transaction was approved.  
+
+![Submit Transfer](../../../public/images/namadillo/transfer2.png)
+*Completing the transfer*
+</Steps>