docs: add gnolang/faucet
#2122
docs: add gnolang/faucet
#2122
Conversation
|
Posted some questions here to clarify things not found in the reference docs |
|
Crossposting from the issue for visibility:
What is the difference between these flags? |
| - `gnoland` & `gnokey` installed | ||
| - A Gno.land keypair generated using [`gnokey`](../gno-tooling/cli/gnokey.md) | ||
|
|
||
| ## Premining funds to an address |
There was a problem hiding this comment.
We should drop this section completely, and not reference genesis_balances.txt anywhere -- we have adequate genesis balances commands for premining accounts
There was a problem hiding this comment.
I've removed this section and added a prerequisite: 6aeb1f5
|
|
||
| ## Premining funds to an address | ||
|
|
||
| Before setting up the faucet, we need to make sure that the address will be used |
There was a problem hiding this comment.
This is not a correct English sentence:
we need to make sure that the address will be used to serve the funds contain enough testnet funds
There was a problem hiding this comment.
This section was completely removed as per #2122 (comment)
|
|
||
| ```json | ||
| { | ||
| "To": "g1juz2yxmdsa6audkp6ep9vfv80c8p5u76e03vvh" |
There was a problem hiding this comment.
This is outdated, please reference the latest gnolang/faucet request structure
There was a problem hiding this comment.
A request without an Amount specified is actually still valid, however I have added further explanations on the amount field and how to use it: e33f6e3
| } | ||
| ``` | ||
|
|
||
| You can test this out buy running the following `curl` command: |
There was a problem hiding this comment.
Nice catch, fixed it: 15028c7
| in the `--remote` flag in the faucet. If your node is listening on a separate | ||
| address, make sure to match it accordingly when running the faucet. | ||
|
|
||
| ## Making faucet requests |
There was a problem hiding this comment.
Error handling was not covered in this section, please cover it 🙏
There was a problem hiding this comment.
I've added possible errors a user can have while setting up the faucet or when making requests:
e33f6e3
docs/gno-tooling/cli/faucet.md
Outdated
| @@ -0,0 +1,46 @@ | |||
| --- | |||
| id: gno-tooling-tm2-faucet | |||
There was a problem hiding this comment.
I'm not sure what the use of this file is, it can become outdated very quickly (help output)
| @@ -0,0 +1,173 @@ | |||
| --- | |||
| id: setting-up-a-faucet | |||
There was a problem hiding this comment.
This tutorial doesn't cover:
gnofaucetgnofaucetvsgnolang/faucet- different things I've noted as part of the comments
There was a problem hiding this comment.
Looking at the original issue, this tutorial was meant to cover setting up a faucet with gnolang/faucet, which it does.
I suggest two options:
- We keep the scope of this PR to cover
gnolang/faucet, and open a separate issue for documentinggnofaucet. Ideally, we would have some reference docs or at least a basic README about it before I start working on it. - I'm unfamiliar with the
gnofaucetfunctionalities and codebase - understanding the details of it are a requirement for me to be able to write a high-quality tutorial. Possibly we can jump on a quick 15 min call and you can run me through the main functionalities to speed up the process, and get this done asap?
I have fixed up all of the other comments as requested, and added a section mentioning that the faucet can be extended and referenced gnofaucet as an example: d2388e7
WDYT?
cc @Kouteki
There was a problem hiding this comment.
I like option 1 better - it lets us publish this PR and make incremental progress.
There was a problem hiding this comment.
We discussed on a call that gnofaucet is most definitely in the scope of this PR, and should be added -- please add it and ping me when it's up in the PR 🙏
There was a problem hiding this comment.
Frankly speaking, I do not remember discussing this on a call.
However, I did take about 2h to read through the code of gnofaucet and write up a section on it. Please check it out.
I've also added a mention of the Faucet Hub.
# Conflicts: # docs/gno-tooling/cli/faucet/faucet.md
| - A Gno.land keypair generated using [`gnokey`](../gno-tooling/cli/gnokey.md) | ||
| containing funds for the faucet to serve |
There was a problem hiding this comment.
These are 2 separate requirements -- please make them clear.
Also, please link some kind of guide on how to actually prefund an account
| ``` | ||
|
|
||
| In the `config.toml` file, you will be able to configure a few parameters: | ||
| - ChainID of the node to connect to |
There was a problem hiding this comment.
This is the chain ID of the network, not the node
|
|
||
| In the `config.toml` file, you will be able to configure a few parameters: | ||
| - ChainID of the node to connect to | ||
| - Faucet listener address |
There was a problem hiding this comment.
Please expand on this, it's not immediately clear that this is the serve address of the faucet that others can use to initiate faucet requests
| - Mnemonic phrase to use for generating the account(s) to serve funds from | ||
| - The number of accounts to generate from the mnemonic |
There was a problem hiding this comment.
Please explain better how these 2 things play together into the faucet
| We will keep it simple and go with the basic configuration. After inputting the | ||
| mnemonic phrase from which your faucet address is derived from, you are ready to | ||
| run the faucet. |
There was a problem hiding this comment.
But how is the default configuration one where you don't specify a mnemonic?
|
|
||
| When requesting a drip from the faucet, you can face the following errors: | ||
| - If the address provided is empty or has an invalid checksum - `invalid beneficiary address` | ||
| - If the amount requested is empty, not in the `<amount>ugnot` format, or is larger |
| - `captcha-secret` - where you can provide your reCaptcha v2 secret key | ||
| - `is-behind-proxy` - which enables or disables the IP throttling functionality. |
There was a problem hiding this comment.
Can you please standardize the formatting in this doc?
Some points have ., some don't
| `5` requests per minute from a single IP address. To configure this, change the | ||
| hardcoded `maxRequestsPerMinute` value in the [`throttle.go`](https://github.com/gnolang/gno/blob/master/contribs/gnofaucet/throttle.go) | ||
| file in the `gnofaucet` folder. |
There was a problem hiding this comment.
This is terrible advice, please delete this
| id: setting-up-a-faucet | ||
| --- | ||
|
|
||
| # Setting up a faucet for your Gno network |
There was a problem hiding this comment.
This tutorial doesn't explain probably the one thing it was supposed to -- how the faucet actually works with subaccounts and funding
|
@leohhhn is this PR still relevant? |
|
Closing this but we can reuse it later for the faucet/gnofaucet readme. |
Description
Closes: #2120
This PR introduces the following changes to the docs (text copied over from the issue linked above):
Matching docs PR (linked in the issue that this PR was created from)
Contributors' checklist...
BREAKING CHANGE: xxxmessage was included in the description