From 9243115eebba349fb93dfc34d1aac5ccee43f443 Mon Sep 17 00:00:00 2001 From: Ethan Frey Date: Wed, 28 Jun 2023 22:44:50 +0200 Subject: [PATCH] Update top-level documentation --- docs/README.md | 21 +++++++++++------ docs/UseCases.md | 60 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 58 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index b87354e4..95575300 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,8 @@ simplifications used for MVP (testnet) or v1 (production-ready, feature-limited) as footnotes in the documents. ```mermaid +%%{init: {'theme': 'forest'}}%% flowchart TD - %%{init: {'theme': 'forest'}}%% - subgraph Osmosis A{{$OSMO}} -- User Deposit --> B(Vault); B -- $OSMO --> C(Local Staker); @@ -25,18 +24,21 @@ flowchart TD end subgraph Juno + I(Price Oracle) -- price feed --> M; + J(Price Oracle) -- price feed --> N; + M(Osmosis Converter) -- virtual stake --> O(Virtual Staking 1); N(Akash Converter) -- virtual stake --> P(Virtual Staking 2); O & P -- $JUNO --> Q[Native Staking]; end - G -. IBC .-> R; + G -. IBC .-> T; subgraph Stargaze - R{{Osmosis Receiver}} -- virtual stake --> S(Virtual Staking); - S -- $STARS --> T[Native Staking]; + S(Price Oracle) -- price feed --> T; + T{{Osmosis Converter}} -- virtual stake --> U(Virtual Staking); + U -- $STARS --> V[Native Staking]; end - ``` You can get a good overview of the whole system flow in the above diagram. @@ -94,6 +96,9 @@ This max cap can be updated by governance as needed, so if a lot more (or less) tokens are staked, the max cap of the providers can be updated with a gov vote to keep them in reasonable limits. +Please [look at the use cases](./UseCases.md) to see the use of max cap in some example scenarios +to gain a better intuition of how it works. + ### Failure Modes There are three main failure modes to consider: @@ -174,7 +179,9 @@ such a condition without the Validators fault. It would require hacks deep into (not the custom ABCI app) and a governance upgrade to direct the validators to use it, and we generally consider this unlikely (it has never been observed in 4+ years of the Cosmos). -## Definitions +## Glossary + +Some common terms are defined here, which may be used throughout the documentation. - **Pairing** - a trust relationship between two chains, such that one promises to lock up slashable stake, while the other leverages this promise to issue validation power in the dPoS system. diff --git a/docs/UseCases.md b/docs/UseCases.md index 422e16e7..d44eeb47 100644 --- a/docs/UseCases.md +++ b/docs/UseCases.md @@ -1,5 +1,17 @@ # Use Cases +We assume each chain has a native staking token denom, with some quantity (could be 1 or 1,000,000,000). +This is the initial token to start the chain with. Each provider chain that connects gets a maximum of X virtual tokens, defined by consumer govenance +when authorizing the new provider. The ratio between the amount of native tokens and the max cap +of virtual tokens on each provider is a key element in defining the various security models. + +To make these diagrams easier to read, I will normalize each chain has 100 native tokens, and label the +connections on how many virtual tokens they are authorized to mint. Thus, a connection with 100 could +exert the same amount of voting power as all native stakers. A connection with 10 could exert 10% of the +power of native stakers, and a connection of 1000 could exert 10 times the power of native stakers. + +(Note this is not clear percentages. 40 / (100 + 40) = 28.5% of the total power in the hands of that provider) + ## Sibling Chains Two chains of similar size want to support each other. @@ -9,8 +21,8 @@ larger -> smaller has more weight than smaller -> larger. ```mermaid flowchart LR %%{init: {'theme': 'forest'}}%% - A(Juno) -- 40% --> B(Star); - B -- 20% --> A; + A(Juno) -- 40 --> B(Star); + B -- 20 --> A; ``` ## Full Mesh @@ -27,14 +39,19 @@ so the weights are proportional to their relative market caps. ```mermaid flowchart LR %%{init: {'theme': 'forest'}}%% - A(OSMO) == 50% ==> B(Juno); - A == 50% ==> C(Akash); - B -- 20% --> C; - C -- 20% --> B; - B -- 10% --> A; - C -- 10% --> A; + A(OSMO) == 60 ==> B(Juno); + A == 60 ==> C(Akash); + B -- 20 --> C; + C -- 20 --> B; + B -- 10 --> A; + C -- 10 --> A; ``` +You could analyze Juno in this example: +100 native, 60 from Osmosis, 20 from Akash = 180 total. +Osmosis hits the 1/3 threshold exactly, while native tokens still hold the majority in the governance votes. +Does that make sense, should this be adjusted? + ## DAOs migrating to own chain A number of Juno DAOs launching their own chains. They want to inherit most of their security from Juno, @@ -43,11 +60,13 @@ but keep governance to their own token. ```mermaid flowchart TD %%{init: {'theme': 'forest'}}%% - Juno -- 75%, no gov --> DAO1; - Juno -- 75%, no gov --> DAO2; - Juno -- 75%, no gov --> DAO3; + Juno -- 300, no gov --> DAO1; + Juno -- 300, no gov --> DAO2; + Juno -- 300, no gov --> DAO3; ``` +Note < 1/3 power in the native token, so all PoS security relies on Juno (while all governance security relies on the DAO token) + ## Almost Replicated Security Mesh Security is not ICSv1 "Replicated Security". We do not map validators from provider to consumer, but rather delegators. @@ -62,9 +81,14 @@ of the chain, including gov votes. The end effect is the new chain is almost 100 ```mermaid flowchart TD %%{init: {'theme': 'forest'}}%% - Juno -- 99%, gov --> Eve; + Juno -- 10000, gov --> Eve; ``` +The native token is just used in bootstrapping, to make setup and deployment simple. +However, at around 1% of the power, it quickly becomes irrelevant, and makes this a close approximation of "replicated security". +You could just reduce the native supply to 1 solo token and then this gets like 99.9999% replicated security, but with a much +clearer setup phase. + ## Credibly Neutral Common Good There are some items that should be neutral or independent of multiple chains, @@ -74,8 +98,12 @@ control the staking and governance, even without any native staking power. ```mermaid flowchart TD %%{init: {'theme': 'forest'}}%% - A(OSMO) --> |25%| N[Name Service]; - B(Juno) -- 25% --> N; - C(Stargaze) -- 25% --> N; - D(Cosmos Hub) -- 25% --> N; + A(OSMO) --> |10000| N[Name Service]; + B(Juno) -- 10000 --> N; + C(Stargaze) -- 10000 --> N; + D(Cosmos Hub) -- 10000 --> N; ``` + +All participating chains have the same power. The native token is almost irrelevant (100 / 40100 = 0.25% of the power) +and can be ignored. It is essential, however, for bootstrapping and getting up the chain until all the provider chains have +connected and sufficient amount of cross-stakers have joined from those chains.