From 1bc45ad61d5123f2b89f0674b7454521a994ca6e Mon Sep 17 00:00:00 2001
From: Conor Schaefer <conorsch@users.noreply.github.com>
Date: Mon, 21 Oct 2024 13:36:44 -0700
Subject: [PATCH] docs: add testnet service endpoints (#37)

Adds a new dev docs page that provides details on accessing the
currently running testnet. We don't yet have a solution for a faucet, so
the docs will need to be updated to be useful to external developers,
but I'm submitting this PR anyway because this information is necessary,
but not sufficient.

Refs https://github.com/penumbra-zone/guide/issues/35
---
 pages/dev/_meta.json |  1 +
 pages/dev/testnet.md | 80 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 pages/dev/testnet.md

diff --git a/pages/dev/_meta.json b/pages/dev/_meta.json
index 7d097ba..aa06e66 100644
--- a/pages/dev/_meta.json
+++ b/pages/dev/_meta.json
@@ -1,6 +1,7 @@
 {
   "dev-env": "Developer environment",
   "devnet-quickstart": "Devnet quickstart",
+  "testnet": "Testnet",
   "sql": "Working with SQLite",
   "docs": "Building documentation",
   "protobuf": "Building protobuf",
diff --git a/pages/dev/testnet.md b/pages/dev/testnet.md
new file mode 100644
index 0000000..19589c7
--- /dev/null
+++ b/pages/dev/testnet.md
@@ -0,0 +1,80 @@
+# Testnet
+
+There's a long-running testnet chain available, intended for developers
+to test code and practice integrating their software with the Penumbra stack.
+
+## Services available
+
+The following public services are available:
+
+| URL | Service |
+| --- | --- |
+| https://testnet.plinfra.net | primary `pd` gRPC endpoint, running most recently released stable tag from the [protocol repo] |
+| https://testnet-preview.plinfra.net | secondary `pd` gRPC endpoint, running the most recent commit on the `main` branch in the [protocol repo] |
+| https://dex-explorer.testnet.plinfra.net | a [DEX explorer](https://github.com/penumbra-zone/dex-explorer) instance, showing testnet market activity |
+| https://cuiloa.testnet.plinfra.net | a block explorer, based on [cuiloa](https://github.com/penumbra-zone/cuiloa) |
+
+## Joining the testnet
+
+You can run a node on the public testnet like so:
+
+```shell
+# clean up any pre-existing network state
+cargo run --release --bin pd -- network unsafe-reset-all
+# generate network configs for the testnet chain
+cargo run --release --bin pd -- network join http://testnet.plinfra.net:26657
+```
+
+After that, if you've set up the [Penumbra developer environment](./dev-env.md),
+you can run a fullnode locally via:
+
+```shell
+just dev
+```
+
+For a more persistent setup, consult the [tutorial on running a node](../node/pd/running-node.md).
+
+## Running `pcli`
+
+To interact with the chain, configure a wallet pointing at the testnet node:
+
+```shell
+cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view reset
+cargo run --release --bin pcli -- init --grpc-url https://testnet.plinfra.net soft-kms generate
+# or, to reuse an existing seed phrase:
+cargo run --release --bin pcli -- init --grpc-url https://testnet.plinfra.net soft-kms import-phrase
+```
+
+and then pass the `--home` flag to any commands you run to point `pcli` at your local node, e.g.,
+
+```shell
+cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view balance
+```
+
+You'll be able to run queries like `pcli query validator list`, but by default you won't be able
+to create transactions, as an empty wallet will lack funds to pay gas fees.
+
+
+## Using the testnet faucet
+
+There's currently no faucet running for the Penumbra testnet chain, but check back soon for details.
+
+<!--
+TODO:
+There's no instance of Galileo running yet, but there could be.
+
+To obtain funds for your testnet wallet, first gather the address:
+
+```shell
+cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view address
+```
+
+Then visit the `#testnet-faucet` channel in the project Discord, and paste your address.
+A bot will send a small amount of funds to your address, which should be visible within a few minutes, via:
+
+```shell
+cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view balance
+```
+-->
+
+[protocol repo]: https://github.com/penumbra-zone/penumbra