From 078ed16f446042b255e69caa3c5052074773ecac Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Wed, 24 Jul 2024 02:01:48 -0400 Subject: [PATCH] update docs structure --- pages/_meta.json | 10 +- pages/dex.mdx | 0 pages/disclosure.mdx | 3 + pages/frontend.md | 18 +++- pages/frontend/_meta.json | 4 +- pages/frontend/cuiloa.mdx | 9 ++ pages/frontend/dex-explorer.mdx | 9 ++ pages/frontend/void-vote.mdx | 9 ++ pages/gov.mdx | 3 + pages/index.mdx | 59 +--------- pages/interchain-privacy.mdx | 0 pages/lp.mdx | 101 ++++++++++++++++++ pages/node/relayer.md | 17 --- pages/{node/relayer/hermes.md => relayers.md} | 16 ++- pages/resources.md | 15 --- pages/staking.mdx | 3 + theme.config.jsx | 6 -- 17 files changed, 175 insertions(+), 107 deletions(-) create mode 100644 pages/dex.mdx create mode 100644 pages/disclosure.mdx create mode 100644 pages/frontend/cuiloa.mdx create mode 100644 pages/frontend/dex-explorer.mdx create mode 100644 pages/frontend/void-vote.mdx create mode 100644 pages/gov.mdx create mode 100644 pages/interchain-privacy.mdx create mode 100644 pages/lp.mdx delete mode 100644 pages/node/relayer.md rename pages/{node/relayer/hermes.md => relayers.md} (84%) create mode 100644 pages/staking.mdx diff --git a/pages/_meta.json b/pages/_meta.json index 3c83b8a..6708bee 100644 --- a/pages/_meta.json +++ b/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" +} \ No newline at end of file diff --git a/pages/dex.mdx b/pages/dex.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/disclosure.mdx b/pages/disclosure.mdx new file mode 100644 index 0000000..dfac79c --- /dev/null +++ b/pages/disclosure.mdx @@ -0,0 +1,3 @@ +--- +title: 'Selective Disclosure' +--- \ No newline at end of file diff --git a/pages/frontend.md b/pages/frontend.md index 4094383..616dcaf 100644 --- a/pages/frontend.md +++ b/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 \ No newline at end of file diff --git a/pages/frontend/_meta.json b/pages/frontend/_meta.json index 2f6516d..3365493 100644 --- a/pages/frontend/_meta.json +++ b/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" } \ No newline at end of file diff --git a/pages/frontend/cuiloa.mdx b/pages/frontend/cuiloa.mdx new file mode 100644 index 0000000..129e56b --- /dev/null +++ b/pages/frontend/cuiloa.mdx @@ -0,0 +1,9 @@ +--- +title: 'Cuiloa' +--- + +import { Callout, Steps } from 'nextra/components' + + +This section is incomplete. You can help by expanding it! + \ No newline at end of file diff --git a/pages/frontend/dex-explorer.mdx b/pages/frontend/dex-explorer.mdx new file mode 100644 index 0000000..a60a9d2 --- /dev/null +++ b/pages/frontend/dex-explorer.mdx @@ -0,0 +1,9 @@ +--- +title: 'DEX Explorer' +--- + +import { Callout, Steps } from 'nextra/components' + + +This section is incomplete. You can help by expanding it! + \ No newline at end of file diff --git a/pages/frontend/void-vote.mdx b/pages/frontend/void-vote.mdx new file mode 100644 index 0000000..e57d9c3 --- /dev/null +++ b/pages/frontend/void-vote.mdx @@ -0,0 +1,9 @@ +--- +title: 'Void.Vote' +--- + +import { Callout, Steps } from 'nextra/components' + + +This section is incomplete. You can help by expanding it! + \ No newline at end of file diff --git a/pages/gov.mdx b/pages/gov.mdx new file mode 100644 index 0000000..1052ead --- /dev/null +++ b/pages/gov.mdx @@ -0,0 +1,3 @@ +--- +title: 'Decentralized Governance' +--- \ No newline at end of file diff --git a/pages/index.mdx b/pages/index.mdx index ab3a5d1..3d6f084 100644 --- a/pages/index.mdx +++ b/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. - -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 diff --git a/pages/interchain-privacy.mdx b/pages/interchain-privacy.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/lp.mdx b/pages/lp.mdx new file mode 100644 index 0000000..9700769 --- /dev/null +++ b/pages/lp.mdx @@ -0,0 +1,101 @@ +--- +title: 'Providing Liquidity' +--- + +import { Callout, Steps } from 'nextra/components' + + + Liquidity provision involves risk. This section describes how to use software tools, but your trading strategies are solely up to you. + + +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: + + +### 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. + + + +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 + + There is currently no GUI support for managing liquidity positions. + + +### Individual limit orders with `pcli` + + +This section is incomplete. You can help by expanding it! + + +### Payoff replication with `pcli` + + +This section is incomplete. You can help by expanding it! + + +### Programmatic access with `pclientd` + + +This section is incomplete. You can help by expanding it! + + +### Managing liquidity with Hummingbot + + +This section is incomplete. You can help by expanding it! + diff --git a/pages/node/relayer.md b/pages/node/relayer.md deleted file mode 100644 index 038573e..0000000 --- a/pages/node/relayer.md +++ /dev/null @@ -1,17 +0,0 @@ -# IBC relayer - -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] - * [relayer], maintained by [Strangelove] - -This guide provides a tutorial for [setting up Hermes for use with Penumbra](relayer/hermes.md). - -[Cosmos]: https://cosmos.network -[IBC]: https://ibc.cosmos.network -[hermes]: https://hermes.informal.systems -[relayer]: https://github.com/cosmos/relayer -[Informal Systems]: https://informal.systems -[Strangelove]: https://strange.love diff --git a/pages/node/relayer/hermes.md b/pages/relayers.md similarity index 84% rename from pages/node/relayer/hermes.md rename to pages/relayers.md index 82b9308..5352fdb 100644 --- a/pages/node/relayer/hermes.md +++ b/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 diff --git a/pages/resources.md b/pages/resources.md index 916a2c8..6110845 100644 --- a/pages/resources.md +++ b/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 diff --git a/pages/staking.mdx b/pages/staking.mdx new file mode 100644 index 0000000..e10afaf --- /dev/null +++ b/pages/staking.mdx @@ -0,0 +1,3 @@ +--- +title: 'Shielded Staking' +--- \ No newline at end of file diff --git a/theme.config.jsx b/theme.config.jsx index d2a11a6..ff33c0b 100644 --- a/theme.config.jsx +++ b/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".