Merge branch 'bat/shielded-sync' (#377)

Added shielded sync documentation

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

@@ -21,6 +21,7 @@ If you are familiar with Zcash, the set of interactions you can execute with Nam
 - [Shielding transfers](./shielded-accounts/shielding.mdx): transparent to shielded address
 - [Shielded transfers](./shielded-accounts/shielded-transfers.mdx): shielded to shielded address
 - [Unshielding transfers](./shielded-accounts/unshielding.mdx): shielded to transparent address
+- [Shielded Sync](./shielded-accounts/shielded-sync.mdx): Sync a user's local view of the MASP with the chain
 
 More technical details of these circuits can be found in the [specs](https://specs.namada.net/modules/masp) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits).
 

packages/docs/pages/users/shielded-accounts/_meta.json

@@ -2,5 +2,6 @@
   "glossary": "Glossary",
   "masp-keys": "Shielded Key Management",
   "shielding": "Shielding Assets",
-  "unshielding": "Unshielding Assets"
+  "unshielding": "Unshielding Assets",
+  "shielded-sync": "Shielded Sync"
 }

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

@@ -0,0 +1,81 @@
+import { Callout } from 'nextra-theme-docs'
+
+# Shielded Sync
+
+In order to interact with the MASP, users need a local copy of all of the notes. This is
+necessary to create new notes with the correct zk-proofs. Additionally, it is the only way
+for a client to find out which notes are owned by the user, which is necessary for calculating balances.
+
+Shielded sync is the command that downloads and processes a local view of the MASP (up to
+a given block height) and then stores it locally in a `shielded context`. This command must be
+run periodically to stay in sync with the tip of the chain.
+
+## Running shielded sync
+
+The simplest way to run shielded sync is via the command:
+```bash copy
+namadac shielded-sync
+```
+This assumes several things by default. It will look into the user's wallet and import any MASP
+keys into the shielded context. These will be the keys used to attempt to decrypt the downloaded
+MASP notes. Additional keys can be provided via:
+```bash copy
+namadac shielded-sync --spending-keys $SPENDING_KEY
+```
+and / or
+```bash copy
+namadac shielded-sync --viewing-keys $VIEWING_KEY
+```
+
+<Callout>
+The first time you wish to check the balance of a spending/viewing key, you must provide it to the shielded context with
+the `--spending-keys|--viewing-keys` argument. On subsequent runs, you can simply use `namadac shielded-sync`, as these
+keys will be stored in the shielded context.
+</Callout>
+
+Shielded sync also assumes by default that the user wishes to sync to the tip of the chain. If this is not
+the case, a maximal height to sync to can be provided:
+```bash copy
+namadac shielded-sync --to-height $BLOCKHEIGHT
+```
+
+## Interrupting
+
+If the shielded context is sufficiently behind the tip of the chain, the amount of data to be downloaded
+and the computational load of processing it can be cumbersome. This is one reason why a user might
+wish to specify a maximal height to which to sync.
+
+Additionally, the user can interrupt shielded sync at anytime by pressing `CTRL-C` or similar stop
+command. Shielded sync will receive this signal and save its work before stopping. This avoids
+losing work and can be resumed the next time shielded sync is run.
+
+## Using a MASP indexer
+
+A MASP indexer can do a lot of the processing of MASP data and make it available to users via a
+web server that can handle large downloads and many requests. This is in contrast to syncing
+by calling the RPC endpoints of node operators.
+
+Thus, the preferred and most efficient way to run shielded sync is by using an indexer:
+```bash copy
+namadac shielded-sync --with-indexer $INDEXER_API_URL
+```
+The api endpoint `$INDEXER_API_URL` will be a url to the indexer ending with `/api/v1`.
+
+## Recovering from data corruption
+
+If, for some reason, the shielded context gets corrupted and shielded sync cannot function correctly,
+a user can try to remove all local data and sync again from scratch. The shielded context is stored
+in the user's chain directory and the generated files have the following names:
+ * `shielded.dat`
+ * `shielded.tmp`
+ * `speculative_shielded.dat`
+ * `shielded_sync.cache`
+ * `shielded_sync.cache.tmp`
+
+ If these files are deleted, shielded sync can be run in order to resync from scratch.
+
+<Callout>
+Removing or modifying these files is not recommended and should only be done as a last resort.
+Also note that the user will need to provided the necessary viewing and spending keys to
+shielded sync again.
+</Callout>

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

@@ -6,10 +6,7 @@ Once the user has a [shielded balance](./shielding.mdx), it can be transferred t
 
 ## Making a shielded transfer
 
-Before making a shielded transfer, it is recommended to first sync the local shielded context:
-```bash copy
-namadac shielded-sync --spending-keys $SPENDING_KEY
-```
+Before making a shielded transfer, it is recommended to first sync the local shielded context. See how to do this [here](shielded-sync.mdx).
 
 To make a shielded transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for
 an explanation on the types of keys and addresses used with the MASP.
@@ -30,20 +27,8 @@ Note: you must provide an implicit account which you control containing funds fo
 
 
 ### Viewing your balance
-To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to
-sync the local shielded context with any MASP notes owned by your spending/viewing key:
-```bash copy
-namadac shielded-sync --spending-keys $SPENDING_KEY
-```
-or
-```bash copy
-namadac shielded-sync --viewing-keys $VIEWING_KEY
-```
-
-<Callout>
-The first time you wish to check the balance of a spending/viewing key, you must provide it to the shielded context with 
-`--spending-keys|--viewing-keys`. On subsequent runs, you can simply use `namadac shielded-sync`.
-</Callout>
+To view the up-to-date balance of your spending key (or viewing key), you must first run the [`shielded-sync`](shielded-sync.mdx) command to
+sync the local shielded context with any MASP notes owned by your spending/viewing key.
 
 After the sync has completed, check your balance with:
 ```bash copy

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

@@ -41,19 +41,8 @@ namadac shield \
 
 ### Viewing your balance
 To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to
-sync the local shielded context with any MASP notes owned by your spending/viewing key:
-```bash copy
-namadac shielded-sync --spending-keys $SPENDING_KEY
-```
-or
-```bash copy
-namadac shielded-sync --viewing-keys $VIEWING_KEY
-```
-
-<Callout>
-The first time you wish to check the balance of a spending/viewing key, you must provide it to the shielded context with 
-`--spending-keys|--viewing-keys`. On subsequent runs, you can simply use `namadac shielded-sync`.
-</Callout>
+sync the local shielded context with any MASP notes owned by your spending/viewing key.
+See how to do this [here](shielded-sync.mdx).
 
 After the sync has completed, check your balance with:
 ```bash copy

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

@@ -8,10 +8,8 @@ Assets can also be sent directly from a shielded address through IBC -- see the
 
 ## Making an unshielding transfer
 
-Before making an unshielding transfer, it is recommended to first sync the local shielded context:
-```bash copy
-namadac shielded-sync --spending-keys $SPENDING_KEY
-```
+Before making an unshielding transfer, it is recommended to first sync the local shielded context.
+See how to do that [here](shielded-sync.mdx).
 
 To make an unshielding transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for
 an explanation on the types of keys and addresses used with the MASP.