Skip to content

Commit

Permalink
docs: remove "cargo run" from most commands
Browse files Browse the repository at this point in the history
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/<bin>` themselves.

Refs #1976.
  • Loading branch information
conorsch committed Nov 28, 2023
1 parent c349fec commit 41e209b
Show file tree
Hide file tree
Showing 8 changed files with 54 additions and 60 deletions.
1 change: 0 additions & 1 deletion docs/guide/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions docs/guide/src/pcli/balance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
21 changes: 10 additions & 11 deletions docs/guide/src/pcli/governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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"
```

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
1 change: 0 additions & 1 deletion docs/guide/src/pcli/pclientd.md

This file was deleted.

36 changes: 18 additions & 18 deletions docs/guide/src/pcli/transaction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand All @@ -26,21 +26,21 @@ 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
delegation tokens you wish to undelegate. Wait a moment for the network to process the undelegation,
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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -107,21 +107,21 @@ 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

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
Expand All @@ -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
Expand All @@ -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`
Expand All @@ -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 <TRADING_PAIR> <QUANTITY> [--current-price AMT] [--fee-bps AMT]
pcli tx lp replicate xyk <TRADING_PAIR> <QUANTITY> [--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.
Expand Down Expand Up @@ -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 <OSMOSIS_ADDRESS> --channel <CHANNEL_ID> 5gm --timeout-height 5-5000000
pcli tx withdraw --to <OSMOSIS_ADDRESS> --channel <CHANNEL_ID> 5gm --timeout-height 5-5000000
```

Unfortunately the CLI tooling for Osmosis is cumbersome. For now, use `rly` as a user agent
Expand Down
10 changes: 5 additions & 5 deletions docs/guide/src/pcli/wallet.md
Original file line number Diff line number Diff line change
@@ -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!
Expand All @@ -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]
```
Expand All @@ -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.
```

Expand Down
13 changes: 5 additions & 8 deletions docs/guide/src/pclientd/configure.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,25 @@
# 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

`pclientd` can run in either view mode, with only a full viewing key, or custody mode, with the ability to sign transactions.

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.

Expand Down
Loading

0 comments on commit 41e209b

Please sign in to comment.