[cli] Add client faucet command to get gas #15940

stefan-mysten · 2024-01-26T03:03:22Z

Description

Added a new command sui client faucet to make it easier to get gas from devnet, testnet, or local network. If a different network than the usual ones (fullnode.network.sui.io) is used, it will complain and ask to pass the url to its faucet.

There are two options for the command:
--url, which is the URL to the gas faucet server
--address, which can be either an address or the alias name corresponding to an address in the wallet.

Usage

sui client faucet => will use the active network and active address
sui client faucet --address alias_name => will use the address corresponding to this alias, and the active network
sui client faucet --url => will use the active address and the faucet server at that endpoint
sui client faucet --address alias_name --url https://myfaucet.mysui.io/v5/gas => will use that address corresponding to the alias, and the faucet server at that endpoint.

Output

It will only output that the request was successful and the task id that it got from the faucet server. The user has to manually check for the gas coin if it was sent to the address or not (due to rate-limits, an automated approach fails easily).

Test Plan

If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section.

Type of Change (Check all that apply)

protocol change
user-visible impact
breaking change for a client SDKs
breaking change for FNs (FN binary must upgrade)
breaking change for validators or node operators (must upgrade binaries)
breaking change for on-chain data layout
necessitate either a data wipe or data migration

Release notes

Added a new command sui client faucet to make it easier to get gas from devnet, testnet, or a local network. If a different network than the usual ones (fullnode.network.sui.io) is used, it will complain and ask to pass the URL to the faucet server.

There are two options for the command:
--url, which is the URL to the gas faucet server
--address, which can be either an address or the alias name corresponding to an address in the wallet.

Usage

sui client faucet => will use the active network and active address
sui client faucet --address alias_name => will use the address corresponding to this alias, and the active network
sui client faucet --url => will use the active address and the faucet server at that endpoint
sui client faucet --address alias_name --url https://myfaucet.mysui.io/v5/gas => will use that address corresponding to the alias, and the faucet server at that endpoint.

Output

It will only output that the request was successful and instruct the user to wait up to 60 seconds and then manually check (sui client gas) for the gas coin if it was sent to the address or not.

vercel · 2024-01-26T03:03:28Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
mysten-ui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 27, 2024 3:16am
sui-core	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 27, 2024 3:16am
sui-typescript-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 27, 2024 3:16am

3 Ignored Deployments

Name	Status	Preview	Updated (UTC)
explorer	⬜️ Ignored (Inspect)	Visit Preview	Jan 27, 2024 3:16am
multisig-toolkit	⬜️ Ignored (Inspect)	Visit Preview	Jan 27, 2024 3:16am
sui-kiosk	⬜️ Ignored (Inspect)	Visit Preview	Jan 27, 2024 3:16am

amnn

Thanks @stefan-mysten! This is timely, because @giac-mysten was just lamenting how he couldn't easily request gas from the CLI!

amnn · 2024-01-26T19:15:15Z

crates/sui/src/client_commands.rs

+                            SUI_DEVNET_URL => "https://faucet.devnet.sui.io/v1/gas",
+                            SUI_TESTNET_URL => "https://faucet.testnet.sui.io/v1/gas",


I think this is right, but just to confirm -- is this the version that uses batching? (the new form of the API?)

From what I know, yes.

crates/sui/src/client_commands.rs

amnn · 2024-01-26T19:18:25Z

crates/sui/src/client_commands.rs

+                    }
+                };
+                request_tokens_from_faucet(address, url).await?;
+                SuiClientCommandResult::NoOutput


Seems like this is useful to replace some other command results as well (perhaps as a follow-up)?

Yes, that's the plan, but I did not want to include non related changes here.

amnn · 2024-01-26T19:19:28Z

crates/sui/src/client_commands.rs

+    println!("Requested gas from faucet: {url}");
+    println!(


What's our current stance on println! vs tracing vs other output methods for the CLI? Do we have a standard now?

I've been thinking on how to do this. What we wanted to do is to use eprintln for stderr stuff, and the rest should be mostly tabulated output. What I wanted to have as output for this is the new coin object id, but that's difficult because of the rate limiter on the faucet server (in my tests, I run the request and then the next request to check for task status returned a 429, so not easy). An alternative is to call the gas command before the faucet, and then in a loop wait until we have 1 extra coin, and then do a diff to get the id. It's hacky, but this solves the rate limiter issue.

Thoughts?

amnn · 2024-01-26T19:20:36Z

crates/sui/src/client_commands.rs

+    println!("Faucet task id: {task_id}");
+    println!("The coin should be available in the next couple of minutes. Run sui client gas to find your coins.");


It is usually quicker than a couple of minutes, so is it worth waiting for it here? (Perhaps guarded by a flag/option?)

This is something that we can follow up with as well!

The issue with waiting is that often due to the rate limiter, we cannot make a request to the faucet server for the status as it will return 429. The hacky way is to call gas command, and then in a loop call the gas command and get the coins until we have coins.len() + 1.
Maybe a --wait-for-coin-id flag can be used to indicate that the user wants to wait to get the coin id?

The main issue is that I could have my set active network to X, and then issue faucet --url Y, so when calling gas command, it will use the X network instead of the Y one...

Tried to do something and realized that if a custom RPC's faucet endpoint does not follow the usual faucet.network.address it's hard to "deconstruct" the RPC endpoint to get the gas objects, so it is not so straightforward. For now, it will just tell the user to check for gas. If anyone has better ideas, I am all ears :D

amnn · 2024-01-26T19:21:14Z

crates/sui/src/client_commands.rs

+        resp.status()
+    );
+    if resp.status() == 429 {
+        bail!("Faucet received too many requests from this ip address. Please try again after 60 minutes.");


Suggested change

bail!("Faucet received too many requests from this ip address. Please try again after 60 minutes.");

bail!("Faucet received too many requests from this IP address. Please try again after 60 minutes.");

amnn · 2024-01-26T19:22:07Z

crates/sui/src/client_commands.rs

+    let faucet_resp: FaucetResponse = resp.json().await?;
+
+    let task_id = if let Some(err) = faucet_resp.error {
+        bail!("Faucet request was unsuccessful. Error is {err:?}")


Suggested change

bail!("Faucet request was unsuccessful. Error is {err:?}")

bail!("Faucet request was unsuccessful: {err}")

Don't use debug output for errors -- most of the time the impl Display for the error type displays a human-readable message, and we should use that. In the cases it doesn't, we should fix that.

Oops, my bad. Thanks for spotting this!

amnn · 2024-01-26T19:22:16Z

crates/sui/src/client_commands.rs

+    } else {
+        faucet_resp.task
+    };
+    println!("Faucet task id: {task_id}");


Suggested change

println!("Faucet task id: {task_id}");

println!("Faucet task ID: {task_id}");

… if it is success or error

Add client faucet command to get gas

0283b02

stefan-mysten requested review from a team January 26, 2024 03:03

vercel bot deployed to Preview – sui-typescript-docs January 26, 2024 03:04 View deployment

vercel bot deployed to Preview – mysten-ui January 26, 2024 03:04 View deployment

Fix clippy and rustfmt

e419c85

vercel bot deployed to Preview – sui-typescript-docs January 26, 2024 05:22 View deployment

vercel bot deployed to Preview – mysten-ui January 26, 2024 05:23 View deployment

vercel bot deployed to Preview – sui-core January 26, 2024 05:23 View deployment

amnn approved these changes Jan 26, 2024

View reviewed changes

vercel bot deployed to Preview – sui-typescript-docs January 27, 2024 03:14 View deployment

vercel bot deployed to Preview – mysten-ui January 27, 2024 03:14 View deployment

vercel bot deployed to Preview – sui-core January 27, 2024 03:14 View deployment

Fix some things, address feedback, and only print one line regardless…

c0df8df

… if it is success or error

stefan-mysten force-pushed the cli_faucet branch from 2b880aa to c0df8df Compare January 27, 2024 03:15

vercel bot deployed to Preview – sui-typescript-docs January 27, 2024 03:16 View deployment

vercel bot deployed to Preview – mysten-ui January 27, 2024 03:16 View deployment

vercel bot deployed to Preview – sui-core January 27, 2024 03:16 View deployment

stefan-mysten enabled auto-merge (squash) January 27, 2024 03:27

stefan-mysten merged commit 58af069 into MystenLabs:main Jan 27, 2024
41 checks passed

stefan-mysten deleted the cli_faucet branch January 27, 2024 06:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[cli] Add client faucet command to get gas #15940

[cli] Add client faucet command to get gas #15940

stefan-mysten commented Jan 26, 2024 •

edited by ebmifa

vercel bot commented Jan 26, 2024 •

edited

amnn left a comment

amnn Jan 26, 2024

stefan-mysten Jan 26, 2024

amnn Jan 26, 2024

stefan-mysten Jan 26, 2024

amnn Jan 26, 2024

stefan-mysten Jan 26, 2024

amnn Jan 26, 2024

amnn Jan 26, 2024

stefan-mysten Jan 26, 2024

stefan-mysten Jan 27, 2024 •

edited

amnn Jan 26, 2024

amnn Jan 26, 2024

stefan-mysten Jan 26, 2024

amnn Jan 26, 2024

		SUI_DEVNET_URL => "https://faucet.devnet.sui.io/v1/gas",
		SUI_TESTNET_URL => "https://faucet.testnet.sui.io/v1/gas",

		println!("Faucet task id: {task_id}");
		println!("The coin should be available in the next couple of minutes. Run sui client gas to find your coins.");

	bail!("Faucet received too many requests from this ip address. Please try again after 60 minutes.");
	bail!("Faucet received too many requests from this IP address. Please try again after 60 minutes.");

	bail!("Faucet request was unsuccessful. Error is {err:?}")
	bail!("Faucet request was unsuccessful: {err}")

[cli] Add client faucet command to get gas #15940

[cli] Add client faucet command to get gas #15940

Conversation

stefan-mysten commented Jan 26, 2024 • edited by ebmifa

Description

Usage

Output

Test Plan

Type of Change (Check all that apply)

Release notes

Usage

Output

vercel bot commented Jan 26, 2024 • edited

amnn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stefan-mysten Jan 27, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stefan-mysten commented Jan 26, 2024 •

edited by ebmifa

vercel bot commented Jan 26, 2024 •

edited

stefan-mysten Jan 27, 2024 •

edited