update docs structure

pages/_meta.json

@@ -1,8 +1,8 @@
 {
   "index": "Welcome to Penumbra",
   "interchain-privacy": "Interchain Privacy",
-  "shielded-dex": "The Penumbra DEX",
-  "shielded-staking": "Shielded Staking",
+  "dex": "The Penumbra DEX",
+  "staking": "Shielded Staking",
   "gov": "Decentralized Governance",
   "disclosure": "Selective Disclosure",
   "web": "Using Penumbra on the web",
@@ -12,6 +12,6 @@
   "relayers": "Running relayers",
   "lp": "Providing Liquidity",
   "dev": "Development",
-  "risks": "Risks",
-  "resources": "Resources"
-}
+  "resources": "Resources",
+  "risks": "Risks"
+}

pages/disclosure.mdx

@@ -0,0 +1,3 @@
+---
+title: 'Selective Disclosure'
+---

pages/frontend.md

@@ -3,11 +3,23 @@ frontends.  This allows different frontend codebases to focus on different user
 profiles and ensures that no single frontend deployment or codebase has control
 over users' access to the protocol.
 
-Penumbra wallets like [Prax] sync, scan, decrypt, and locally index user data. When users connect to a frontend, the wallet acts as a "personal RPC", granting that frontend access to the user's private data.
+Penumbra wallets like [Prax] sync, scan, decrypt, and locally index user data.
+When users connect to a frontend, the wallet acts as a "personal RPC", granting
+that frontend access to the user's private data.
 
-This chapter has information about deploying a Penumbra frontend, for users who do not wish to rely on existing third-party frontends:
+This chapter has information about deploying various open-source Penumbra
+frontends, for users who do not wish to rely on existing third-party frontends:
 
 - [**Minifront**](./frontend/minifront.md): the minimal, embeddable static-site
-  frontend that runs entirely on the end-user device. A (possibly outdated) copy of Minifront is embedded in every single Penumbra fullnode and served on the RPC endpoint, but it can also be hosted standalone.
+frontend that runs entirely on the end-user device. A (possibly outdated) copy
+of Minifront is embedded in every single Penumbra fullnode and served on the RPC
+endpoint, but it can also be hosted standalone.
+
+- [**Void.Vote**](./frontend/void-vote.mdx): a governance-focused frontend that
+allows viewing and voting on governance proposals.
+
+- [**Cuiloa**](./frontend/cuiloa.mdx): a developer-focused block explorer showing raw block, transaction, and event data.
+
+- [**DEX Explorer**](./frontend/dex-explorer.mdx): a DEX-focused explorer rendering DEX data.
 
 [Prax]: https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe

pages/frontend/_meta.json

@@ -1,6 +1,6 @@
 {
     "minifront": "Minifront",
-    "voidvote": "Void.Vote",
+    "void-vote": "Void.Vote",
     "cuiloa": "Cuiloa",
-    "dex_explorer": "Dex Explorer"
+    "dex-explorer": "DEX Explorer"
 }

pages/frontend/cuiloa.mdx

@@ -0,0 +1,9 @@
+---
+title: 'Cuiloa'
+---
+
+import { Callout, Steps } from 'nextra/components'
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>

pages/frontend/dex-explorer.mdx

@@ -0,0 +1,9 @@
+---
+title: 'DEX Explorer'
+---
+
+import { Callout, Steps } from 'nextra/components'
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>

pages/frontend/void-vote.mdx

@@ -0,0 +1,9 @@
+---
+title: 'Void.Vote'
+---
+
+import { Callout, Steps } from 'nextra/components'
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>

pages/gov.mdx

@@ -0,0 +1,3 @@
+---
+title: 'Decentralized Governance'
+---

pages/index.mdx

@@ -5,64 +5,9 @@ decentralized exchange for the Cosmos and beyond. Penumbra brings privacy to
 IBC, allowing anyone to shield any IBC asset just by transferring it into
 Penumbra's multi-asset shielded pool.  Within Penumbra, users can transact,
 stake, swap, or marketmake without broadcasting their personal information to
-the world.
+the world.  Unlike a transparent chain, where all information is public,
+Penumbra is end-to-end encrypted. 
 
 <picture>
   <img src="./images/interchain-shielded-pool.jpg" />
 </picture>
-
-Unlike a transparent chain, where all information is public, Penumbra is
-end-to-end encrypted. 
-
-## Using Penumbra on the web
-
-The easiest way to get started using Penumbra is with the [Prax Wallet] web
-extension.  The web extension runs entirely locally, and contains an
-embedded ultralight node that syncs and decrypts only the data visible to your
-wallet.  Websites can request to connect to your wallet and query your data.
-
-The [_Using Penumbra on the web_](./web.md) chapter describes how to use
-Penumbra on the web.
-
-## Using Penumbra from the command line
-
-Penumbra also has a command-line client, `pcli`.  Some protocol features, such
-as threshold custody for shielded multisigs, do not yet have support in web
-frontends and are only accessible via the command line.
-
-The [_Using Penumbra from the command line_](./pcli.md) chapter describes how to
-use `pcli`.
-
-## Running a node
-
-Running a node is not necessary to use the protocol. Both the web extension and
-`pcli` are designed to operate with any RPC endpoint. However, we've tried to
-make it as easy as possible to run nodes so that users can host their own RPC.
-
-There are two kinds of Penumbra nodes:
-
-* Penumbra fullnodes run `pd` and `cometbft` to synchronize and verify the entire chain state, as described in [_Running a node: `pd`_](./node/pd.md).
-* Penumbra ultralight nodes run `pclientd` to scan, decrypt, and synchronize a specific wallet's data, as well as build and sign transactions, as described in [_Running a node: `pclientd`_](./node/pclientd.md).
-
-The web extension and `pcli` embed the view and custody functionality provided
-by `pclientd`, so it is not necessary to run `pclientd` to use them. Instead,
-`pclientd` is intended to act as a local RPC for programmatic tooling (e.g.,
-trading bots) not written in Rust that cannot easily embed the code for working
-with Penumbra's shielded cryptography.
-
-## Participating in development
-
-Penumbra is a decentralized, open-source protocol, built in public.
-
-The [_Participating in development_](./dev.md) chapter has developer
-documentation for working on the protocol itself.
-
-## Resources
-
-The [_Resources_](./resources.md) chapter has links to other resources about the Penumbra protocol.
-
-
-[protocol]: https://protocol.penumbra.zone
-[rustdoc]: https://rustdoc.penumbra.zone
-[Penumbra]: https://github.com/penumbra-zone/penumbra
-[Prax Wallet]: https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe

pages/lp.mdx

@@ -0,0 +1,101 @@
+---
+title: 'Providing Liquidity'
+---
+
+import { Callout, Steps } from 'nextra/components'
+
+<Callout type="warning" emoji="⚠️">
+  Liquidity provision involves risk. This section describes how to use software tools, but your trading strategies are solely up to you.
+</Callout>
+
+Penumbra's DEX is built around order-book-style concentrated liquidity.
+Liquidity positions are constant-sum AMMs, offering to trade between assets at a
+fixed price.  Each position is its own independent AMM with its own fee tier,
+and as described in the [DEX chapter](./dex.mdx), the DEX engine indexes active
+liquidity positions and sorts them by price, then traverses the liquidity graph
+to optimally fill trades. 
+
+Liquidity positions are public, but are created out of and withdrawn back to
+Penumbra's shielded pool. Thus, while everyone can see the aggregate state of
+the market, they cannot see which positions are controlled by which accounts, or
+view an account's trading history or strategy (unless they have access to that
+account's viewing key).
+
+The lifecycle of a liquidity position is:
+<Steps>
+
+### Opened
+
+On creation (by a [`PositionOpen` action][poa]), the position is in the "opened" state, in which it is actively
+providing liquidity to the DEX engine. Trade executions against the position
+update its reserves.
+
+### Closed
+
+An opened position can be closed explicitly, by a user-submitted
+[`PositionClose` action][pca], or implicitly by the chain, if the [`Position`][position_proto]'s
+`close_on_fill` field is set to `true` and the position's reserves were completely consumed by a trade.
+
+When a position is closed, it no longer provides liquidity to the DEX and becomes "inert".
+
+### Withdrawn
+
+Closing a position does not immediately withdraw funds, because Penumbra
+transactions (like any ZK transaction model) are early-binding: the prover must
+know the state transition they prove knowledge of, and they cannot know the
+final reserves with certainty until after the position has been deactivated.
+
+Instead, reserves are explicitly withdrawn following closure. 
+
+</Steps>
+
+Control over liquidity positions is recorded using LPNFTs that track both the
+position ID and its state. This allows using the transaction's value balance mechanism to
+track the state machine:
+
+- the `PositionOpen` action consumes the initial reserves and produces an "opened-LPNFT";
+- the `PositionClose` action consumes an opened-LPNFT and produces a "closed-LPNFT";
+- the `PositionWithdraw` action consumes a closed- or withdrawn-LPNFT and produces a withdrawn-LPNFT with an incremented withdrawal sequence number and any reserves withdrawn from the position.
+
+The protocol supports withdrawing from a position multiple times, though there
+is currently no reason to do this as the reserves are consumed on the first
+withdrawal.  
+
+This design opens interesting possibilities not possible on a conventional DEX:
+
+- **Block-scoped JIT liquidity**: a position can be opened and closed in the same transaction. As the opening is processed in a batch in the first phase of the DEX `EndBlock` handler and the closure is processed in a batch following all trade executions, this allows a liquidity provider to quote a price and be guaranteed that it will only be valid for a single block's batch executions.
+
+- **Replicating Market Makers**: the payoff function of any CFMM can be approximated via constant-sum AMMs, allowing market makers to replicate whatever trading function they want. This functionality is implemented in `pcli` for approximating the payoff of an `xy=k` (UniV2) curve.
+
+[poa]: https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.core.component.dex.v1#penumbra.core.component.dex.v1.PositionOpen
+[pca]: https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.core.component.dex.v1#penumbra.core.component.dex.v1.PositionClose
+[position_proto]: https://buf.build/penumbra-zone/penumbra/docs/main:penumbra.core.component.dex.v1#penumbra.core.component.dex.v1.Position
+
+## Managing Liquidity Positions
+<Callout type="info" emoji="ℹ️">
+  There is currently no GUI support for managing liquidity positions.
+</Callout>
+
+### Individual limit orders with `pcli`
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>
+
+### Payoff replication with `pcli`
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>
+
+### Programmatic access with `pclientd`
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>
+
+### Managing liquidity with Hummingbot
+
+<Callout emoji="💡">
+This section is incomplete. You can help by expanding it!
+</Callout>

pages/node/relayer/hermes.md → pages/relayers.md

@@ -1,8 +1,15 @@
-# Hermes and Penumbra
+In order for Penumbra to interact with the broader [Cosmos] ecosystem, the community must
+run [IBC] relaying software, to transmit packets between chains. Relaying is by design
+permissionless. Some examples of relayer software are:
+
+  * [hermes], maintained by [Informal Systems][Informal]
+  * the Go [relayer], maintained by [Strangelove]
+
+This guide provides a tutorial for setting up Hermes for use with Penumbra.
 
-## Using a compatible Hermes version
 Penumbra-compatibility exists in a fork of the Hermes software, available at:
 [https://github.com/penumbra-zone/hermes](https://github.com/penumbra-zone/hermes).
+To build and install it:
 
 ```shell
 git clone https://github.com/penumbra-zone/hermes
@@ -71,4 +78,9 @@ Consult the official Hermes docs for [running in production](https://hermes.info
 as well as the [telemetry guide](https://hermes.informal.systems/documentation/telemetry/index.html).
 You'll need to communicate the channels that you maintain to the community. How you do so is up to you.
 
+[Cosmos]: https://cosmos.network
+[IBC]: https://ibc.cosmos.network
 [hermes]: https://hermes.informal.systems
+[relayer]: https://github.com/cosmos/relayer
+[Informal]: https://informal.systems
+[Strangelove]: https://strange.love

pages/resources.md

@@ -1,29 +1,14 @@
 This page links to various resources that are helpful for working with and
 understanding Penumbra.
 
-### Getting started
-
   * The primary communication hub is our [Discord]; click the link to join the
 discussion there.
-  * Documentation on how to use `pcli`, how to run `pd`, and how to do development can be found at [guide.penumbra.zone][guide].
 
 ### For developers
 
   * The protocol specification is rendered at [protocol.penumbra.zone][protocol].
   * The API documentation is rendered at [rustdoc.penumbra.zone][rustdoc].
   * The protobuf documentation is rendered at [buf.build/penumbra-zone/penumbra][protobuf].
-  * The current sprint progress is tracked on a [Github project board](https://github.com/orgs/penumbra-zone/projects/23/views/3) (hint: 🔖 this).
-  * The development history by testnet can be found at [another Github board](https://github.com/orgs/penumbra-zone/projects/17).
-
-## Tools
-
-  * Public testnet `pd` endpoint: `https://grpc.testnet.penumbra.zone` This URL won't work in a web browser, as the service speaks gRPC.
-  * Public testnet `cometbft` API endpoint: [https://rpc.testnet.penumbra.zone](https://rpc.testnet.penumbra.zone)
-  * Block explorer: [https://cuiloa.testnet.penumbra.zone](https://cuiloa.testnet.penumbra.zone)
-  * Metrics: [https://grafana.testnet.penumbra.zone](https://grafana.testnet.penumbra.zone)
-
-For all those URLs, there's also a `preview` version available, e.g. `https://grpc.testnet-preview.penumbra.zone`,
-that tracks the latest tip of the git repo, rather than the current public testnet.
 
 [Discord]: https://discord.gg/hKvkrqa3zC
 [protocol]: https://protocol.penumbra.zone

pages/staking.mdx

@@ -0,0 +1,3 @@
+---
+title: 'Shielded Staking'
+---

theme.config.jsx

@@ -8,12 +8,6 @@ export default {
   },
   docsRepositoryBase: 'https://github.com/penumbra-zone/guide',
 
-  useNextSeoProps() {
-    return {
-      titleTemplate: '%s - Penumbra Guide'
-    }
-  }
-  // ... other theme options
   useNextSeoProps() {
     return {
       // Set "Penumbra Guide" in page titles, rather than default "Nextra".