Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added shielded sync documentation #377

Merged
merged 2 commits into from
Aug 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/docs/pages/users/shielded-accounts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

3 changes: 2 additions & 1 deletion packages/docs/pages/users/shielded-accounts/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,6 @@
"glossary": "Glossary",
"masp-keys": "Shielded Key Management",
"shielding": "Shielding Assets",
"unshielding": "Unshielding Assets"
"unshielding": "Unshielding Assets",
"shielded-sync": "Shielded Sync"
}
81 changes: 81 additions & 0 deletions packages/docs/pages/users/shielded-accounts/shielded-sync.mdx
Original file line number Diff line number Diff line change
@@ -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>
21 changes: 3 additions & 18 deletions packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
15 changes: 2 additions & 13 deletions packages/docs/pages/users/shielded-accounts/shielding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 2 additions & 4 deletions packages/docs/pages/users/shielded-accounts/unshielding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading