Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

docs: add Using gnokey tutorial #2226

Merged
merged 112 commits into from
Sep 5, 2024
Merged
Show file tree
Hide file tree
Changes from 91 commits
Commits
Show all changes
112 commits
Select commit Hold shift + click to select a range
a8fcc88
save
leohhhn May 22, 2024
a7aa0cc
add slug
leohhhn May 28, 2024
140bfcd
save
leohhhn May 28, 2024
11c5e07
Merge branch 'master' into docs/gnokey-tutorial
leohhhn May 28, 2024
a282249
Merge branch 'master' into docs/gnokey-tutorial
leohhhn May 28, 2024
301beb8
save
leohhhn May 28, 2024
e4a4062
save
leohhhn May 28, 2024
c3b49d2
save
leohhhn May 28, 2024
aca03da
save
leohhhn May 28, 2024
19e0300
save
leohhhn May 28, 2024
74a8329
queries
leohhhn May 28, 2024
bbe9222
try msgrun
leohhhn Jun 2, 2024
c9a2f58
rm example
leohhhn Jun 2, 2024
e9a4301
save
leohhhn Jun 2, 2024
00ea85c
add airgapped
leohhhn Jun 3, 2024
ffbd8ba
fixups
leohhhn Jun 3, 2024
bf55d87
typos
leohhhn Jun 3, 2024
3774931
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 3, 2024
43fa0d2
fix maketx run
leohhhn Jun 3, 2024
df25d49
typos and fixes
leohhhn Jun 4, 2024
e12e4fe
add run examples
leohhhn Jun 4, 2024
2665745
capitalize call
leohhhn Jun 4, 2024
59c1213
update working with keypairs
leohhhn Jun 4, 2024
516db4c
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 4, 2024
e763f61
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 5, 2024
1ec8fd1
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 5, 2024
36fe867
remove newline
leohhhn Jun 7, 2024
c90cf3c
update headers
leohhhn Jun 7, 2024
896c04b
verify & conclusion
leohhhn Jun 7, 2024
7403856
add mention of hex
leohhhn Jun 7, 2024
0acc1f6
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 7, 2024
afeaeb6
fix indentation
leohhhn Jun 10, 2024
ba263ff
fix indentation
leohhhn Jun 10, 2024
7972283
fix indentation
leohhhn Jun 10, 2024
3cd4a45
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 11, 2024
2ecb65f
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
445a8c1
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
7d3d910
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
1f2b132
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
3a432b0
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
a9c37d6
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
a27d96e
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
b4f0278
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
e154e5c
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
35a3743
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
4700594
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
1d9197c
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
7f69da9
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
b23328d
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
bb8360e
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
ec443ec
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
85d533b
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
27980c1
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
a5a60ca
Update docs/getting-started/using-gnokey.md
leohhhn Jun 12, 2024
112b4b0
fix
leohhhn Jun 12, 2024
09b1fce
fix
leohhhn Jun 12, 2024
844f301
imperative
leohhhn Jun 12, 2024
d071774
phrasing
leohhhn Jun 12, 2024
1efa804
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 21, 2024
f1ebec1
move files
leohhhn Jun 21, 2024
d8c551b
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jun 30, 2024
4288ff5
split files
leohhhn Jul 1, 2024
ce94206
save
leohhhn Jul 3, 2024
25737db
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Jul 6, 2024
fbcf3ce
update creating a keypair
leohhhn Jul 19, 2024
dec53e7
update creating a keypair, others
leohhhn Jul 22, 2024
9a18c62
update front page, remove prerequisites from working with keypairs
leohhhn Aug 9, 2024
0b5d04a
update installation, getting started
leohhhn Aug 27, 2024
b144b70
add line to intro, add prerequisites
leohhhn Aug 27, 2024
401489d
Gno.land > gno.land
leohhhn Aug 27, 2024
d6fa301
replace gnodev with PL
leohhhn Aug 27, 2024
f805189
replace chainid & remote
leohhhn Aug 27, 2024
de91b1c
update airgap
leohhhn Aug 27, 2024
78187b0
update chainid explanation
leohhhn Aug 27, 2024
d1bb488
rephrase
leohhhn Aug 27, 2024
51a2b3b
update airgap
leohhhn Aug 27, 2024
824b270
update querying
leohhhn Aug 27, 2024
990f99f
add tx hashes, make generic paths
leohhhn Aug 27, 2024
baf9a87
update imports
leohhhn Aug 27, 2024
51d7e29
update conclusion
leohhhn Aug 27, 2024
0b57a45
rm cli
leohhhn Aug 27, 2024
76ce28f
update conclusion
leohhhn Aug 27, 2024
a93f069
fixups
leohhhn Aug 27, 2024
8351ee2
fixup
leohhhn Aug 27, 2024
c8be1eb
add styling
leohhhn Aug 27, 2024
78bb5a6
Merge branch 'refs/heads/master' into docs/gnokey-tutorial
leohhhn Aug 27, 2024
0df3101
make build
leohhhn Aug 27, 2024
8b027df
update links
leohhhn Aug 27, 2024
7eb0465
update link
leohhhn Aug 27, 2024
187a28a
add conclusion
leohhhn Aug 28, 2024
05de5b1
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Sep 3, 2024
8c72133
unique id
leohhhn Sep 3, 2024
76e968d
Update docs/getting-started/local-setup/creating-a-keypair.md
leohhhn Sep 3, 2024
e16f684
Update docs/getting-started/local-setup/interacting-with-gnoland.md
leohhhn Sep 3, 2024
86be7d8
Apply suggestions from code review
leohhhn Sep 3, 2024
ccac75a
add links
leohhhn Sep 3, 2024
f96159f
files
leohhhn Sep 3, 2024
6c1a50d
Update docs/gno-tooling/cli/gnokey/state-changing-calls.md
leohhhn Sep 3, 2024
c55822e
primitive types
leohhhn Sep 3, 2024
92d5c19
rm old fiel
leohhhn Sep 3, 2024
916f40b
add locally
leohhhn Sep 3, 2024
8bb8eff
locally
leohhhn Sep 3, 2024
8d44273
more complicated
leohhhn Sep 3, 2024
7a2010d
airgap fixup
leohhhn Sep 3, 2024
d7b07b0
two machines one person
leohhhn Sep 3, 2024
9c833ed
add numbers
leohhhn Sep 3, 2024
8d6fd2a
link call
leohhhn Sep 3, 2024
d6db3a0
save airgap
leohhhn Sep 3, 2024
aa26e6a
run
leohhhn Sep 3, 2024
53b6760
update link
leohhhn Sep 3, 2024
e24eabd
add acc num & seq num explanation
leohhhn Sep 3, 2024
d3126bd
Merge branch 'master' into docs/gnokey-tutorial
leohhhn Sep 5, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions docs/getting-started/local-setup/creating-a-keypair.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
id: creating-a-keypair
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
---

# Creating a Keypair
leohhhn marked this conversation as resolved.
Show resolved Hide resolved

## Overview

In this tutorial, you will learn how to create your Gno keypair using
[`gnokey`](../../gno-tooling/cli/gnokey/gnokey.md).

Keypairs are the foundation of how users interact with blockchains; and Gno is
no exception. By using a 12-word or 24-word [mnemonic phrase](https://www.zimperium.com/glossary/mnemonic-seed/#:~:text=A%20mnemonic%20seed%2C%20also%20known,wallet%20software%20or%20hardware%20device.)
deelawn marked this conversation as resolved.
Show resolved Hide resolved
as a source of randomness, users can derive a private and a public key.
These two keys can then be used further; a public key derives an address which is
a unique identifier of a user on the blockchain, while a private key is used for
signing messages and transactions for the aforementioned address, proving a user
has ownership over it.

Let's see how we can use `gnokey` to generate a keypair.

## Generating a keypair
aeddi marked this conversation as resolved.
Show resolved Hide resolved

The `gnokey add` command allows you to generate a new keypair. Simply run the
command, while adding a name for your keypair:

```bash
gnokey add MyKey
```

![gnokey-add-random](../../assets/getting-started/local-setup/creating-a-key-pair/gnokey-add-random.gif)

After running the command, `gnokey` will ask you to enter a password that will be
used to encrypt your keypair to the disk. Then, it will show you the following
information:
- Your public key, as well as the Gno address derived from it, starting with `g1...`,
- Your randomly generated 12-word mnemonic phrase which was used to derive the keypair.

:::warning Safeguard your mnemonic phrase!

A **mnemonic phrase** is like your master password; you can use it over and over
to derive the same keypair. This is why it is crucial to store it in a safe,
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
offline place - writing the phrase on a piece of paper and hiding it is highly
recommended. **If it gets lost, it is unrecoverable.**

:::

`gnokey` will generate a keybase in which it will store information about your
keypairs. The keybase directory path is stored under the `-home` flag in `gnokey`.
deelawn marked this conversation as resolved.
Show resolved Hide resolved

### Gno addresses

Your **Gno address** is like your username on the network; an address is visible
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
in the caller stack of an application, it is included in each transaction you create
with your keypair, and anyone who knows your address can send you [coins](../../concepts/stdlibs/coin.md),
etc.

## Conclusion

That's it 🎉

You've successfully created your first Gno keypair. Follow the next tutorial to
see how you can use it.
leohhhn marked this conversation as resolved.
Show resolved Hide resolved

If you wish to learn more about `gnokey` specifically, check out the
[gnokey section](../../gno-tooling/cli/gnokey/gnokey.md).









4 changes: 2 additions & 2 deletions docs/getting-started/local-setup/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ git clone https://github.com/gnolang/gno.git
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)
- `gnokey` - the Gno [keypair manager](../../gno-tooling/cli/gnokey/working-with-key-pairs.md)

To install all three tools, simply run the following in the root of the repo:
```bash
Expand Down Expand Up @@ -87,7 +87,7 @@ You should get the following output:

`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).
about `gnokey` [here](../../gno-tooling/cli/gnokey/gnokey.md).

To verify that the `gnokey` binary is installed system-wide, you can run:

Expand Down
26 changes: 13 additions & 13 deletions docs/getting-started/local-setup/interacting-with-gnoland.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,18 @@ 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
[Local Setup](installation.md) guide for steps
- **A keypair in `gnokey`.** Reference the [Creating a key pair](creating-a-keypair.md) 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).
[Gno Faucet Hub](https://faucet.gno.land).

![faucet-hub](../../assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png)

Expand All @@ -35,7 +34,7 @@ After inputting your address and solving the captcha, you can check if you have
following `gnokey` command:

```bash
gnokey query bank/balances/<your_gno_address> --remote "https://rpc.gno.land:443"
gnokey query bank/balances/<your_gno_address> --remote "https://rpc.gno.land:443"
```

If the faucet request was successful, you should see something similar to the
Expand All @@ -48,15 +47,16 @@ 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.
> Note: block heights in this case are unreliable because of the way the Portal Loop
> testnet works.
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
> Read more [here](../../concepts/portal-loop.md).

To see what functions are available to call on the Userbook realm, click
Expand All @@ -67,7 +67,7 @@ the `[help]` button.
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`:
keypair `MyKey`:

```
gnokey maketx call \
Expand All @@ -79,11 +79,11 @@ gnokey maketx call \
-broadcast \
-chainid "portal-loop" \
-remote "https://rpc.gno.land:443" \
MyKeypair
MyKey
```

To see what each option and flag in this command does, read the `gnokey`
[reference page](../../gno-tooling/cli/gnokey.md).
To see what each option and flag in this command does, check out `gnokey` in the
[tooling section](../../gno-tooling/cli/gnokey/gnokey.md).

## Conclusion

Expand All @@ -92,6 +92,6 @@ 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
This concludes the "Local Setup" section. 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.
2 changes: 1 addition & 1 deletion docs/gno-tooling/cli/faucet/faucet.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The Gno faucet works by designating a single address as a faucet address that wi
Ensure the faucet account will have enough funds
by [premining its balance](../../../gno-infrastructure/premining-balances.md) to a high value.
In case you do not have an existing address added to `gnokey`, you can consult
the [Working with Key Pairs](../../../getting-started/local-setup/working-with-key-pairs.md) guide.
the [Working with Key Pairs](../gnokey/working-with-key-pairs.md) guide.

## 2. Start the local chain

Expand Down
128 changes: 128 additions & 0 deletions docs/gno-tooling/cli/gnokey/full-security-tx.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
id: full-security-tx
---

# Making an airgapped transaction

## Prerequisites

- **`gnokey` installed.** Reference the
[Local Setup](../../../getting-started/local-setup/installation.md#2-installing-the-required-tools) guide for steps

## Overview

`gnokey` provides a way to create a transaction, sign it, and later
broadcast it to a chain in the most secure fashion. This approach, while more
complicated, grants full control and provides airgap support.
aeddi marked this conversation as resolved.
Show resolved Hide resolved

The indented purpose of this functionality is to provide maximum security when
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
signing and broadcasting a transaction. In practice, this procedure should take
place on two separate machines, one with access to the internet (`Machine 1`),
and the other one without (`Machine 2`), with the separation of steps as follows:
1. `Machine 1`: Fetch account information from the chain
2. `Machine 2`: Create an unsigned transaction locally
3. `Machine 2`: Sign the transaction
4. `Machine 1`: Broadcast the transaction
aeddi marked this conversation as resolved.
Show resolved Hide resolved

For the sake of simplicity, in this example, we will assume that the procedure
is happening on two machines, and we will again use the Userbook
realm on the Portal Loop testnet.
aeddi marked this conversation as resolved.
Show resolved Hide resolved

## Fetching account information from the chain
aeddi marked this conversation as resolved.
Show resolved Hide resolved

First, we need to fetch data for the account we are using to sign the transaction,
using the [auth/accounts](./querying-a-network.md#authaccounts) query:
aeddi marked this conversation as resolved.
Show resolved Hide resolved

```bash
gnokey query auth/accounts/<your_address> -remote "https://rpc.gno.land:443"
```

We need to extract the account number and sequence from the output:

```bash
height: 0
data: {
"BaseAccount": {
"address": "g1zzqd6phlfx0a809vhmykg5c6m44ap9756s7cjj",
"coins": "10000000ugnot",
"public_key": null,
"account_number": "468",
"sequence": "0"
}
}
```

In this case, the account number is `468`, and the sequence (nonce) is `0`. We
will need these values to sign the transaction later.

## Creating an unsigned transaction locally

To create the transaction you want, you can use the aforementioned `call` API,
aeddi marked this conversation as resolved.
Show resolved Hide resolved
without the `-broadcast` flag, while redirecting the output to a local file:

```bash
gnokey maketx call \
-pkgpath "gno.land/r/demo/userbook" \
-func "SignUp" \
-gas-fee 1000000ugnot \
-gas-wanted 2000000 \
leohhhn marked this conversation as resolved.
Show resolved Hide resolved
mykey > userbook.tx
```

This will create a `userbook.tx` file with a null `signature` field.
Now we are ready to sign the transaction.

## Signing the transaction

To add a signature to the transaction, we can use the `gnokey sign` subcommand.
To sign, we must set the correct flags for the subcommand:
- `-tx-path` - path to the transaction file to sign, in our case, `userbook.tx`
- `-chainid` - id of the chain to sign for
- `-account-number` - number of the account fetched previously
- `-account-sequence` - sequence of the account fetched previously

```bash
gnokey sign \
-tx-path userbook.tx \
-chainid "portal-loop" \
-account-number 468 \
-account-sequence 0 \
mykey
```

After inputting the correct values, `gnokey` will ask for the password to decrypt
the keypair. Once we input the password, we should receive the message that the
signing was completed. If we open the `userbook.tx` file, we will be able to see
that the signature field has been populated.

We are now ready to broadcast this transaction to the chain.

## Broadcasting the transaction

To broadcast the signed transaction to the chain, we can use the `gnokey broadcast`
subcommand, giving it the path to the signed transaction:

```bash
gnokey broadcast -remote "https://rpc.gno.land:443" userbook.tx
```

In this case, we do not need to specify a keypair, as the transaction has already
been signed in a previous step and `gnokey` is only sending it to the RPC endpoint.

## Verifying a transaction's signature

To verify a transaction's signature is correct, you can use the `gnokey verify`
subcommand. We can provide the path to the transaction document using the `-docpath`
flag, provide the key we signed the transaction with, and the signature itself.
Make sure the signature is in the `hex` format.
deelawn marked this conversation as resolved.
Show resolved Hide resolved

```bash
gnokey verify -docpath userbook.tx mykey <signature>
```

## Conclusion

That's it! 🎉

In this tutorial, you've learned to use `gnokey` for creating maximum-security
transactions in an airgapped manner.
16 changes: 16 additions & 0 deletions docs/gno-tooling/cli/gnokey/gnokey.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
id: gnokey
---

# `gnokey`

## Overview

In this section, you will learn how to use the `gnokey` binary. `gnokey` is the
gno.land CLI keychain and client, and it allows you to do 4 main things:
- Manage Gno keypairs
- Send state-changing calls (transactions)
- Query a gno.land network
- Sign and broadcast transactions with [airgap protection](https://en.wikipedia.org/wiki/Air_gap_(networking))

Check out the rest of this section to learn how to do all of these.
Loading
Loading