From b56de2513b88ae06bdcad95bec636d9fef519f14 Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Tue, 28 Nov 2023 12:54:29 -0800 Subject: [PATCH] docs: remove "cargo run" from most commands Reimplements the non-cargo, installed-path command invocations for both pcli and pd. This assumes that folks have installed the binaries from the release page. If folks want to compile from source, then they can use `cargo run` or `./target/release/` themselves. Refs #1976. --- docs/guide/src/SUMMARY.md | 1 - docs/guide/src/pcli/balance.md | 6 ++--- docs/guide/src/pcli/governance.md | 21 ++++++++-------- docs/guide/src/pcli/pclientd.md | 1 - docs/guide/src/pcli/transaction.md | 36 ++++++++++++++-------------- docs/guide/src/pcli/wallet.md | 10 ++++---- docs/guide/src/pclientd/configure.md | 13 ++++------ docs/guide/src/pd/join-testnet.md | 26 ++++++++++---------- 8 files changed, 54 insertions(+), 60 deletions(-) delete mode 100644 docs/guide/src/pcli/pclientd.md diff --git a/docs/guide/src/SUMMARY.md b/docs/guide/src/SUMMARY.md index 82dee1a8ad..966f311dc1 100644 --- a/docs/guide/src/SUMMARY.md +++ b/docs/guide/src/SUMMARY.md @@ -7,7 +7,6 @@ - [Viewing Balances](./pcli/balance.md) - [Sending Transactions](./pcli/transaction.md) - [Using Governance](./pcli/governance.md) - - [Using `pcli` with `pclientd`](./pcli/pclientd.md) - [Running a `pd` fullnode](./pd.md) - [Installing `pd`](./pd/install.md) - [Joining a Testnet](./pd/join-testnet.md) diff --git a/docs/guide/src/pcli/balance.md b/docs/guide/src/pcli/balance.md index 37bb5d0c4d..5c5e6a3773 100644 --- a/docs/guide/src/pcli/balance.md +++ b/docs/guide/src/pcli/balance.md @@ -4,7 +4,7 @@ Once you've received your first tokens, you can scan the chain to import them into your local wallet (this may take a few minutes the first time you run it): ```bash -cargo run --quiet --release --bin pcli view sync +pcli view sync ``` Syncing is performed automatically, but running the `sync` subcommand will @@ -14,12 +14,12 @@ invocations of `pcli` commands don't need to wait. If someone sent you testnet assets, you should be able to see them now by running: ```bash -cargo run --quiet --release --bin pcli view balance +pcli view balance ``` This will print a table of assets by balance in each. The `balance` view just shows asset amounts. To see more information about delegation tokens and the stake they represent, use ```bash -cargo run --quiet --release --bin pcli view staked +pcli view staked ``` diff --git a/docs/guide/src/pcli/governance.md b/docs/guide/src/pcli/governance.md index d8f957bfd6..fa7bab5453 100644 --- a/docs/guide/src/pcli/governance.md +++ b/docs/guide/src/pcli/governance.md @@ -24,13 +24,13 @@ proposal` subcommand. To list all the active proposals by their ID, use: ```bash -cargo run --release --bin pcli query governance list-proposals +pcli query governance list-proposals ``` Other proposal query commands all follow the form: ```bash -cargo run --release --bin pcli query governance proposal [PROPOSAL_ID] [QUERY] +pcli query governance proposal [PROPOSAL_ID] [QUERY] ``` These are the queries currently defined: @@ -56,7 +56,7 @@ can vote on it using the `tx vote` subcommand of `pcli`. For example, if you wan proposal 1, you would do: ```bash -cargo run --release --bin pcli tx vote yes --on 1 +pcli tx vote yes --on 1 ``` When you vote as a delegator (but _not_ when you vote as a validator), you will receive @@ -71,7 +71,7 @@ If you are a validator who was active when the proposal started, you can vote on would do: ```bash -cargo run --release --bin pcli validator vote yes --on 1 +pcli validator vote yes --on 1 ``` ### Eligibility And Voting Power @@ -164,7 +164,7 @@ To submit a proposal, first generate a proposal template for the kind of proposa submit. For example, suppose we want to create a signaling proposal: ```bash -cargo run --release --bin pcli tx proposal template signaling --file proposal.toml +pcli tx proposal template signaling --file proposal.toml ``` This outputs a TOML template for the proposal to the file `proposal.toml`, where you can edit the @@ -179,7 +179,7 @@ specify the proposal deposit in this action; it is determined automatically base parameters. ```bash -cargo run --release --bin pcli tx proposal submit --file proposal.toml +pcli tx proposal submit --file proposal.toml ``` The proposal deposit will be immediately escrowed and the proposal voting period will start in the @@ -234,8 +234,7 @@ community consensus), you can do so before voting concludes. Note that this does to losing your deposit by slashing, as withdrawn proposals can still be voted on and slashed. ```bash -cargo run --release --bin pcli \ - tx proposal withdraw 0 \ +pcli tx proposal withdraw 0 \ --reason "some human-readable reason for withdrawal" ``` @@ -252,7 +251,7 @@ concludes, you can claim your proposal deposit using the `tx proposal deposit-cl say: ```bash -cargo run --release --bin pcli tx proposal deposit-claim 1 +pcli tx proposal deposit-claim 1 ``` This will _consume_ your proposal deposit NFT (either the original or the one you received after @@ -268,7 +267,7 @@ Anyone can contribute any amount of any denomination to the Penumbra DAO. To do command `pcli tx dao-deposit`, like so: ```bash -cargo run --release --bin pcli tx dao-deposit 100penumbra +pcli tx dao-deposit 100penumbra ``` Funds contributed to the DAO cannot be withdrawn except by a successful DAO spend governance @@ -278,7 +277,7 @@ To query the current DAO balance, use `pcli query dao balance` with the **base d asset or its asset ID (display denominations are not currently accepted). For example: ```bash -cargo run --release --bin pcli query dao balance upenumbra +pcli query dao balance upenumbra ``` DAO spend proposals are only accepted for voting if they would not overdraw the current funds in the diff --git a/docs/guide/src/pcli/pclientd.md b/docs/guide/src/pcli/pclientd.md deleted file mode 100644 index caa563e4f5..0000000000 --- a/docs/guide/src/pcli/pclientd.md +++ /dev/null @@ -1 +0,0 @@ -# Using pcli with pclientd diff --git a/docs/guide/src/pcli/transaction.md b/docs/guide/src/pcli/transaction.md index 185a2b0dff..231d01eeb9 100644 --- a/docs/guide/src/pcli/transaction.md +++ b/docs/guide/src/pcli/transaction.md @@ -6,14 +6,14 @@ send them any amount of any asset you have. First, use balance to find the amount of assets you have: ```bash -cargo run --release --bin pcli view balance +pcli view balance ``` Second, if I wanted to send 10 penumbra tokens to my friend, I could do that like this (filling in their full address at the end): ```bash -cargo run --quiet --release --bin pcli tx send 10penumbra --to penumbrav2t... +pcli tx send 10penumbra --to penumbrav2t... ``` Notice that asset amounts are typed amounts, specified without a space between the amount (`10`) @@ -26,13 +26,13 @@ In addition, to sending an asset, one may also stake penumbra tokens to validato Find a validator to stake to: ```bash -cargo run --release --bin pcli query validator list +pcli query validator list ``` Copy and paste the identity key of one of the validators to stake to, then construct the staking tx: ```bash -cargo run --release --bin pcli tx delegate 10penumbra --to penumbravalid... +pcli tx delegate 10penumbra --to penumbravalid... ``` To undelegate from a validator, use the `pcli tx undelegate` command, passing it the typed amount of @@ -40,7 +40,7 @@ delegation tokens you wish to undelegate. Wait a moment for the network to proce then reclaim your funds: ```bash -cargo run --release --bin pcli tx undelegate-claim +pcli tx undelegate-claim ``` Inspect the output; a message may instruct you to wait longer, for a new epoch. Check back and rerun the command @@ -67,20 +67,20 @@ The basic commands for opening liquidity positions are `tx position order buy` a To open an order buying `10cube` at a price of `1penumbra` each, with no fee, you'd do the following: ```bash -cargo run --release --bin pcli -- tx position order buy 10cube@1penumbra +pcli tx position order buy 10cube@1penumbra ``` Similarly, to open an order selling `100penumbra` at a price of `5gm` each, with a `20bps` fee on transactions against the liquidity position, you would append `/20bps` at the end of the order, like as follow: ```bash -cargo run --release --bin pcli -- tx position order sell 100penumbra@5gm/20bps +pcli tx position order sell 100penumbra@5gm/20bps ``` After opening the position, you'll see that your account has been deposited an "LPNFT" representing the open position: ```bash -$ cargo run --release --bin pcli -- view balance +$ pcli view balance Account Amount 0 1lpnft_opened_plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr @@ -91,13 +91,13 @@ $ cargo run --release --bin pcli -- view balance If you have an open liquidity position, you may close it, preventing further trading against it. ```bash -cargo run --release --bin pcli -- tx position close plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr +pcli tx position close plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr ``` This will subtract the opened LPNFT and deposit a closed LPNFT into your balance: ```bash -$ cargo run --release --bin pcli -- view balance +$ pcli view balance Account Amount 0 1lpnft_closed_plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr @@ -107,7 +107,7 @@ You also have the option to close **all** liquidity positions associated with an trading function approximation: ```bash -cargo run --release --bin pcli -- tx position close-all +pcli tx position close-all ``` ### Withdrawing a Liquidity Position @@ -115,13 +115,13 @@ cargo run --release --bin pcli -- tx position close-all If you have a closed liquidity position, you may withdraw it, depositing the reserves in the trading position into your balance. ```bash -cargo run --release --bin pcli -- tx position withdraw plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr +pcli tx position withdraw plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr ``` This will subtract the closed LPNFT and deposit a withdrawn LPNFT into your balance, along with any reserves belonging to the trading position: ```bash -$ cargo run --release --bin pcli -- view balance +$ pcli view balance Account Amount 0 1lpnft_withdrawn_plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr @@ -132,7 +132,7 @@ You also have the option to withdraw **all** liquidity positions associated with trading function approximation: ```bash -cargo run --release --bin pcli -- tx position withdraw-all +pcli tx position withdraw-all ``` ## Swapping Assets @@ -145,7 +145,7 @@ Swaps take place against the on-chain liquidity positions described earlier in t If you wanted to exchange 1 `penumbra` tokens for `gm` tokens, you could do so like so: ```bash -cargo run --release --bin pcli -- tx swap --into gm 1penumbra +pcli tx swap --into gm 1penumbra ``` This will handle generating the swap transaction and you'd soon have the market-rate equivalent of 1 `penumbra` @@ -157,12 +157,12 @@ enough liquidity available to perform the swap. Penumbra's constant-price pool is a versatile market primitive, allowing users extensive control over their trading strategies. It's not solely for active DEX quoters; with our AMM replication tool, users can emulate any passive AMM of their choice. The testnet comes with a built-in UniswapV2 replicator that is utilized as such: ```bash -cargo run -r --bin pcli tx lp replicate xyk [--current-price AMT] [--fee-bps AMT] +pcli tx lp replicate xyk [--current-price AMT] [--fee-bps AMT] ``` For instance, to provide ~100penumbra and ~100test_usd liquidity on the `penumbra:test_usd` pair with a pool fee of `33bps`, run: ```bash -cargo run -r --bin pcli tx lp replicate xyk penumbra:test_usd 100penumbra --fee-bps 33 +pcli tx lp replicate xyk penumbra:test_usd 100penumbra --fee-bps 33 ``` You will be prompted a disclaimer which you should read carefully, and accept or reject by pressing "y" for yes, or "n" for no. @@ -214,7 +214,7 @@ So a value like `5-5000000` (i.e. revision 5 at height 5 million) will work. To initiate an IBC withdrawal from Penumbra testnet to Osmosis testnet: ```bash -cargo run --release --bin pcli -- tx withdraw --to --channel 5gm --timeout-height 5-5000000 +pcli tx withdraw --to --channel 5gm --timeout-height 5-5000000 ``` Unfortunately the CLI tooling for Osmosis is cumbersome. For now, use `rly` as a user agent diff --git a/docs/guide/src/pcli/wallet.md b/docs/guide/src/pcli/wallet.md index 50cc66cc11..036fe83c98 100644 --- a/docs/guide/src/pcli/wallet.md +++ b/docs/guide/src/pcli/wallet.md @@ -1,10 +1,10 @@ # Generating a Wallet -On first installation of `pcli`, you will need to generate a fresh wallet to use with Penumbra. +On first [installation of `pcli`](./install.md), you will need to generate a fresh wallet to use with Penumbra. The `pcli init` command will generate a configuration file. To generate a new wallet, try: ```bash -$ cargo run --quiet --release --bin pcli init soft-kms generate +$ pcli init soft-kms generate YOUR PRIVATE SEED PHRASE: [SEED PHRASE] Save this in a safe place! @@ -15,7 +15,7 @@ This uses the `soft-kms` backend, which saves the generated spend key in the con Alternatively, to import an existing wallet, try ```bash -$ cargo run --quiet --release --bin pcli init soft-kms import-phrase +$ pcli init soft-kms import-phrase Enter seed phrase: Writing generated configs to [PATH TO PCLI DATA] ``` @@ -25,12 +25,12 @@ controlled by your wallet. To generate the address for a numbered account, use `pcli view address`: ```bash -$ cargo run --quiet --release --bin pcli view address 0 +$ pcli view address 0 penumbrav2t1... ``` You can also run `pcli view address` on an address to see which account it corresponds to: ```bash -$ cargo run --quiet --release --bin pcli view address penumbrav2t1... +$ pcli view address penumbra1... Address is viewable with this full viewing key. Account index is 0. ``` diff --git a/docs/guide/src/pclientd/configure.md b/docs/guide/src/pclientd/configure.md index 50f3097ea2..c2cefddd93 100644 --- a/docs/guide/src/pclientd/configure.md +++ b/docs/guide/src/pclientd/configure.md @@ -1,10 +1,7 @@ # Configuring `pclientd` -First, install `pclientd` following the [instructions for building -`pcli`](../pcli/install.md) but building `pclientd` rather than `pcli`: -```bash -cargo build --release --bin pclientd -``` +First, install `pclientd` following the [instructions for installing +`pcli`](../pcli/install.md) but downloading `pclientd` rather than `pcli`. ## Generating configs @@ -12,17 +9,17 @@ cargo build --release --bin pclientd To initialize `pclientd` in view mode, run ``` -cargo run --release --bin pclientd -- init --view FULL_VIEWING_KEY +pclientd init --view FULL_VIEWING_KEY ``` The `FULL_VIEWING_KEY` can be obtained from the `config.toml` generated by `pcli init`. To initialize `pclientd` in custody mode, run ``` -cargo run --release --bin pclientd -- init --custody - +pclientd init --custody - ``` to read a seed phrase from `stdin`, or ``` -cargo run --release --bin pclientd -- init --custody "SEED PHRASE" +pclientd init --custody "SEED PHRASE" ``` to specify the seed phrase on the command line. diff --git a/docs/guide/src/pd/join-testnet.md b/docs/guide/src/pd/join-testnet.md index 97f4f8ede5..b6fedef33a 100644 --- a/docs/guide/src/pd/join-testnet.md +++ b/docs/guide/src/pd/join-testnet.md @@ -12,7 +12,7 @@ have no value. ## Joining as a fullnode -To join a testnet as a fullnode, check out the tag for the current testnet, run +To join a testnet as a fullnode, [install the most recent version of `pd`](install.md), run `pd testnet join` to generate configs, then use those configs to run `pd` and `cometbft`. In more detail: @@ -21,7 +21,7 @@ To join a testnet as a fullnode, check out the tag for the current testnet, run First, reset the testnet data from any prior testnet you may have joined: ```shell -cargo run --bin pd --release -- testnet unsafe-reset-all +pd testnet unsafe-reset-all ``` This will delete the entire testnet data directory. @@ -31,7 +31,7 @@ This will delete the entire testnet data directory. Next, generate a set of configs for the current testnet: ```shell -cargo run --bin pd --release -- testnet join --external-address IP_ADDRESS:26656 --moniker MY_NODE_NAME +pd testnet join --external-address IP_ADDRESS:26656 --moniker MY_NODE_NAME ``` where `IP_ADDRESS` (like `1.2.3.4`) is the public IP address of the node you're running, @@ -52,7 +52,7 @@ the section above on resetting node state. Next, run `pd`: ```shell -cargo run --bin pd --release -- start +pd start ``` Then (perhaps in another terminal), run CometBFT, specifying `--home`: @@ -83,7 +83,7 @@ sudo systemctl restart penumbra cometbft After starting your node, as above, you should now be participating in the network as a fullnode. However your validator won't be visible to the chain yet, -as the definition hasn't been uploaded. +as the definition hasn't been uploaded. To proceed, you must have [`pcli` installed](../pcli/install.md). ### Validator Definitions (Penumbra) @@ -101,7 +101,7 @@ update the configuration for a validator. To create a template configuration, use `pcli validator definition template`: ```shell -$ cargo run --release --bin pcli -- validator definition template \ +$ pcli validator definition template \ --tendermint-validator-keyfile ~/.penumbra/testnet_data/node0/cometbft/config/priv_validator_key.json \ --file validator.toml $ cat validator.toml @@ -192,13 +192,13 @@ After setting up metadata, funding streams, and the correct consensus key in your `validator.toml`, you can upload it to the chain: ```console -cargo run --release --bin pcli -- validator definition upload --file validator.toml +pcli validator definition upload --file validator.toml ``` And verify that it's known to the chain: ```console -cargo run --release --bin pcli -- query validator list -i +pcli query validator list -i ``` However your validator doesn't have anything delegated to it and will remain in @@ -210,19 +210,19 @@ active set of validators. First find your validator's identity key: ```console -cargo run --release --bin pcli -- validator identity +pcli validator identity ``` And then delegate some amount of `penumbra` to it: ```console -cargo run --release --bin pcli -- tx delegate 1penumbra --to penumbravalid1g2huds8klwypzczfgx67j7zp6ntq2m5fxmctkf7ja96zn49d6s9qz72hu3 +pcli tx delegate 1penumbra --to penumbravalid1g2huds8klwypzczfgx67j7zp6ntq2m5fxmctkf7ja96zn49d6s9qz72hu3 ``` You should then see your balance of `penumbra` decreased and that you have received some amount of delegation tokens for your validator: ```console -cargo run --release --bin pcli view balance +pcli view balance ``` Voting power will be calculated on the next epoch transition after your @@ -238,7 +238,7 @@ deployment. You can find the values in use for the current chain in its First fetch your existing validator definition from the chain: ```console -cargo run --release --bin pcli -- validator definition fetch --file validator.toml +pcli validator definition fetch --file validator.toml ``` Then make any changes desired and **make sure to increase by `sequence_number` by at least 1!** @@ -247,5 +247,5 @@ The `sequence_number` is a unique, increasing identifier for the version of the After updating the validator definition you can upload it again to update your validator metadata on-chain: ```console -cargo run --release --bin pcli -- validator definition upload --file validator.toml +pcli validator definition upload --file validator.toml ```