Update top-level documentation

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.

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.