From e2c8effe9be86b3a39559c6e1813fb95ad1bc115 Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Wed, 7 Feb 2024 12:26:39 -0800 Subject: [PATCH 1/2] docs: update devnet guide for new pcli syntax Closes #3707. --- docs/guide/src/dev/devnet-quickstart.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/guide/src/dev/devnet-quickstart.md b/docs/guide/src/dev/devnet-quickstart.md index 923d9203f9..c9eb71529f 100644 --- a/docs/guide/src/dev/devnet-quickstart.md +++ b/docs/guide/src/dev/devnet-quickstart.md @@ -3,7 +3,7 @@ This page describes a quickstart method for running `pd`+`cometbft` to test changes during development. -To start, you'll need to [install CometBFT `v0.37`](../pd/install.md#installing-cometbft). +To start, you'll need to install a [specific version of CometBFT](../pd/install.md#installing-cometbft). ## Generating configs @@ -44,23 +44,24 @@ in another terminal window. ## Running `pcli` -To interact with the chain, first do +To interact with the chain, configure a wallet pointing at the localhost node: ```shell -cargo run --release --bin pcli -- view reset +cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view reset +cargo run --release --bin pcli -- init --grpc-url http://localhost:8080 soft-kms generate +# or, to reuse an existing seed phrase: +cargo run --release --bin pcli -- init --grpc-url http://localhost:8080 soft-kms import-phrase ``` -and then pass the `-n` flag to any commands you run to point `pcli` at your local node, e.g., +and then pass the `--home` flag to any commands you run to point `pcli` at your local node, e.g., ```shell -cargo run --bin pcli -- -n http://127.0.0.1:8080 view balance +cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view balance ``` -By default, `pd testnet generate` uses the latest snapshot of the Discord's -faucet channel, so if you posted your address there more than a week or two ago, -you should already have an allocation in your local devnet. - -If not, reset the state as below, and edit the `genesis.json` to add your address. +By default, `pd testnet generate` uses the testnet allocations from the `testnets/` directory in the git repo. +If you have an address included in those files, then use `pcli init soft-kms import-phrase`. Otherwise, +edit the `genesis.json` to add your address. ## Resetting and restarting @@ -73,7 +74,7 @@ cargo run --release --bin pd -- testnet unsafe-reset-all You'll probably also want to reset your wallet state: ```shell -cargo run --release --bin pcli -- view reset +cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view reset ``` At this point you're ready to generate new configs, and restart both `pd` and From 1e93f2b09e2c7c4d73ea3e9f089a6b3f5918bff4 Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Wed, 7 Feb 2024 12:31:21 -0800 Subject: [PATCH 2/2] docs: update proto urls to v1 Follow-up to https://github.com/penumbra-zone/penumbra/pull/3751. --- docs/guide/src/dev/rpc.md | 6 +++--- docs/guide/src/pcli/transaction.md | 2 +- docs/guide/src/pclientd/build_transaction.md | 10 +++++----- docs/guide/src/pclientd/rpc.md | 12 ++++++------ 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/guide/src/dev/rpc.md b/docs/guide/src/dev/rpc.md index 130991dc55..3f7a76b0b0 100644 --- a/docs/guide/src/dev/rpc.md +++ b/docs/guide/src/dev/rpc.md @@ -21,7 +21,7 @@ to a local devnet. The [Buf Studio](https://studio.buf.build) webapp provides a polished GUI and [comprehensive documentation](https://buf.build/docs/bsr/studio). However, a significant limitation for use with Penumbra is that it lacks -support for streaming requests, such as [`penumbra.client.v1alpha1.CompactBlockRangeRequest`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.client.v1alpha1#penumbra.client.v1alpha1.CompactBlockRangeRequest). +support for streaming requests, such as [`penumbra.core.component.compact_block.v1.CompactBlockRangeRequest`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.core.component.compact_block.v1#penumbra.core.component.compact_block.v1.CompactBlockRangeRequest). To get started with Buf Studio, you can use the publicly available gRPC endpoint from the testnet deployments run by Penumbra Labs: @@ -37,11 +37,11 @@ Click **Send** to submit the request and view response data in the right-hand pa Regardless of which interface you choose, you can connect to an instance of `pd` running on your machine, which can be useful while adding new features. -First, make sure you've [joined a testnet](https://guide.penumbra.zone/main/pd/join-testnet.html) +First, make sure you've [joined a testnet](../pd/join-testnet.md) by setting up a node on your local machine. Once it's running, you can connect directly to the pd port via `http://localhost:8080`. -Alternatively, you can use `pclientd`. First, make sure you've [configured pclientd locally](https://guide.penumbra.zone/main/pcli/pclientd.html) +Alternatively, you can use `pclientd`. First, make sure you've [configured pclientd locally](../pclientd/configure.md) with your full viewing key. Once it's running, you can connect directly to the pclient port via `http://localhost:8081`. diff --git a/docs/guide/src/pcli/transaction.md b/docs/guide/src/pcli/transaction.md index 31131eb59d..c078dc4ddb 100644 --- a/docs/guide/src/pcli/transaction.md +++ b/docs/guide/src/pcli/transaction.md @@ -221,4 +221,4 @@ pcli tx withdraw --to --channel 5gm --timeout-hei Unfortunately the CLI tooling for Osmosis is cumbersome. For now, use `rly` as a user agent for the Osmosis testnet, as described in the [IBC dev docs](../dev/ibc.md). -[Osmosis testnet]: https://docs.osmosis.zone/networks/join-testnet/ +[Osmosis testnet]: https://docs.osmosis.zone/overview/endpoints#testnet-networks diff --git a/docs/guide/src/pclientd/build_transaction.md b/docs/guide/src/pclientd/build_transaction.md index 3189553539..b3ffcc9c35 100644 --- a/docs/guide/src/pclientd/build_transaction.md +++ b/docs/guide/src/pclientd/build_transaction.md @@ -4,27 +4,27 @@ Using the view and custody services to construct a transaction has four steps. ## Plan the Transaction -Using the [`TransactionPlanner`](https://buf.build/penumbra-zone/penumbra/docs/60489c71c3b64f179b2537b24a587abe:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.TransactionPlanner) RPC in the view service, compute a `TransactionPlan`. +Using the [`TransactionPlanner`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.TransactionPlanner) RPC in the view service, compute a `TransactionPlan`. This RPC translates a general intent, like "send these tokens to this address" into a fully deterministic plan of the exact transaction, with all spends and outputs, all blinding factors selected, and so on. ## Authorize the Transaction With a `TransactionPlan` in hand, use the -[`Authorize`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.custody.v1alpha1#penumbra.custody.v1alpha1.CustodyProtocolService.Authorize) +[`Authorize`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.custody.v1#penumbra.custody.v1.CustodyService.Authorize) RPC to request authorization of the transaction from the custody service. Note that authorization happens on the cleartext transaction _plan_, not the shielded transaction, so that the custodian can inspect the transaction before signing it. ## Build the Transaction -With the `TransactionPlan` and `AuthorizationData` in hand, use the [`WitnessAndBuild`](https://buf.build/penumbra-zone/penumbra/docs/60489c71c3b64f179b2537b24a587abe:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.WitnessAndBuild) RPC to have the view service build the transaction, using the latest witness data to construct the ZK proofs. +With the `TransactionPlan` and `AuthorizationData` in hand, use the [`WitnessAndBuild`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.WitnessAndBuild) RPC to have the view service build the transaction, using the latest witness data to construct the ZK proofs. ## Broadcast the Transaction -With the resulting shielded `Transaction` complete, use the [`BroadcastTransaction`](https://buf.build/penumbra-zone/penumbra/docs/60489c71c3b64f179b2537b24a587abe:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.BroadcastTransaction) +With the resulting shielded `Transaction` complete, use the [`BroadcastTransaction`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.BroadcastTransaction) request to broadcast the transaction to the network. The `await_detection` parameter will wait for the transaction to be confirmed on-chain. Using `await_detection` is a simple way to ensure that different -transactions can't conflict with each other. \ No newline at end of file +transactions can't conflict with each other. diff --git a/docs/guide/src/pclientd/rpc.md b/docs/guide/src/pclientd/rpc.md index 3f4bae8cec..53c54ac8a6 100644 --- a/docs/guide/src/pclientd/rpc.md +++ b/docs/guide/src/pclientd/rpc.md @@ -10,7 +10,7 @@ link is preconfigured to make requests against a local `pclientd` instance with the default `bind_addr`, but can be aimed at any endpoint. [GRPCUI]: https://github.com/fullstorydev/grpcui -[buf-studio]: https://buf.build/studio/penumbra-zone/penumbra/penumbra.core.app.v1alpha1.QueryService/AppParameters?selectedProtocol=grpc-web&target=http%3A%2F%2Flocalhost%3A8081 +[buf-studio]: https://buf.build/studio/penumbra-zone/penumbra/penumbra.core.app.v1.QueryService/AppParameters?selectedProtocol=grpc-web&target=http%3A%2F%2Flocalhost%3A8081 ## Accessing public chain state @@ -21,21 +21,21 @@ Documentation on these RPCs is available on Buf.build; follow the links in Buf S ## Accessing private chain state -Access to a user's private state is provided by the [`ViewService` RPC](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService). +Access to a user's private state is provided by the [`ViewService` RPC](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService). In addition to ordinary queries, like -[`Balances`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.Balances), +[`Balances`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.Balances), which gets a user's balances by account, the RPC also contains utility methods that allow computations involving cryptography. For instance, the -[`AddressByIndex`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.AddressByIndex) +[`AddressByIndex`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.AddressByIndex) request computes a public address from an account index, and the -[`IndexByAddress`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1alpha1#penumbra.view.v1alpha1.ViewProtocolService.IndexByAddress) +[`IndexByAddress`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.view.v1#penumbra.view.v1.ViewService.IndexByAddress) request decrypts an address to its private index. Finally, the view service can plan and build transactions, as described in [the next section](./build_transaction.md). ## Requesting transaction authorization -If `pclientd` was configured in custody mode, it exposes a [`CustodyService`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.custody.v1alpha1#penumbra.custody.v1alpha1.CustodyProtocolService). +If `pclientd` was configured in custody mode, it exposes a [`CustodyService`](https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.custody.v1#penumbra.custody.v1.CustodyService). This allows authorization of a `TransactionPlan`, as described in [the next section](./build_transaction.md).