diff --git a/packages/docs/pages/integrating-with-namada/_meta.json b/packages/docs/pages/integrating-with-namada/_meta.json index 5256093c..a7a66d23 100644 --- a/packages/docs/pages/integrating-with-namada/_meta.json +++ b/packages/docs/pages/integrating-with-namada/_meta.json @@ -1,5 +1,6 @@ { "sdk" : "Using the SDK", "light-sdk": "Using the Light SDK", - "indexer": "Using the Indexer" + "indexer": "Using the Indexer", + "interface": "Namada Interface" } diff --git a/packages/docs/pages/integrating-with-namada/interface.mdx b/packages/docs/pages/integrating-with-namada/interface.mdx new file mode 100644 index 00000000..3977c081 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/interface.mdx @@ -0,0 +1,34 @@ +# Namada Interface + +## Front end development with Namada +The [namada-interface repository](https://github.com/anoma/namada-interface) is a monorepo which contains the Namada browser extension +and associated Namada-Interface web app. It's a great resource for developers wishing to understand how to incorporate the Namada SDK +into their front-end applications. + +### Installing from source (for development and experiment purposes) + +#### Connect to a testnet or run a local node +1. Follow the instructions for the [testnets](../networks/testnets.mdx) to connect to a testnet or [set up a local node](../operators/networks/local-network.mdx). +2. Figure out where the base directory is stored and save its location as a variable such as `export BASE_DIR=`. + You can follow [these docs](../networks/testnets/migrating-testnets.mdx) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. +3. You will need to edit the CometBFT config in order to allow the web wallet to connect to your node. + The CometBFT config will be located in `$BASE_DIR/$CHAIN_ID/cometbft/config/config.toml`. You will need to change the `cors_allowed_origins` field to `["*"]`. You can do this by running + ```shell copy + sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' \ + $BASE_DIR/$CHAIN_ID/cometbft/config/config.toml + ``` + +#### Setting up the extension +1. Clone the [namada-interface repository](https://github.com/anoma/namada-interface). +2. Follow the installation instructions in `README.md`. +3. `cd` into the `namada-interface/apps/extension` directory and run `yarn start:chrome`. This will build the extension and place it in the `namada-interface/apps/extension/build` directory. It also starts the dev server which will watch for changes. +4. `cd` into the `namada-interface/apps/namada-interface` directory and run `yarn dev:local` in order to launch a local instance of the web wallet. +4. Add the extension to the browser. For example, in Chrome, you can go to `chrome://extensions/` and click `Load unpacked` and select the `namada-interface/apps/extension/build/chrome/` folder. + +## Receiving tokens +You can show the address of any account by pressing the `Receive` button in the initial view under the "Total Balances" tab. You can copy the address by clicking the copy icon next to the address. +This will also display a QR code that can be scanned by a mobile wallet. + +## Sending Transactions + +In order to send transactions, you can press the `Send` button in the initial view under the "Total Balances" tab. This will open a modal that will allow you to send tokens to any account, from any account in your wallet that has a positive balance. diff --git a/packages/docs/pages/users.mdx b/packages/docs/pages/users.mdx index 94d79bad..8cf8e592 100644 --- a/packages/docs/pages/users.mdx +++ b/packages/docs/pages/users.mdx @@ -1,13 +1,17 @@ # User Guide -This guide is tailored towards users who are interested in using Namada to its maximum potential. This guide will include both the most basic operations that a user can execute, as well as the more advanced features that a user can access. +This section covers usage of the Namada software from an end user perspective, including the procedures and commands to create and manage keypairs, +make transparent and shielded transactions, stake tokens, and participate in governance. ## Table of contents +- [Using the Namada wallet](./users/wallet.mdx) - [Transparent Accounts](./users/transparent-accounts.mdx) - [The MASP](./users/shielded-accounts.mdx) - [Fees on Namada](./users/fees.mdx) -- [Delegating on Namada](./users/delegators.mdx) +- [Bonding and Proof-of-stake](./users/delegators.mdx) - [Governance and Public Goods Funding](./users/governance.mdx) -- [Using the Namada wallet](./users/wallet.mdx) +- [PGF](./users/public-goods-stewards.mdx) +- [IBC transfers](./users/ibc.mdx) +- [Querying the chain](./users/query.mdx) diff --git a/packages/docs/pages/users/_meta.json b/packages/docs/pages/users/_meta.json index f2f6129e..a8d5e512 100644 --- a/packages/docs/pages/users/_meta.json +++ b/packages/docs/pages/users/_meta.json @@ -6,5 +6,6 @@ "delegators": "Bonding and Proof-of-stake", "governance": "Governance and Public Goods Funding", "public-goods-stewards": "PGF", - "ibc": "IBC transfers" + "ibc": "IBC transfers", + "query": "Querying the chain" } \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts.mdx b/packages/docs/pages/users/transparent-accounts.mdx index b683ad88..ff82b135 100644 --- a/packages/docs/pages/users/transparent-accounts.mdx +++ b/packages/docs/pages/users/transparent-accounts.mdx @@ -1,106 +1,24 @@ -import { Callout } from 'nextra-theme-docs' - # An Introduction to Namada Addresses All accounts in Namada have a unique address, exactly one Validity Predicate and optionally any additional data in its dynamic storage sub-space. There are currently 3 types of account addresses: -- **Implicit:** An implicit account is derived from your keypair and can be used to authorize certain transactions from the account. Implicit accounts have no code attached to them, and can only have one key controlling it. This differs it from established accounts, which can support multiple keys. -- **Established:** An established account is a associated with one or more cryptographic keys. Each account has the `vp_user` predicate which validate any associated transaction. The main purpose of this code is to ensure that the multisignature threshold is correctly met and stores the keys that verify transactions. All established accounts will be initialized through on-chain transactions, unlike implicit accounts, which exist as soon as the keypair is generated. -- **Internal:** Special internal accounts, such as protocol parameters account, PoS and IBC. +- **Implicit:** An implicit account is the simplest account type. It is derived from a keypair and can be used to authorize certain transactions such as sending and staking tokens, or paying [fees](./fees.mdx). +Implicit accounts have no code attached to them, and can only have one key controlling it. This differs it from established accounts, +which can support multiple keys. +- **Established:** Unlike implicit accounts, which exist as soon as the keypair is generated, an established account must be initialized +with an on-chain transaction. It is associated with one or [more](./transparent-accounts/multisignature.mdx) cryptographic keys. An established account +has the `vp_user` validity predicate which validates any associated transaction to ensure that the multisignature threshold is correctly met. +- **Internal:** These are special internal accounts, such as those for the protocol parameters, proof of stake and IBC modules. -## Manage keypairs +## Managing keypairs Namada uses [ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) keypairs for signing cryptographic operations on the blockchain. -To manage your keys, various sub-commands are available under: - -```shell copy -namada wallet --help -``` - -### Generate a keypair - -It is possible to generate keys using the CLI. By doing so, an implicit account address is also derived in the process and added to storage. - - -Note the use of the placeholder `keysha` for the key parameter. This is a completely configurable parameter, and should just refer to the alias of the key signing the transaction (that has a positive nam balance). - - -```shell copy -KEY_ALIAS="keysha" -namada wallet gen --alias $KEY_ALIAS -``` - - -The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet gen --alias keysha`. - +The `namadaw` binary is used for key management. Various sub-commands are available under: -By default, the keys are stored encrypted. -The encryption password is _not_ a part of key generation randomness. - -Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). -To generate a keypair for a default path use ```shell copy -KEY_ALIAS="keysha" -namada wallet gen --alias $KEY_ALIAS --hd-path default +namadaw --help ``` - -The default HD path for Namada is `m/44'/877'/0'/0'/0'`. - - -Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness. - - -WARNING: Keep your mnemonic code and passphrase safe. -Loss of any of them would inevitably lead to impossible account recovery. - - -### Restore the keypair - -To recover the keypair from your mnemonic code and passphrase use -```shell copy -namada wallet derive --alias keysha --hd-path default -``` - -This will ask you to then enter a passphrase (unless you add the `--unsafe-dont-encrypt` flag), -and then will ask you to enter your mnemonic code. - -### List all known keys - -```shell copy -namada wallet list --keys -``` - -## Manage addresses - - -To manage addresses, similar to keys, various sub-commands are available: - -```shell copy -namada wallet --help -``` - -### Generate an implicit address - -Let's call the implicit address `accountant`: -```shell copy -namada wallet gen --alias accountant -``` - -```shell copy -namada wallet gen --alias keysha --hd-path default -``` -generates an address using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). - -### Restore the address - -```shell copy -namada wallet derive --alias keysha --hd-path default -``` -### List all known addresses - -```shell copy -namada wallet list --addr -``` +See also: [File system wallet](../users/wallet/file-system-wallet.mdx) for examples and additional info on using `namadaw` to manage your keys. \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts/established-accounts.mdx b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx new file mode 100644 index 00000000..0d607f4b --- /dev/null +++ b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx @@ -0,0 +1,27 @@ +import { Callout } from 'nextra-theme-docs' + +# Established accounts + +Unlike implicit accounts, which exist as soon as the keypair is generated, an established account must be initialized +with an on-chain transaction. It is associated with one or [more](./multisignature.mdx) cryptographic keys. + +## Generating an established account + + +Before submitting the transaction to initialize an established account, you must have created an [implicit](./implicit-accounts.mdx) account and funded it with enough +funds to pay for the transaction [fees](../fees.mdx). + + +Initializing an established account entails submitting an `init-account` transaction on-chain to associate the account with +one or more public keys. We'll use the aliases `my-implicit` and `my-established` in this example, where the `my-implicit` account is assumed to have been previously been +created and funded. + +We can create a new established account `my-established` and associate it with the public key of `my-implicit` with: +``` +namadac init-account --alias my-established --public-keys my-implicit --signing-keys my-implicit --threshold 1 +``` +Note that: +- the implicit account `my-implicit` is required to sign the init-account transaction and pay the associated fees (with the `--signing-keys` argument) +- One public key is being associated with the account, and the signing threshold is 1. Technically, all established accounts are multisignature accounts +and therefore a 'typical' established account can be considered a '1 of 1' multisignature account. See [here](./multisignature.mdx) +for further details on using multisignature accounts with multiple keys. \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx b/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx new file mode 100644 index 00000000..86bd4056 --- /dev/null +++ b/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx @@ -0,0 +1,41 @@ +import { Callout } from 'nextra-theme-docs' + +# Implicit accounts + +An implicit account is the simplest account type. It is derived from a keypair and can be used to authorize certain transactions such as sending and staking tokens, or paying [fees](../fees.mdx). +Implicit accounts have no code attached to them, and can only have one key controlling it. + +## Generating an implicit account +You can generate a new implicit account using the CLI. The new keypair will be added to your `wallet.toml` under the alias you provide. + + +The 'alias' of an account simply provides a convenient way of referring to addresses stored in your `wallet.toml` file by name. +It is not intrinsic to the account. + + +```shell copy +namada wallet gen --alias +``` + +You will be prompted to provide a password, as the keys are stored to disk encrypted. Carefully remember this password; you will need it to sign transactions with your key. +The encryption password is _not_ a part of key generation randomness. + +After generating the new key, a twenty-four word mnemonic will be displayed, which can be used to recover your account. Write this down immediately and +store it safely offline, as it will not be displayed again. + + +WARNING: Keep your mnemonic code and passphrase safe. +Loss of either can result in you being locked out of your accounts with no chance of recovering your funds. + + +##### Derivation path + +Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). + + +The default HD path for Namada is `m/44'/877'/0'/0'/0'`. + + +Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness. + + diff --git a/packages/docs/pages/users/transparent-accounts/multisignature.mdx b/packages/docs/pages/users/transparent-accounts/multisignature.mdx index d4dc5e3d..502a2148 100644 --- a/packages/docs/pages/users/transparent-accounts/multisignature.mdx +++ b/packages/docs/pages/users/transparent-accounts/multisignature.mdx @@ -1,153 +1,137 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' # Multisignature accounts on Namada -Multisignature accounts (multisigs) are accounts on Namada that allow for multiple signers. There are many benefits of having multisigs, including but not limited to +Multisignature accounts (multisigs) are accounts on Namada that allow for multiple signers. There are many benefits to multisignature accounts, including but not limited to: - Increased security - Ability to share wallets - Better recovery options -For this reason, all accounts on Namada are multisignature accounts by default. +For this reason, all established accounts on Namada are multisignature accounts by default. -## Initialising a multisignature account +A multisignature account can be described as an "x of y" account, where x is the 'threshold' or required number of signatures on a transaction +and y is the total number of keys associated with the account. For example, a 3 of 5 multisig will need at least three of the parties to sign any transaction. -Before creating an account, a user must generate at least one cryptographic `key`, that will be used to sign transactions. +## Example: Initialising a multisignature account +Here is the process to generate a 2 of 3 multisig account: -The following method will generate such a key: -```shell -namadaw gen \ ---alias my-key1 -``` -A second key can be generated as well (which will be useful for multisigs): -```shell -namadaw gen \ ---alias my-key2 + +### Create three signing keys +Assuming we have three parties -- Alice, Bob, and Charlie -- on the multisig, they each need to first generate their keypairs. +```bash copy +namadaw gen --alias alice +namadaw gen --alias bob +namadaw gen --alias charlie ``` -Accounts on Namada are initialized through the following method: +### Fund an implicit account for transaction fees +Recall from the section on [established accounts](./established-accounts.mdx) that we will need to provide an implicit account to +sign and to pay the gas costs of the `init-account` transaction. This can be any account you own, whether or not it's party to the multisig. +In this example, Alice will cover the transaction fees and we'll assume she already has sufficient NAM in her account. -**Non-multisig account (single signer)** -```shell -namadac init-account \ ---alias my-multisig-alias \ ---public-keys my-key1 \ ---signing-keys my-key1 -``` +### Init-account +The `init-account` transaction is no different from a typical established account, except for threshold and number of public keys associated. +(In fact, a typical established account is simply a 1 of 1 multisig.) -**Multisig account (at leat 2 signers)** -```shell -namadac init-account \ ---alias my-multisig-alias \ ---public-keys my-key1,my-key2 \ ---signing-keys my-key1,my-key2 \ ---threshold 2 +The `--signing-keys` flag indicates that Alice is signing and paying fees for this transaction. +```bash copy +namadac init-account --alias abc-multisig\ + --public-keys alice,bob,charlie --threshold 2 \ + --signing-keys alice ``` + -## Submitting a multisignature transaction -In order to submit a multisignature transaction, an offline transaction must first be constructed. -### Constructing an offline transaction - -For `v0.23.0` there are certain limitations to the offline transaction construction. Please be weary of any bugs that may arise. - +## Submitting a multisignature transaction +A multisignature transaction requires that an offline transaction first be constructed so that it can be signed by each required party before +being submitted to the chain. -The `--dump-tx` argument allows a user to do this. A folder is required to be specified where the transaction will be dumped. + +### Dump the raw tx +The `--dump-tx` argument will write the transaction to disk. A folder is required to be specified where the transaction will be dumped. -```shell +```bash copy mkdir tx_dumps -``` +namadac transfer --source abc-multisig --target \ + --token nam --amount 2 \ + --signing-keys alice \ + --dump-tx --output-folder-path tx_dumps -This can be done through the following method: -```shell -namadac transfer \ ---source my-multisig-alias \ ---target some-established-account-alias \ ---token NAM \ ---amount 100 \ ---signing-keys my-key1 \ ---dump-tx \ ---output-folder-path tx_dumps +# Example output: +Transaction serialized to tx_dumps/FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx. ``` -What this means is that the transaction has been constructed, and is ready to be signed. - -Within the specified folder, a `.tx` file will be created. This file contains the hexadecimal representation of the transaction bytes. This file can be used to sign the transaction. +### Sign the transaction with two of the three Keys +This command will sign the transaction with Alice's key. Afterwards, repeat the command using Bob's key. -### Signing the transaction - -The next step is to sign the transaction. `my-key1` can sign the transaction through the following method: -```shell +```bash copy +cd tx_dumps namadac sign-tx \ ---tx-path "" \ ---signing-keys my-key1 \ ---owner my-multisig-alias + --tx-path FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx \ + --signing-keys alice \ + --owner abc-multisig ``` - - -Note that any number of `--signing-keys` could sign the transaction in this stage. This will produce multiple signatures, which can be used to submit the transaction. - - - -Which means that the signature has been saved to this file (located in the current directory). - -Let's save this as an alias: -```shell -export SIGNATURE_ONE="offline_signature_FB7246E3FC43F59D8AEEC234EBFDB9DF1AC9BB7B14E536D05A7E2617CA41D4CD_0.tx" +You should have created two new files, one with Alice's signature and one with Bob's: +```bash copy +# contents of tx_dumps directory +FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx +offline_signature_FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3_tpknam1qpnpmq2mpxaag9e0xcczgc0w66pzaxvpnhysjsm8h5tgmajgvunwck67w5j.tx +offline_signature_FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3_tpknam1qqjnwcwpjy09ty4v0z6jwpkr04m3q2h0dgr6j62dfs4g6q6l4dk5yy5we05.tx ``` +To make things easier in the next step, we'll save these filenames to the shell variables `TX`, `SIG1` and `SIG2`. -Ensure to sign the transaction with at least k-of-n keys, where k is the minimum number of signatures required to submit a transaction, and n is the total number of keys. In this example, k=2 and n=2. - -Then let's say this signing produces another signature which we save to the alias `SIGNATURE_TWO`. +### Submit transaction on-chain +Since we have enough signatures to meet the threshold of this account, we can submit the transaction. Note that we need to specify +an account that will pay the transaction fees. -### Submitting the transaction - -The final step is to submit the transaction. This can be done through the following method: -```shell +```bash copy namadac tx \ ---tx-path "tx_dumps/a45ef98a817290d6fc0efbd480bf66647ea8061aee1628ce09b4af4f4eeed1c2.tx" \ ---signatures $SIGNATURE_ONE $SIGNATURE_TWO \ ---owner my-multisig-alias \ ---gas-payer my-key1 + --tx-path $TX + --signatures $SIG1 $SIG2 + --owner abc-multisig + --gas-payer alice ``` - -Note the lack of commas used in the `--signatures` argument. This is because the argument is a list of files, not a list of signatures. -Also note the `tx_dumps` folder. This is the folder where the transaction was dumped to as specified in `--output-folder-path` in the previous step. +Note the lack of commas used in the `--signatures` argument. -## Changing the multisig threshold -It is possible to change the multisig threshold of an account. This can be done through the following method: + + + +## Changing the multisig threshold or associated keys +It is possible to change the multisig threshold of an existing account. This can be done by submitting a valid `update-account` transaction. + +For example, to change the threshold on our multisig to 1: ```shell namadac update-account \ ---address my-multisig-address \ +--address abc-multisig \ +--public-keys alice,bob,charlie \ --threshold 1 \ ---signing-keys my-key1,my-key2 +--signing-keys alice,bob ``` + +Note: you must include both the threshold and the list of public keys to be assosicated with this account, even if there is no change to one of those values. + + + +Updating an account's threshold or public keys requires submitting a valid transaction meeting the existing requirements -- the `update-account` +transaction is no different from any other transaction in that regard. Therefore, you may need to follow the steps described in the previous section to first dump the `update-account` transaction +to a file and collect the required signatures. + +### Querying the threshold and public keys of an account One can check that the threshold has been updated correctly by running: ```shell namadac query-account \ ---owner my-multisig-address +--owner abc-multisig ``` -Which will yield the threshold of 1, together with the two public keys. - -## Changing the public keys of a multisig account -It is possible to change the public keys of a multisig account. This can be done through the following method: -```shell -namadac update-account \ ---address my-multisig-address \ ---public-keys my-key3,my-key4,my-key5 \ ---signing-keys my-key1,my-key2 -``` - -Which will change the public keys of the multisig account from `my-key1` and `my-key2` to the keys `my-key3`, `my-key4` and `my-key5` (assuming they exist in the wallet). - -The public-keys provided to the argument `--public-keys` will become the new signers of the multisig. The list must be a list of public keys, separated by commas, and without spaces. There must be at least 1 public key in the list, and the length of list must be at least the threshold of the multisig account. +Which will list the threshold and all associated public keys of an account. ## A video tutorial -Skip all the boring reading and watch a video tutorial instead: +Skip all the boring reading and watch a video tutorial instead! diff --git a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx index ec63487e..2c486279 100644 --- a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx +++ b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx @@ -5,39 +5,25 @@ import { Callout } from 'nextra-theme-docs' In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/9b67281e359ebff5467cad57c866fbcf91eb80c8/shared/src/ledger/native_vp/multitoken.rs#L30). The validity predicate (VP) checks, in particular, that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block. -### Initialize an established account +### Sending tokens -If you already have a key in your wallet, you can skip this step. Otherwise, [generate a new keypair](../transparent-accounts.mdx#generate-a-keypair) now. +You can send tokens to/from either an implicit or established account. -Then, send a transaction to initialize your new established account and save its address with the alias `establishment`. The `keysha` public key will be written into the account's storage for authorizing future transactions. We also sign this transaction with `keysha`. +This section will cover transfers from one `tnam...` address to another (tranparent transfers). +Transfers to/from a `znam...` address (that is, to/from the [MASP](../shielded-accounts.mdx)) are covered in more detail in the section on [shielded transfers](../shielded-accounts/shielded-transfers.mdx). - -Note the use of the placeholder `keysha` for the key parameter. This is a completely configurable parameter, and should just refer to the alias of the key signing the transaction (that has a positive nam balance). + +For help creating a new account, see the sections on [Generating an implicit account](../transparent-accounts/implicit-accounts.mdx) or [Using the file system wallet](../../users/wallet/file-system-wallet.mdx). -```shell copy -namada client init-account \ - --alias establishment \ - --public-keys keysha \ - --signing-keys keysha \ - --threshold 1 -``` - -Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your wallet with the chosen alias `establishment`. - -This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_user.rs). - -### Send a Payment - To submit a regular token transfer from your account to the `validator-1` address: ```shell copy namada client transfer \ - --source establishment \ - --target validator-1 \ - --token NAM \ - --amount 10 \ - --signing-keys keysha + --source \ + --target \ + --token \ + --amount 10 ``` This command will attempt to find and use the key of the source address to sign the transaction. @@ -47,18 +33,10 @@ This command will attempt to find and use the key of the source address to sign To query token balances for a specific token and/or owner: ```shell copy -namada client balance --token NAM --owner my-new-acc +namada client balance --token --owner ``` For any client command that submits a transaction (`init-account`, `transfer`, `tx`, `update` and [PoS transactions](../../operators/validators/proof-of-stake.mdx)), you can use the `--dry-run-wrapper` flag to simulate the transaction being applied in the block and see what would be the result. - -### See every known addresses' balance - -You can see the token's addresses known by the client when you query all tokens balances: - -```shell copy -namada client balance -``` diff --git a/packages/docs/pages/users/wallet.mdx b/packages/docs/pages/users/wallet.mdx index 2e443513..d6a61ff0 100644 --- a/packages/docs/pages/users/wallet.mdx +++ b/packages/docs/pages/users/wallet.mdx @@ -1,6 +1,6 @@ # Namada Wallet Guide -This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](./transparent-accounts/send-and-receive-nam-tokens.mdx) with NAM tokens on the Namada blockchain. +This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](./transparent-accounts/send-and-receive-nam-tokens.mdx) with tokens on the Namada blockchain. ## A brief introduction to the Namada wallet The purpose of the Namada wallet is to provide a user-interface to store and manage both keys and addresses. @@ -8,7 +8,7 @@ The purpose of the Namada wallet is to provide a user-interface to store and man The wallet simply "remembers" these very large numbers on your behalf. Keys are the fundamental building blocks for accounts on Namada. Keys come in the form of *pairs* (of secret and public key), and can be used to derive the **account address** (first 40 chars of the SHA256 hash of the public key). -To read more about addresses see [An introduction to Namada addresses](./transparent-accounts.mdx). +To read more about addresses, see [An introduction to Namada addresses](./transparent-accounts.mdx). ## The wallet options on Namada diff --git a/packages/docs/pages/users/wallet/file-system-wallet.mdx b/packages/docs/pages/users/wallet/file-system-wallet.mdx index 30509efa..ef48f9e4 100644 --- a/packages/docs/pages/users/wallet/file-system-wallet.mdx +++ b/packages/docs/pages/users/wallet/file-system-wallet.mdx @@ -1,11 +1,64 @@ +import { Callout } from 'nextra-theme-docs' + ## File System Wallet -By default, the Namada Wallet is stored under `.namada/{chain_id}/wallet.toml` where keys are stored encrypted. You can change the default base directory path with `--base-dir` and you can allow the storage of unencrypted keypairs with the flag `--unsafe-dont-encrypt`. +The filesystem wallet stores your encrypted keypairs on disk in your Namada base directory. It is the default wallet option when using the Namada CLI "out of the box." + +By default, the Namada Wallet is contained in the file `/{chain_id}/wallet.toml`, where keys are stored encrypted. You can change the default base directory path with `--base-dir` and you can allow the storage of unencrypted keypairs with the flag `--unsafe-dont-encrypt`. -If the wallet doesn't already exist, it will be created for you as soon as you run a command that tries to access the wallet. A newly created wallet will be pre-loaded with some internal addresses like `pos`, `pos_slash_pool`, `masp` and more. +If the wallet doesn't already exist, it will be created for you as soon as you run a command that tries to access the wallet, or upon [joining a network](../../networks.mdx). +A newly created wallet will be pre-loaded with some internal addresses like `pos`, `pos_slash_pool`, `masp` and more. Currently, the Namada client can load the password via: - **Stdin:** the client will prompt for a password. - **Env variable:** by exporting a ENV variable called `NAMADA_WALLET_PASSWORD` with a value of the actual password. -- **File:** by exporting an ENV variable called `NAMADA_WALLET_PASSWORD_FILE` with a value containing the path to a file containing the password. \ No newline at end of file +- **File:** by exporting an ENV variable called `NAMADA_WALLET_PASSWORD_FILE` with a value containing the path to a file containing the password. + +### Common wallet operations + +The `namadaw` wallet binary handles all key and wallet management functionality. You can use `namadaw --help` to explore +all available wallet commands. + +##### Create a new keypair +This will create a new keypair and save it in your wallet under the provided alias (for convenience). You will be prompted for a +password to encrypt the private key. Afterwards, your mnemonic will be printed to the terminal, which you should safely store in case +you need to restore your key at a later date. + +```bash copy +namadaw gen --alias +``` + + +Write down your mnemonic and store it securely -- this is the only time it will be shown. You can use your mnemonic to recover +your account if you lose access (for example, if your laptop stops working or is stolen). If you are locked out of your account, and +you haven't saved your mnemonic, your funds will be lost forever. + +Also carefully note the encryption password you provided -- you will need to provide it any time you make a transaction. + + +##### List your addresses +Once you've created a new keypair, you'll want to know the address to which you can send tokens. You do this by listing all known +addresses in your wallet and looking for the alias you've just created: + +```bash copy +namadaw list +``` + +or, if you only want to search for a specific address: + +```bash copy +namadaw find --alias +``` + +##### Recover an address from a mnemonic +You can recover an existing key from a mnemonic and add it to your wallet with: +```bash copy +namadaw derive --alias +``` +(You will be prompted to enter the mnemonic). + +#### Using the Pregenesis flag +Normally, you will be expected to join a network before using the wallet; and `namadaw` will throw an error when an existing chain context is not found. +However, there may be times when you want to use `namadaw` prior to joining a chain -- for example, when generating a keypair to +recieve a token allotment in the genesis block of a future chain. In these cases, you can use the flag `--pre-genesis` with your `namadaw` commands. \ No newline at end of file diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 4696c5d1..49e07745 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -1,5 +1,11 @@ +import { Callout } from 'nextra-theme-docs' + ## Hardware Wallet + +The Namada Ledger app is currently in active development and not recommended for use. Information below may be out-of-date. + + Namada's web wallet extension is compatible with the [Ledger](https://www.ledger.com/) hardware. This guide will walk you through the process of setting up your Ledger device to work with Namada. ### Prerequisites diff --git a/packages/docs/pages/users/wallet/web-wallet.mdx b/packages/docs/pages/users/wallet/web-wallet.mdx index 46b0aa88..b3cd7af3 100644 --- a/packages/docs/pages/users/wallet/web-wallet.mdx +++ b/packages/docs/pages/users/wallet/web-wallet.mdx @@ -1,32 +1,74 @@ +import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' + # Web Wallet -## Install -When Namada is in [`mainnet`](../../networks/mainnets.mdx), the web wallet will be available in most browser extension web stores. For now, the user can install it from source by following the instructions below. +## Namada Extension +You can use the [Namada Extension](https://namada.net/extension) to manage your keys within your browser. By connecting the extension with +web apps built for Namada, you can send or recieve tokens, make IBC transfers, or perform other actions such as voting on governance proposals. + +## Installation +The extension is currently available on the [Chrome web store](https://chromewebstore.google.com/detail/namada-extension/hnebcbhjpeejiclgbohcijljcnjdofek), with Firefox support coming soon. + +## Set-up +After adding the extension to Chrome, follow these steps to create a new wallet: + + + +### Click 'Launch Initial Set-up' + +### Add or create keys +You can choose 'Import existing keys' to import an existing wallet from your twelve word mnemonic. You can also use a Ledger hardware wallet -- see [here](./hardware-wallet.mdx) +for further instructions. + +Click 'Create new keys' and verify that you have read and understood the message to proceed. + +### Safely store your mnemonic +You will be shown your recovery mnemonic and asked to confirm that you have written it down. + + +Write your mnemonic down and store it safely offline. + +It will allow you to recover your account. Without it, you risk losing access to your funds forever. + + +### Create and safely store your password +You will also be asked to create a password for the extension. Write down this password -- you will need to enter it regularly when using the extension. + + +If you lose your password, you will lose access to the extension. + +Remember: there's no 'recover password with email' option! + + +### Complete! +Your wallet is ready to use. + + +## Using the Extension +The extension itself only provides key management functionality. To send or receive tokens, you will need to navigate to a compatible +web app (such as [namada-interface](https://github.com/anoma/namada-interface)) and connect the extension to the site. + +Here's how to use the extension with Namada-Interface: + + +### Set the network in the extension +Open the extension and click the 'gear' icon in the top right, then select 'Network'. -### Installing from source (for development and experiment purposes) +Enter a valid chain-id and rpc url for the chain you wish to transact on, and click 'Submit'. -#### Connect to a testnet or run a local node -1. Follow the instructions for the [testnets](../../networks/testnets.mdx) to connect to a testnet or [set up a local node](../../operators/networks/local-network.mdx). -2. Figure out where the base directory is stored and save its location as a variable such as `export BASE_DIR=`. - You can follow [these docs](../../networks/testnets/migrating-testnets.mdx) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. -3. You will need to edit the CometBFT config in order to allow the web wallet to connect to your node. - The CometBFT config will be located in `$BASE_DIR/$CHAIN_ID/cometbft/config/config.toml`. You will need to change the `cors_allowed_origins` field to `["*"]`. You can do this by running - ```shell copy - sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' \ - $BASE_DIR/$CHAIN_ID/cometbft/config/config.toml - ``` +### Navigate to the Namada-interface site +The Namada-interface for the [Campfire testnet](../../networks/testnets/campfire.mdx) is hosted at [https://interface.luminara.icu](https://interface.luminara.icu). After mainnet +has launched, a list of hosted Interfaces will be found [here](../../networks/mainnets.mdx). -#### Setting up the extension -1. Clone the [namada-interface repository](https://github.com/anoma/namada-interface). -2. Follow the installation instructions in `README.md`. -3. `cd` into the `namada-interface/apps/extension` directory and run `yarn start:chrome`. This will build the extension and place it in the `namada-interface/apps/extension/build` directory. It also starts the dev server which will watch for changes. -4. `cd` into the `namada-interface/apps/namada-interface` directory and run `yarn dev:local` in order to launch a local instance of the web wallet. -4. Add the extension to the browser. For example, in Chrome, you can go to `chrome://extensions/` and click `Load unpacked` and select the `namada-interface/apps/extension/build/chrome/` folder. +### Connect the extension +Click 'Connect to Namada Extension' and approve when prompted. You should see your wallet balance displayed on the page. -## Receiving tokens -You can show the address of any account by pressing the `Receive` button in the initial view under the "Total Balances" tab. You can copy the address by clicking the copy icon next to the address. -This will also display a QR code that can be scanned by a mobile wallet. +### Interact +Once connected, you can use the Interface to make transfers or stake with a validator (Note: some functionality may be missing on testnet). +Whenever you submit a transaction to the chain, you will be prompted to enter your password to allow the extension to sign using your private key. -## Sending Transactions +### Disconnect +If you wish to disconnect (remove permissions) from a site, you can do so in the Settings menu of the extension, under 'Connected Sites'. -In order to send transactions, you can press the `Send` button in the initial view under the "Total Balances" tab. This will open a modal that will allow you to send tokens to any account, from any account in your wallet that has a positive balance. + \ No newline at end of file