diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png new file mode 100644 index 00000000000..ad81aace478 Binary files /dev/null and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png new file mode 100644 index 00000000000..dbb5c4c6fee Binary files /dev/null and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png new file mode 100644 index 00000000000..4031fac3383 Binary files /dev/null and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif new file mode 100644 index 00000000000..6a718867da9 Binary files /dev/null and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png new file mode 100644 index 00000000000..ba231aa252e Binary files /dev/null and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png index 3754ccfe88e..61e1936648f 100644 Binary files a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png and b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards-source.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards-source.png deleted file mode 100644 index 65e0f880bc9..00000000000 Binary files a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards-source.png and /dev/null differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards.png deleted file mode 100644 index dca226c3ec9..00000000000 Binary files a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards.png and /dev/null differ diff --git a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb.png b/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb.png deleted file mode 100644 index 3ba9035889d..00000000000 Binary files a/docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb.png and /dev/null differ diff --git a/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub-portal-loop.png b/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub-portal-loop.png new file mode 100644 index 00000000000..fb3455f4a55 Binary files /dev/null and b/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub-portal-loop.png differ diff --git a/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png b/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png new file mode 100644 index 00000000000..18d611c26a0 Binary files /dev/null and b/docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png differ diff --git a/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-default.png b/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-default.png new file mode 100644 index 00000000000..f275e71d18e Binary files /dev/null and b/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-default.png differ diff --git a/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-help.png b/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-help.png new file mode 100644 index 00000000000..a2a4a5182d6 Binary files /dev/null and b/docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-help.png differ diff --git a/docs/assets/getting-started/local-setup/local-setup/gnodev.gif b/docs/assets/getting-started/local-setup/local-setup/gnodev.gif new file mode 100644 index 00000000000..6a718867da9 Binary files /dev/null and b/docs/assets/getting-started/local-setup/local-setup/gnodev.gif differ diff --git a/docs/getting-started/local-setup/browsing-gno-source-code.md b/docs/getting-started/local-setup/browsing-gno-source-code.md deleted file mode 100644 index ad3e091ea8b..00000000000 --- a/docs/getting-started/local-setup/browsing-gno-source-code.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: browsing-gno-source-code ---- - -# Browsing Gno Source Code - -## Overview - -In this tutorial, you will learn how to browse deployed Gno [Realms](../../concepts/realms.md) -and [Packages](../../concepts/packages.md). Additionally, you will understand how the `Render` method is utilized -to achieve Realm state visibility. - -## Prerequisites - -- **`gnoweb` set up. Reference the [Local Setup](local-setup.md#3-installing-other-gno-tools) guide for steps** - -## 1. Start the local chain - -In order for `gnoweb` to fetch realm and package source code, it needs to connect a running Gno node. For a better -overview on running a local node, please reference the [Starting a Local Chain](setting-up-a-local-chain.md) guide. - -In this guide, we will start a local node with the default configuration. Navigate to the `gno.land` sub-folder and run: - -```bash -gnoland start -``` - -## 2. Start `gnoweb` - -Now that the chain is running, we can start the `gnoweb` tool: - -```bash -gnoweb -``` - -:::info Different JSON-RPC URL - -In case you are running a node on a different JSON-RPC URL from the default one (`http://127.0.0.1:26657`), -you can specify the remote URL with the `gnoweb` flag named `--remote` - -::: - -We should be able to access the website locally on http://127.0.0.1:8888/. - -![gnoweb screen](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb.png) - -## 3. Browse Package source code - -Packages in Gno.land usually have names resembling `gno.land/p/`. Since packages do not contain state, we can only -view their source code on-chain. To learn more about Packages, please check out -the [Packages](../../concepts/packages.md) explanation document. - -Using `gnoweb`, we can browse the source code in our browser. -For example, the `avl` package is deployed at `gno.land/p/demo/avl`. - -To access the source code of the `avl` package, we can append the `/p/demo/avl` to our browser URL (from the homepage). - -The final URL for the `avl` package source could be viewable at http://127.0.0.1:8888/p/demo/avl, if we followed -default setup params, as we did in this guide. - -![gnoweb avl](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png) - -From here, we can open any source code file of the deployed on-chain package and inspect its API. - -## 4. Browse Realm source code - -In contrast to Packages, Realms in Gno.land usually have names resembling `gno.land/r/`. - -Realms _do_ contain state, and in addition to being able to view their source code on-chain, users can also view their -internal state representation in the form of the `Render()` output. To learn more about Realms, please -check out the [Realms](../../concepts/realms.md) explanation document. - -Using `gnoweb`, we can browse the Realm `Render()` method output and source code in our browser. -For example, the `boards` Realm is deployed at `gno.land/r/demo/boards`. - -To view the internal Realm state of the `boards` package, we can append the `/r/demo/boards` to our browser URL (from -the homepage). - -The final URL for the `boards` Realm internal state could be viewable at http://127.0.0.1:8888/r/demo/boards, if we -followed -default setup params, as we did in this guide. - -![gnoweb boards](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards.png) - -:::info Render() is not required - -Internal Realm state does not have to be exposed through the `Render()` method of the realm, as it is -not a requirement for deploying a Realm. - -::: - -Additionally, to view the source code for the realm, we simply need to append the `/` to the full realm path: - -http://127.0.0.1:8888/r/demo/boards/ - -![gnoweb boards source](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards-source.png) diff --git a/docs/getting-started/local-setup/browsing-gnoland.md b/docs/getting-started/local-setup/browsing-gnoland.md new file mode 100644 index 00000000000..300b7e0e035 --- /dev/null +++ b/docs/getting-started/local-setup/browsing-gnoland.md @@ -0,0 +1,104 @@ +--- +id: browsing-gnoland +--- + +# Browsing Gno.land + +## Overview +In this tutorial, you will learn how to browse [realms](../../concepts/realms.md) +and [packages](../../concepts/packages.md) deployed to a Gno.land chain. +You will understand how the `Render` method is utilized to achieve realm state +visibility, and you will learn how to easily access realm APIs. + +## Prerequisites +- **`gnodev` installed.** Reference the +[Local Setup](installation.md#3-installing-other-gno-tools) guide for steps + +## 1. Start `gnodev` +To browse Gno source code, we need two components: +- a running `gno.land` node, +- a gno.land source code viewer, like `gnoweb` + +Luckily, `gnodev` comes prepackaged with both. To start, simply run `gnodev` in +your terminal. + +`gnodev` will start an in-memory node, as well as a `gnoweb` server: + +![gnodev](../../assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif) + +`gnodev` remembers the folder where it was installed, and loads the +[`examples/`](https://github.com/gnolang/gno/tree/master/examples) subfolder by default. By visiting +[`http://localhost:8888`](http://localhost:8888), you will be able to see the +gno.land home page: + +![homepage](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png) + +## 2. Browsing Gno.land + +### Package source code +Packages in Gno.land usually have names resembling `gno.land/p/`. Since +packages do not contain state, only their source code can be viewed on-chain. To +learn more about packages, check out the [Packages](../../concepts/packages.md) +concept page. + +Let's take a specific example: the `avl` package, deployed at `gno.land/p/demo/avl`. +To access the source code of the `avl` package, we can append the `/p/demo/avl` +to our browser URL (from the homepage). + +The final URL for the `avl` package source could be viewable at +[`http://127.0.0.1:8888/p/demo/avl`](http://127.0.0.1:8888/p/demo/avl), +if we followed default setup params, as we did in this guide. + +![gnoweb avl](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png) + +From here, we can open any source code file of the deployed on-chain package +and inspect its API. + +### Realm source code & state +In contrast to Packages, Realms in Gno.land usually have names resembling +`gno.land/r/`. + +Realms _do_ contain state, and in addition to being able to view their source +code on-chain, users can also view their internal state representation in the +form of the `Render()` output. To learn more about realms, please check out the +[Realms](../../concepts/realms.md) concept page. + +We can browse the realm `Render()` method output and source code in our browser. +For example, the `gnoland/blog` realm is deployed at `gno.land/r/gnoland/blog`. + +To view the internal realm state of the `blog` realm, we can append the +`/r/gnoland/blog` to our browser URL (from the homepage). + +The final URL for the `blog` realm internal state could be viewable at +[`http://127.0.0.1:8888/r/gnoland/blog`](http://127.0.0.1:8888/r/gnoland/blog), +if we followed default setup params, as we did in this guide. + +![blog_render](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png) + +:::info Render() is not required +Internal realm state does not have to be exposed through the `Render()` method +of the realm, as it is not a requirement for deploying a Realm. +::: + +Additionally, to view the source code for the realm, we have two options: +- append `/` to the full realm path - [`http://127.0.0.1:8888/r/gnoland/blog/`](http://127.0.0.1:8888/r/gnoland/blog/) +- click on the `[source]` button in the top-right corner + +![blog_source](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png) + +Finally, the `[help]` button takes us to the realm help page, where you will +be able to see the user-facing API of the realm. + +![blog_help](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png) + +This page will allow you to easily generate `gnokey` commands for interacting +with the realm in question. + +## Conclusion + +That's it 🎉 + +You have successfully inspected the source code of a package and realm, and seen +the on-chain state of the blog app. You have also learned about the `[help]` page +that `gnoweb` provides. + diff --git a/docs/getting-started/local-setup/installation.md b/docs/getting-started/local-setup/installation.md new file mode 100644 index 00000000000..fe96998e239 --- /dev/null +++ b/docs/getting-started/local-setup/installation.md @@ -0,0 +1,110 @@ +--- +id: installation +--- + +# Installation + +## Overview +In this tutorial, you will learn how to set up the Gno development environment +locally, so you can get up and running writing Gno code. You will download and +install all the necessary tooling, and validate that it is correctly configured +to run on your machine. + +## Prerequisites +- **Git** +- **`make` (for running Makefiles)** +- **Go 1.19+** +- **Go Environment Setup**: + - Make sure `$GOPATH` is well-defined, and `$GOPATH/bin` is added to your `$PATH` variable. + - To do this, you can add the following line to your `.bashrc`, `.zshrc` or other config file: +``` +export GOPATH=$HOME/go +export PATH=$GOPATH/bin:$PATH +``` + +## 1. Cloning the repository +To get started with a local Gno.land development environment, you must clone the +GitHub repository somewhere on disk: + +```bash +git clone https://github.com/gnolang/gno.git +``` + +## 2. Installing the required tools + +There are three tools that should be used for getting started with Gno development: +- `gno` - the GnoVM binary +- `gnodev` - the Gno [development helper](../../gno-tooling/cli/gnodev.md) +- `gnokey` - the Gno [keypair manager](working-with-key-pairs.md) + +To install all three tools, simply run the following in the root of the repo: +```bash +make install +``` + +## 3. Verifying installation + +### `gno` +`gno` provides ample functionality to the user, among which is running, +transpiling, testing and building `.gno` files. Read more +about `gnokey` [here](../../gno-tooling/cli/gno.md). + +To verify the `gno` binary is installed system-wide, you can run: + +```bash +gno --help +``` + +You should get the help output from the command: + +![gno help](../../assets/getting-started/local-setup/local-setup/gno-help.gif) + +Alternatively, if you don't want to have the binary callable system-wide, you +can run the binary directly: + +```bash +cd gnovm +go run ./cmd/gno --help +``` + +### `gnodev` +`gnodev` is the go-to Gno development helper tool - it comes with a built in +Gno.land node, a `gnoweb` server to display the state of your smart contracts +(realms), and a watcher system to actively track changes in your code. Read more +about `gnodev` [here](../../gno-tooling/cli/gnodev.md). + +To verify that the `gnodev` binary is installed system-wide, you can run: + +```bash +gnodev +``` + +You should get the following output: +![gnodev](../../assets/getting-started/local-setup/local-setup/gnodev.gif) + + +### `gnokey` + +`gnokey` is the Gno.land keypair management CLI tool. It allows you to create +keypairs, sign transactions, and broadcast them to Gno.land chains. Read more +about `gnokey` [here](../../gno-tooling/cli/gnokey.md). + +To verify that the `gnokey` binary is installed system-wide, you can run: + +```bash +gnokey --help +``` + +You should get the help output from the command: + +![gnokey help](../../assets/getting-started/local-setup/local-setup/gnokey-help.gif) + +## Conclusion + +That's it 🎉 + +You have successfully built out and installed the necessary tools for Gno +development! + +In further documents, you will gain a better understanding on how they are used +to make Gno work. diff --git a/docs/getting-started/local-setup/interacting-with-gnoland.md b/docs/getting-started/local-setup/interacting-with-gnoland.md new file mode 100644 index 00000000000..adc7788dcaf --- /dev/null +++ b/docs/getting-started/local-setup/interacting-with-gnoland.md @@ -0,0 +1,97 @@ +--- +id: interacting-with-gnoland +--- + +# Interacting with Gno.land code + +## Overview +In this tutorial, you will learn how to interact with Gno.land code. +You will understand how to use your keypair to send transactions to realms +and packages, send native coins, and more. + +## Prerequisites +- **`gnokey` installed.** Reference the +[Local Setup](installation.md#3-installing-other-gno-tools) guide for steps +- **A keypair in `gnokey`.** Reference the +[Working with Key Pairs](working-with-key-pairs.md#adding-a-private-key-using-a-mnemonic) guide for steps + +## 1. Get testnet GNOTs +For interacting with any Gno.land chain, you will need a certain amount of GNOTs +to pay gas fees with. + +For this example, we will use the [Portal Loop](../../concepts/testnets.md#portal-loop) +testnet. We can access the Portal Loop faucet through the +[Gno Faucet Hub](https://faucet.gno.land), or by accessing the faucet directly at +[gno.land/faucet](https://gno.land/faucet). + +![faucet-hub](../../assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png) + +After choosing "Gno Portal Loop", you will get a prompt to input your address, +select the amount of testnet GNOT you want to receive, and solve a captcha: + +![faucet-hub-portal-loop](../../assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub-portal-loop.png) + +After inputting your address and solving the captcha, you can check if you have received funds with the +following `gnokey` command: + +```bash +gnokey query bank/balances/ --remote "https://rpc.gno.land:443" +``` + +If the faucet request was successful, you should see something similar to the +following: + +``` +❯ gnokey query bank/balances/ --remote "https://rpc.gno.land:443" +height: 0 +data: "10000000ugnot" +``` + +## 2. Visit a realm +For this example, we will use the [Userbook realm](https://gno.land/r/demo/userbook). +The Userbook realm is a simple app that allows users to sign up, and keeps track +of when they signed up. It also displays the currently signed-up users and the block +height at which they have signed up. + +![userbook-default](../../assets/getting-started/local-setup/interacting-with-gnoland/userbook-default.png) + +> Note: block heights are not correct because of the way the Portal Loop testnet +> works. +> Read more [here](../../concepts/portal-loop.md). + +To see what functions are available to call on the Userbook realm, click +the `[help]` button. + +![userbook-help](../../assets/getting-started/local-setup/interacting-with-gnoland/userbook-help.png) + +By choosing one of the two `gnokey` commands and inputting your address +(or keypair name) in the top bar, you will have a ready command to paste into your +terminal. For example, the following command will call the `SignUp` function with the +keypair `MyKeypair`: + +``` +gnokey maketx call \ +-pkgpath "gno.land/r/demo/userbook" \ +-func "SignUp" \ +-gas-fee 1000000ugnot \ +-gas-wanted 2000000 \ +-send "" \ +-broadcast \ +-chainid "portal-loop" \ +-remote "https://rpc.gno.land:443" \ +MyKeypair +``` + +To see what each option and flag in this command does, read the `gnokey` +[reference page](../../gno-tooling/cli/gnokey.md). + +## Conclusion + +That's it! Congratulations on executing your first transaction on a Gno network! 🎉 + +If the previous transaction was successful, you should be able +to see your address on the main page of the Userbook realm. + +This concludes the "Local Setup" tutorial. For next steps, see the +[How-to guides section](../../how-to-guides/how-to-guides.md), where you will +learn how to write your first realm, package, and much more. \ No newline at end of file diff --git a/docs/getting-started/local-setup/local-setup.md b/docs/getting-started/local-setup/local-setup.md index ac486ca269c..669528e61d3 100644 --- a/docs/getting-started/local-setup/local-setup.md +++ b/docs/getting-started/local-setup/local-setup.md @@ -2,117 +2,7 @@ id: local-setup --- -# Local Setup - -## Overview - -In this tutorial, you will learn how to set up the Gno development environment locally, so you -can get up and running writing Gno code. You will download and install all the necessary tooling, -and validate that they are correctly configured to run on your machine. - -## Prerequisites - -- **Git** -- **`make` (for running Makefiles)** -- **Go 19+** -- **Go Environment Setup**: - - Make sure `$GOPATH` is well-defined, and `$GOPATH/bin` is added to your `$PATH` variable. - - To do this, you can add the following line to your `.bashrc`, `.zshrc` or other config file: -``` -export GOPATH=$HOME/go -export PATH=$GOPATH/bin:$PATH -``` - -## 1. Cloning the repository - -To get started with a local Gno.land development environment, you must clone the GitHub repository -somewhere on disk: - -```bash -git clone https://github.com/gnolang/gno.git -``` - -## 2. Installing the `gno` development toolkit - -Next, we are going to build and install the `gno` development toolkit. -`gno` provides ample functionality to the user, among which is running, transpiling, testing and building `.gno` files. - -To install the toolkit, navigate to the `gnovm` folder from the repository root, and run the `build` make directive: - -```bash -cd gnovm -make build -``` - -This will build out the necessary `gno` binary into the `gnovm/cmd` sub-folder: - -![gno tool build](../../assets/getting-started/local-setup/local-setup/make-build-gnovm.gif) - -Next, to make development easier, we need to make the binary available system-wide. -From the same `gnovm` sub-folder, you can run: - -```bash -make install -``` - -To verify the `gno` binary is installed system-wide, you can run: - -```bash -gno --help -``` - -You should get the help output from the command: - -![gno help](../../assets/getting-started/local-setup/local-setup/gno-help.gif) - -Alternatively, if you don't want to have the binary callable system-wide, you can run the binary directly: - -```bash -go run ./cmd/gno --help -``` - -## 3. Installing other `gno` tools - -The next step is to install several other tools that are required for the Gno development environment, like - -- `gnoland` - the Gno [blockchain node](setting-up-a-local-chain.md) -- `gnokey` - the Gno [private key manager](working-with-key-pairs.md) -- `gnoweb` - the Gno [source code viewer](browsing-gno-source-code.md) -- `gnofaucet` - the Gno [native currency faucet](../../gno-tooling/cli/faucet/faucet.md) - -To build these tools, from the root directory navigate to the `gno.land` sub-folder, and run the `build` make -directive: - -```bash -cd gno.land -make build -``` - -This will build out the necessary binaries into the `gno.land/cmd` sub-folder: - -![gno tools build](../../assets/getting-started/local-setup/local-setup/make-build-gnoland.gif) - -Same as with the `gno` tool, we can make these binaries available system-wide. -From the same `gno.land` sub-folder, you can run: - -```bash -make install -``` - -To verify that, for example, the `gnokey` binary is installed system-wide, you can run: - -```bash -gnokey --help -``` - -You should get the help output from the command: - -![gnokey help](../../assets/getting-started/local-setup/local-setup/gnokey-help.gif) - -## Conclusion - -That's it 🎉 - -You have successfully built out and installed the necessary tools for Gno development! - -In further documents, you will gain a better understanding on how they are used to make Gno work. +# Local setup +This section will show you how to set up a local environment for Gno development. +It includes instructions for installation, setting up a Gno.land keypair, +browsing Gno source code, and more. \ No newline at end of file diff --git a/docs/getting-started/local-setup/premining-balances.md b/docs/getting-started/local-setup/premining-balances.md index 7117f8d5cdd..b7f2139f508 100644 --- a/docs/getting-started/local-setup/premining-balances.md +++ b/docs/getting-started/local-setup/premining-balances.md @@ -12,7 +12,7 @@ Additionally, you will understand how to query the account balance after you pre Premining balance is the process of making sure some accounts (addresses) have specific funds when the chain initially launches. In the context of local chain deployments, premine balances are used to ensure the user accounts (developers) have ample funds to interact with the chain and facilitate contract deployments. - + ## Prerequisites - **`gnoland` and `gnokey` set up. Reference the [Installation](local-setup.md#3-installing-other-gno-tools) guide diff --git a/docs/getting-started/local-setup/working-with-key-pairs.md b/docs/getting-started/local-setup/working-with-key-pairs.md index 3e47b6c4a2c..ec47a7d42ab 100644 --- a/docs/getting-started/local-setup/working-with-key-pairs.md +++ b/docs/getting-started/local-setup/working-with-key-pairs.md @@ -5,20 +5,21 @@ id: working-with-key-pairs # Working with Key Pairs ## Overview - -In this tutorial, you will learn how to manage private user keys, which are required for interacting with the Gno.land -blockchain. You will understand what mnemonics are, how they are used, and how you can make interaction seamless with +In this tutorial, you will learn how to manage private user keys, which are +required for interacting with the Gno.land blockchain. You will understand what +mnemonics are, how they are used, and how you can make interaction seamless with Gno. ## Prerequisites - -- **`gnokey` set up. Reference the [Local Setup](local-setup.md#3-installing-other-gno-tools) guide for steps** +- **`gnokey` installed.** Reference the +[Local Setup](installation.md#2-installing-the-required-tools-) guide for steps ## Listing available keys +`gnokey` works by creating a local directory in the filesystem for storing +(encrypted!) user private keys. -`gnokey` works by creating a local directory in the filesystem for storing (encrypted!) user private keys. - -You can find this repository by checking the value of the `--home` flag when running the following command: +You can find this repository by checking the value of the `--home` flag when +running the following command: ```bash gnokey --help @@ -56,7 +57,8 @@ FLAGS In this example, the directory where `gnokey` will store working data is `/Users/zmilos/Library/Application Support/gno`. -Keep note of this directory, in case you need to reset the keystore, or migrate it for some reason. +Keep note of this directory, in case you need to reset the keystore, or migrate +it for some reason. You can provide a specific `gnokey` working directory using the `--home` flag. To list keys currently present in the keystore, we can run: @@ -65,8 +67,10 @@ To list keys currently present in the keystore, we can run: gnokey list ``` -In case there are no keys present in the keystore, the command will simply return an empty response. -Otherwise, it will return the list of keys and their accompanying metadata as a list, for example: +In case there are no keys present in the keystore, the command will simply +return an empty response. +Otherwise, it will return the list of keys and their accompanying metadata as a +list, for example: ```bash 0. Manfred (local) - addr: g15uk9d6feap7z078ttcnwc94k60ullrvhmynxjt pub: gpub1pgfj7ard9eg82cjtv4u4xetrwqer2dntxyfzxz3pqvn87u43scec4zfgn4la3nt237nehzydzayqxe43fx63lq6rty9c5almet4, path: @@ -79,7 +83,8 @@ The key response consists of a few pieces of information: - The derived address (`addr`) - The public key (`pub`) -Using these pieces of information, we can interact with Gno.land tools and write blockchain applications. +Using these pieces of information, we can interact with Gno.land tools and write +blockchain applications. ## Generating a BIP39 mnemonic @@ -95,8 +100,8 @@ gnokey generate ![gnokey generate](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-generate.gif) ## Adding a random private key - -If we wanted to add a new private key to the keystore, we can run the following command: +If we wanted to add a new private key to the keystore, we can run the following +command: ```bash gnokey add MyKey @@ -104,14 +109,16 @@ gnokey add MyKey Of course, you can replace `MyKey` with whatever name you want for your key. -The `gnokey` tool will prompt you to enter a password to encrypt the key on disk (don't forget this!). -After you enter the password, the `gnokey` tool will add the key to the keystore, and return the accompanying [mnemonic -phrase](https://en.bitcoin.it/wiki/Seed_phrase), which you should remember somewhere if you want to recover the key at a -future point in time. +The `gnokey` tool will prompt you to enter a password to encrypt the key on disk +(don't forget this!). +After you enter the password, the `gnokey` tool will add the key to the keystore, +and return the accompanying [mnemonic phrase](https://en.bitcoin.it/wiki/Seed_phrase), which you should remember +somewhere if you want to recover the key at a future point in time. ![gnokey add random](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-add-random.gif) -You can check that the key was indeed added to the keystore, by listing available keys: +You can check that the key was indeed added to the keystore, by listing available +keys: ```bash gnokey list @@ -120,9 +127,8 @@ gnokey list ![gnokey list](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-list.gif) ## Adding a private key using a mnemonic - -To add a private key to the `gnokey` keystore [using an existing mnemonic](#generating-a-bip39-mnemonic), we can run the -following command with the +To add a private key to the `gnokey` keystore [using an existing mnemonic](#generating-a-bip39-mnemonic), +we can run the following command with the `--recover` flag: ```bash @@ -131,14 +137,14 @@ gnokey add --recover MyKey Of course, you can replace `MyKey` with whatever name you want for your key. -By following the prompts to encrypt the key on disk, and providing a BIP39 mnemonic, we can successfully add -the key to the keystore. +By following the prompts to encrypt the key on disk, and providing a BIP39 +mnemonic, we can successfully add the key to the keystore. ![gnokey add mnemonic](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-add-mnemonic.gif) ## Deleting a private key - -To delete a private key from the `gnokey` keystore, we need to know the name or address of the key to remove. +To delete a private key from the `gnokey` keystore, we need to know the name or +address of the key to remove. After we have this information, we can run the following command: ```bash @@ -148,12 +154,12 @@ gnokey delete MyKey After entering the key decryption password, the key will be deleted from the keystore. :::caution Recovering a private key -In case you delete or lose access to your private key in the `gnokey` keystore, you -can recover it using the key's mnemonic, or by importing it if it was exported at a previous point in time. +In case you delete or lose access to your private key in the `gnokey` keystore, +you can recover it using the key's mnemonic, or by importing it if it was exported +at a previous point in time. ::: ## Exporting a private key - Private keys stored in the `gnokey` keystore can be exported to a desired place on the user's filesystem. @@ -165,25 +171,28 @@ To export a key from the keystore, you can run: gnokey export -key MyKey -output-path ~/Work/gno-key.asc ``` -Follow the prompts presented in the terminal. Namely, you will be asked to decrypt the key in the keystore, -and later to encrypt the armor file on disk. It is worth noting that you can also export unencrypted key armor, using -the `--unsafe` flag. +Follow the prompts presented in the terminal. Namely, you will be asked to +decrypt the key in the keystore, and later to encrypt the armor file on disk. +It is worth noting that you can also export unencrypted key armor, using the `--unsafe` flag. ![gnokey export](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-export.gif) ## Importing a private key +If you have an exported private key file, you can import it into `gnokey` fairly +easily. -If you have an exported private key file, you can import it into `gnokey` fairly easily. - -For example, if the key is exported at `~/Work/gno-key.asc`, you can run the following command: +For example, if the key is exported at `~/Work/gno-key.asc`, you can run the +following command: ```bash gnokey import -armor-path ~/Work/gno-key.asc -name ImportedKey ``` -You will be asked to decrypt the encrypted private key armor on disk (if it is encrypted, if not, use the `--unsafe` -flag), and then to provide an encryption password for storing the key in the keystore. +You will be asked to decrypt the encrypted private key armor on disk +(if it is encrypted, if not, use the `--unsafe` flag), and then to provide an +encryption password for storing the key in the keystore. -After executing the previous command, the `gnokey` keystore will have imported `ImportedKey`. +After executing the previous command, the `gnokey` keystore will have imported +`ImportedKey`. ![gnokey import](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-import.gif)