diff --git a/packages/docs/pages/users/shielded-accounts.mdx b/packages/docs/pages/users/shielded-accounts.mdx index 1018df5b..9c4869d4 100644 --- a/packages/docs/pages/users/shielded-accounts.mdx +++ b/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). diff --git a/packages/docs/pages/users/shielded-accounts/_meta.json b/packages/docs/pages/users/shielded-accounts/_meta.json index 67269d47..76bb7cc5 100644 --- a/packages/docs/pages/users/shielded-accounts/_meta.json +++ b/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" } \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-sync.mdx b/packages/docs/pages/users/shielded-accounts/shielded-sync.mdx new file mode 100644 index 00000000..85983ad0 --- /dev/null +++ b/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 +``` + + +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. + + +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. + + +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. + \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index ce8ef29c..12643afa 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/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 -``` - - -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`. - +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 diff --git a/packages/docs/pages/users/shielded-accounts/shielding.mdx b/packages/docs/pages/users/shielded-accounts/shielding.mdx index 86bb7398..07d3e69a 100644 --- a/packages/docs/pages/users/shielded-accounts/shielding.mdx +++ b/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 -``` - - -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`. - +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 diff --git a/packages/docs/pages/users/shielded-accounts/unshielding.mdx b/packages/docs/pages/users/shielded-accounts/unshielding.mdx index 037eba36..4c680649 100644 --- a/packages/docs/pages/users/shielded-accounts/unshielding.mdx +++ b/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.