Skip to content

Commit b01b0ed

Browse files
brentstonebrentstone
authored
Merge pull request #446 from anoma/ian/keychain-guide
update namada keychain docs
2 parents cfe5699 + edc5b88 commit b01b0ed

File tree

18 files changed

+297
-82
lines changed

18 files changed

+297
-82
lines changed

‎packages/docs/pages/users/_meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@
99
"public-goods-funding": "Public Goods Funding (PGF)",
1010
"ibc": "IBC transfers",
1111
"query": "Querying the Chain",
12+
"keychain": "Namada Keychain",
1213
"namadillo": "Using Namadillo"
1314
}

‎packages/docs/pages/users/keychain.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { Callout } from 'nextra-theme-docs'
2+
3+
# Namada Keychain Browser Extension
4+
5+
The [Namada Keychain](https://namada.net/extension) is a browser extension that allows you to easily manage your Namada keys/accounts. By connecting Namada Keychain with
6+
web apps built for Namada (such as [Namadillo](https://namada.net/apps#interfaces)), you can send or receive tokens, make IBC transfers, or perform other actions such as
7+
voting on governance proposals.
8+
9+
The following sections will walk you through the installation, setup, and usage of Namada Keychain.
10+
11+
### Video Tutorial
12+
13+
If you prefer video guides, check out the tutorials available on [namada.help](https://www.namada.help/tutorials?filter=Namada+Keychain), which provide detailed walkthroughs of installation, setup, and
14+
many common uses of Namada Keychain.

‎packages/docs/pages/users/keychain/_meta.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"start-here": "Before You Begin",
3+
"installing": "Installing Namada Keychain",
4+
"add-keys": "Creating and Importing Accounts",
5+
"manage-keys": "Viewing and Managing Accounts",
6+
"ledger": "Using a Ledger Hardware Wallet",
7+
"configure": "Settings and Options"
8+
}

‎packages/docs/pages/users/keychain/add-keys.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
import { Callout, Steps } from 'nextra-theme-docs'
2+
3+
# Creating and Importing Accounts
4+
5+
To use Namada Keychain, you'll need to create (or import) an account (*a.k.a* your 'Keys' or your 'Wallet'). Creating an account
6+
will generate a transparent and shielded address and a set of secret keys—allowing you to send and receive tokens, as well as
7+
sign transactions to stake, vote on governance, and more.
8+
9+
You can have several accounts in your keychain at the same time and switch between them as needed.
10+
11+
## Creating a New Account
12+
13+
<Callout type="info">
14+
If you want to create an account using a Ledger hardware wallet, see the [dedicated section](./ledger) for Ledger-specific instructions.
15+
</Callout>
16+
17+
1. Open Namada Keychain by clicking the extension icon in your browser toolbar. If you've previously completed the setup process,
18+
you'll see your current list of accounts. From here, click the "Add Keys" button in the top right corner to open a full-page modal
19+
with options to create a new account or import an existing one. (If this is your first time opening the extension, you'll be taken
20+
to the full-page view immediately.)
21+
22+
![Add Keys](../../../public/images/keychain/add-key.png)
23+
24+
2. Click the "Create New Keys" button to create a new account. Carefully review the warning message about the
25+
importance of keeping your seed phrase safe, then proceed to the next page.
26+
27+
3. Reveal your seed phrase by mousing over it. You can choose to generate either a 12 or 24 word seed phrase by clicking the
28+
toggle button above the seed phrase. Use '12 words' if you're unsure which to choose. Write down or otherwise securely save your seed phrase and proceed to the next
29+
screen, where you'll be asked to confirm two random words in order to verify that you've saved your seed phrase correctly.
30+
31+
4. On the next screen, you'll be asked to name your new account under 'Keys Name.' This is a label for your account, and can be changed later. **If this is your first time
32+
creating an account**, you'll also be asked to set a password for the extension (otherwise, you will only see an input field for 'Keys Name').
33+
34+
![Create Flow](../../../public/images/keychain/create-flow.png)
35+
36+
If you've previously set a password for the extension, you won't be asked to set a new one. If you wish to change your password, you can do so at a later time in the [settings](./configure)
37+
menu.
38+
<Callout type="warning">
39+
You'll be periodically asked to confirm this password when you open the extension, connect
40+
to an app, or sign transactions -- so make sure you back it up along with your seed phrase! Losing either your seed phrase or password can result in you losing access to your
41+
funds.
42+
</Callout>
43+
44+
45+
5. Finally, you'll be shown your new account's transparent and shielded addresses, as well as your public key. (It's not necessary to save these as you can view them at any time.)
46+
Click "Finish Setup" to complete the process.
47+
48+
## Importing an Existing Account
49+
50+
Importing an existing account is very similar to creating a new account, except after clicking the "Add Keys" button you should select "Import Existing Keys"
51+
instead of "Create New Keys."
52+
53+
![Import](../../../public/images/keychain/import.png)
54+
55+
You'll be asked to provide the seed for your existing account in one of the following formats:
56+
- A 12 word seed phrase
57+
- A 24 word seed phrase
58+
- A raw hex private key
59+
- A raw hex spending key
60+
61+
Finally, you'll be asked to name your account, and (**if this is your first time initializing an account only**) set a password for the extension.
62+
63+
64+
## Switching Between Accounts
65+
66+
You can have multiple accounts in your keychain at the same time, but only one account will be active at a time. To switch between accounts,
67+
click the Namada Keychain extension icon in your browser toolbar and click the checkbox to the left of the account you wish to use.
68+
69+
Alternatively, you can click the 'three vertical dots' icon `⋮` next to the desired account and select "Set default account."
70+
71+
72+
# Video Tutorial
73+
For video tutorials on creating and importing accounts, see the following sections of [namada.help](https://www.namada.help/):
74+
- [How to Create a Wallet](https://www.namada.help/tutorials/how-to-create-a-wallet)
75+
- [How to Import a Wallet](https://www.namada.help/tutorials/how-to-import-a-wallet)

‎packages/docs/pages/users/keychain/configure.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { Callout } from 'nextra-theme-docs'
2+
3+
# Configure Namada Keychain
4+
Follow this quick reference guide to configure the Namada Keychain extension.
5+
6+
## Change Password
7+
To change the master password for your keychain, click the settings icon `⚙️` in the top right corner of the extension and select "Change Password." You will be prompted to enter your
8+
current password and then your new password.
9+
10+
## View or Manage Connected Sites
11+
Click the settings icon `⚙️` in the top right corner of the extension and select "Connected Sites" to show a list of sites that you have granted access to your keychain. You can click the `X`
12+
next to a site to revoke access from that site, or click the "Disconnect All" button to revoke all connections.
13+
14+
## View or Change the Active Chain-Id
15+
Click the settings icon `⚙️` in the top right corner of the extension and select "Network" to show the currently active Chain-Id. You can also manually set the Chain-Id by
16+
entering a new value in the input field and clicking the "Submit" button.
17+
18+
<Callout type="info">
19+
You will typically not need to set or change the Chain-Id manually, as this will be managed by the app you're using.
20+
</Callout>
21+
22+
## Show the Extension Version
23+
Clicking the settings icon `⚙️` in the top right corner of the extension will display the Keychain Version, Revision, and SDK Version.

‎packages/docs/pages/users/keychain/installing.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import { Callout } from 'nextra-theme-docs'
2+
3+
# Installing Namada Keychain
4+
5+
Namada Keychain is available for Chrome (Firefox coming soon) on the [Chrome Webstore](https://chromewebstore.google.com/detail/namada-keychain/hnebcbhjpeejiclgbohcijljcnjdofek).
6+
Simply click the "Add to Chrome" button to install the extension.
7+
8+
## Video Tutorial
9+
For more detailed installation instructions, including screenshots and a video tutorial,
10+
see the installation guide on [namada.help](https://www.namada.help/tutorials/namada-keychain-extension-installation).

‎packages/docs/pages/users/keychain/ledger.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import { Callout, Steps } from 'nextra-theme-docs'
2+
3+
# Using a Ledger Hardware Wallet
4+
5+
You can use a [Ledger](https://www.ledger.com/) hardware wallet with the Namada Keychain extension. A hardware wallet is a physical device that generates and manages your
6+
private keys within the device itself, keeping them isolated from your computer and the internet. You connect your Ledger to your computer via USB and sign transactions by confirming
7+
via physical buttons on the device, adding an extra layer of security.
8+
9+
<Callout type="info">
10+
Due to Ledger hardware limitations, you can only use shielded (MASP) operations with a Ledger Nano S Plus or newer.
11+
You can still use older devices for transparent operations such as staking and claiming rewards.
12+
</Callout>
13+
14+
## Initial Setup
15+
16+
<Steps>
17+
### Install Ledger Live
18+
Install the [Ledger Live](https://www.ledger.com/ledger-live) app and complete the initial setup process for your Ledger, if you haven't already. See [Getting Started](https://support.ledger.com/article/4404389503889-zd)
19+
on the Ledger support site for more information.
20+
21+
### Install the Namada Ledger App
22+
- Open Ledger Live and connect your Ledger device.
23+
- Make sure your Ledger device is on the latest firmware. You can update your firmware in Ledger Live, in the "My Ledger" section.
24+
- Access "My Ledger": Click on the My Ledger icon located in the bottom-left corner of the Ledger Live window.
25+
- Connect Your Ledger Device: Plug in your Ledger device and unlock it by entering your PIN.
26+
- Install the Namada App: In the App Catalog, use the search bar to find "Namada." Click the "Install" button to install the Namada application on your Ledger.
27+
28+
### Create a New Account with your Ledger
29+
**Note:** See also the section on [Creating a New Account](./add-keys#creating-a-new-account). There are some minor differences
30+
in the process when using a Ledger device which are detailed below.
31+
32+
- Open Namada Keychain by clicking the extension icon in your browser toolbar. If you've previously completed the setup process,
33+
you'll see your current list of accounts. From here, click the "Add Keys" button in the top right corner to open a full-page modal
34+
with options to create a new account or import an existing one. (If this is your first time opening the extension, you'll be taken
35+
to the full-page view immediately.)
36+
37+
![Add Keys](../../../public/images/keychain/add-key.png)
38+
39+
- Select the "Connect Hardware Wallet" option.
40+
- Follow Step 1: Connect your Ledger device to your computer via USB and unlock it by entering your PIN. Click "Next" when ready. You may be prompted by your browser to allow
41+
a USB connection to your Ledger device.
42+
43+
![Connect Ledger](../../../public/images/keychain/ledger-connect.png)
44+
45+
- Follow Step 2: Open the Namada app on your Ledger device and click "Next" when ready.
46+
<Callout type="info">
47+
You can choose a custom derivation path by clicking the "Advanced" button located near the top of the view. You can use this option to derive multiple accounts from
48+
the same Ledger. If you're unsure what derivation paths are or how they work, ignore this setting and use the default. To
49+
learn more about derivation paths, see https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths.
50+
</Callout>
51+
- Your account will be derived from the seed stored in your Ledger device. You will be prompted to confirm each step on the Ledger
52+
device itself (you may need to do this several times).
53+
54+
![Approve](../../../public/images/keychain/ledger-derive.png)
55+
56+
- After confirming on the Ledger, provide a name for your account when prompted on-screen and click "Next."
57+
- Click "Create" to complete the process.
58+
- Your transparent address and public key will be displayed on-screen. If you're using a Ledger Nano S Plus or newer,
59+
you'll also see a shielded address. You don't need to save these addresses as you can view them at any time in the extension.
60+
- Click "Finish Setup" to complete the process.
61+
</Steps>
62+
63+
### Differences from 'Standard' Accounts
64+
65+
Since Ledger-based accounts are derived from a seed stored in the device, the "View Seed Phrase" option will be greyed out. And
66+
since your private keys are managed by the Ledger and not stored in the extension, the "Display Spending Key" option is not available.
67+
68+
## Video Tutorial
69+
For a detailed video walkthrough on how to install the Namada Ledger app and create a new account using a Ledger, see the following section on [namada.help](https://www.namada.help/):
70+
- [How to connect a Ledger device](https://www.namada.help/tutorials/how-to-connect-a-ledger-device)

‎packages/docs/pages/users/keychain/manage-keys.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import { Callout } from 'nextra-theme-docs'
2+
3+
# Managing Accounts
4+
5+
Follow this quick reference guide to learn how to manage your accounts in the Namada Keychain extension.
6+
7+
## View Your Keys and Addresses
8+
Click the three vertical dots `⋮` next to an account and select "View keys" to display your addresses and public keys. From here,
9+
you can also click the buttons at the bottom to display your Viewing Key and Spending Key (you will be prompted for your password).
10+
<Callout type="warning">
11+
Remember: your addresses and public
12+
keys are safe to share, but your Viewing and Spending Keys should always be kept private!
13+
</Callout>
14+
15+
## Generate a New Payment (Shielded) Address
16+
Each account can generate many thousands of Payment (Shielded) Addresses, and your total shielded balance will be the sum of all
17+
Payment Address balances belonging to your account. To generate a new Payment Address, first click the three vertical dots `⋮` next to an account and select "View keys." From here, click
18+
the "Generate Payment Address" button at the bottom of the view. Upon clicking this button, you'll notice the Shielded Address
19+
displayed directly above has changed.
20+
21+
## View Your Seed Phrase
22+
You can view the seed phrase for an account by clicking the three vertical dots `⋮` next to it in the accounts list and selecting "View Seed Phrase." You'll be prompted for your password
23+
before the seed phrase is displayed. Note that if you're using a Ledger hardware wallet, this option will not be available because the account seed is tied to the Ledger device.
24+
<Callout type="error">
25+
Never share your seed phrase! Anyone who knows your seed phrase can steal your funds.
26+
</Callout>
27+
28+
## Rename an Account
29+
Click the three vertical dots `⋮` next to an account and select "Rename" to choose a new name.
30+
31+
## Delete an Account
32+
Click the three vertical dots `⋮` next to an account and select "Delete" to remove it from your keychain (you will be prompted for your password). Your account and funds will
33+
still exist on the blockchain, but you will no longer be able to access it through the Namada Keychain extension until you [import](./add-keys.mdx) it again using its seed phrase.
34+
35+
## Video Tutorial
36+
For a visual guide on how to manage your accounts, check out the following videos on [namada.help](https://www.namada.help/):
37+
38+
- [How to view your keys](https://www.namada.help/tutorials/how-to-view-your-keys)
39+
- [How to view your seed phrase](https://www.namada.help/tutorials/how-to-view-your-seed-phrase)
40+
- [How to rename your wallet](https://www.namada.help/tutorials/how-to-rename-your-wallet)
41+
- [How to delete your wallet](https://www.namada.help/tutorials/how-to-delete-your-wallet)

‎packages/docs/pages/users/keychain/start-here.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { Callout } from 'nextra-theme-docs'
2+
3+
# Before You Begin
4+
5+
<Callout type="warning">
6+
Read this section carefully to avoid losing any funds down the road!
7+
</Callout>
8+
9+
Both the biggest advantage and biggest risk of using a decentralized network like Namada is that nobody controls access to your funds except for yourself. While this is
10+
incredibly empowering, it also means that if you lose your account's secret keys or seed phrase, you will lose access to your funds forever. There is no bank manager
11+
or customer support to turn to if you lose access to your account.
12+
13+
The good news is you can protect yourself by taking a few basic precautions when creating your account. We'll cover the most
14+
important of these below.
15+
16+
## Store Your Password and Seed Phrase Offline
17+
18+
### Seed Phrase
19+
20+
When you create a new account, you'll be given a 12 or 24 word seed phrase (also known as a 'recovery phrase' or 'mnemonic'). You can use this phrase to restore your account
21+
in the extension or Namada CLI at a later time. This phrase is the only way to recover your account if you lose your secret keys, so it's important to save it in a secure location,
22+
offline, both so that it cannot be accessed by online attackers or malware on your computer and so that you're protected in
23+
case your computer breaks, is lost, or is stolen.
24+
25+
<Callout type="error">
26+
Never, under any circumstance, share your seed phrase with anyone! Phishing attacks, fake websites, and other scams are rampant on the internet. Anyone who learns your
27+
seed phrase can access your account and steal your funds.
28+
- No member of Heliax or anyone affiliated with Namada will ever ask you for your seed phrase. However, scammers may pose as Heliax or Namada Support and ask you to share
29+
your seed phrase under the guise of helping you recover your account.
30+
- Do not enter your seed phrase into any websites, apps, or wallets unless you are absolutely certain they are trustworthy. A website or wallet asking you
31+
to enter your seed phrase (for example,to import your account or check your airdrop allocation) may simply intend to use it to turn around and steal your funds.
32+
</Callout>
33+
34+
### Password
35+
36+
When you create your first account, you'll be asked to set a password for your Namada Keychain extension. You'll be asked for this password every time you open the extension,
37+
as well as on other actions such as signing transactions or connecting to a website.
38+
39+
Like your seed phrase, it's important to save your password in a secure location, offline. If you forget your password, there is no way to recover it; remember, there are no
40+
central servers, so unlike forgetting your Spotify password, there is no "Recover Password by Email" option.
41+
42+
### What if I Lose My Password and/or Seed Phrase?
43+
44+
- If you lose your password, you will have to reinstall the Namada Keychain extension and restore your account(s) using their seed phrase(s).
45+
- If you've lost your seed phrase, you will not be able to restore your account and will lose your funds forever.
46+
47+
<Callout type="info">
48+
Ask yourself: "If my computer breaks or is stolen, can I recover my account?" As long as you've securely saved your seed phrase(s) offline, the answer is yes.
49+
</Callout>

‎packages/docs/pages/users/wallet.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,5 @@ To read more about addresses, see [An introduction to Namada addresses](./transp
1515
Check out the different options to generate a wallet:
1616

1717
- [File System Wallet](./wallet/file-system-wallet.mdx)
18-
- [Namada Keychain (browser extension)](./wallet/web-wallet.mdx)
18+
- [Namada Keychain Browser Extension](./keychain.mdx)
1919
- [Hardware Wallet](./wallet/hardware-wallet.mdx)

0 commit comments

Comments
 (0)