Initial Commit with docs

.gitignore

@@ -0,0 +1,28 @@
+# macOS
+.DS_Store
+
+# Text file backups
+**/*.rs.bk
+
+# Build results
+target/
+
+# IDEs
+.vscode/
+.idea/
+*.iml
+
+# Auto-gen
+.cargo-ok
+
+# Build artifacts
+*.wasm
+hash.txt
+contracts.txt
+artifacts/
+
+# code coverage
+tarpaulin-report.*
+
+packages/*/schema
+contracts/*/schema

LICENSE

@@ -0,0 +1,23 @@
+Mesh Security: Proof of Stake redesigned for the Interchain Era
+
+MIT License
+
+Copyright (c) 2023 Confio GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,19 @@
+# Mesh Security
+
+An implementation of Sunny's [Mesh Security](https://youtu.be/Z2ZBKo9-iRs?t=4937) talk from
+Cosmoverse 2022.
+
+Please check out the [architectural documentation](./docs/README.md), which gives a
+thorough view of all the components in a completed system.
+
+## Status
+
+This is work towards a production version of **Mesh Security**. As of April 2023, this is very
+early stage, not even MVP. The goal is to have something for testnets by July 2023.
+Please [see the roadmap](./ROADMAP.md) for more info.
+
+The original version from HackWasm Medellin can be found at
+[CosmWasm/mesh-security-hackathon](https://github.com/CosmWasm/mesh-security-hackathon).
+That is actually full-stack end-to-end, but made a lot of design trade-offs for a hackathon.
+You can refer to the code as an idea of how the production version will look and if you
+learn better from working code than architecture documents.

ROADMAP.md

@@ -0,0 +1,101 @@
+# Development Roadmap
+
+Created: Apr 17, 2023
+Status: Draft
+
+## High Level Milestones
+
+### MVP
+
+Target Date: June/July 2023
+
+The first milestone will be design containing all major features in a solid foundation to build on.
+It is designed to be launched on two testnets along with a usable UI, so we can begin getting real
+feedback from users and relayers, while building out the more complex features and polishing off some
+tougher issues.
+
+### V1
+
+Target date: Early Q4 2023 ??
+
+This will include a feature complete version of all code (eg including slashing), but may not have all
+extensions (such as remote staking not providing gov voting power). The provider side should
+be well reviewed and free from any security holes (safe to deploy on larger chains). The consumer side
+(which includes a custom SDK module) will be as solid as possible, but not recommended to run on serious
+chains. At this points, Osmosis could provide security to a small market cap chain.
+
+### V2
+
+Target date: Early Q1 2024 ??
+
+This will include all optional features we consider feasible in a realistic time frame and most importantly
+will have much deeper security model, and have received some external reviews (maybe audit if someone pays).
+This should be stable enough such that chains with solid market caps could provide peer security (being both
+provider and consumer).
+
+## Plan for MVP
+
+A higher-level backlog for what it takes to create the MVP.
+This may be too many points and we need to review this. Currently in draft form.
+
+**Part 1: Foundation**
+
+* Start new repo for production mesh-security (port ideas from prototype, but we don't need to build on it)
+* Finalize the documentation for provider side
+* Define all contract interfaces / APIs as Rust files
+* Produce stub-contracts with proper APIs (all `unimplemented!()`)
+
+**Part 2: The Vault** 
+
+* Produce mock contracts with proper APIs (all with dummy testing implementation)
+  * Mocks should also be usable for UI testing with eg 1 minute unbonding
+* Write and test vault contract (that calls mock local and remote staking via multi-test)
+  * Ensure vault accepts both native and cw20 tokens
+  * All configuration options should be implemented
+* Finalize the documentation for the consumer side, including the custom SDK modules
+* Create initial designs (wireframes) for the UI, focusing around vault and local/remote staking 
+
+**Part 3: Provider Staking**
+
+* Implement local staking module (simple version - no optional features)
+  * Ensure user can withdraw rewards from local staking
+* Implement remote staking module, provider side (simple version - no optional features)
+* Implement mock converter, consumer side (connects via IBC properly, but )
+* Full stack IBC test from `token -> vault -> remote staking -> converter`, bonding and unbonding
+* Usable UI for provider side (mocking out remote providers), with bonding and unbonding
+
+**Part 4: Consumer Staking**
+
+* Implement minimal Virtual Staking contract using minimal modifications to Osmosis' [superfluid staking](https://github.com/osmosis-labs/osmosis/tree/main/x/superfluid#messages) and [lockup](https://github.com/osmosis-labs/osmosis/blob/main/x/lockup/README.md#lock-tokens) modules.
+  * Try to keep changes minimal to work without LP shares (rather using 1:1, or the converter rate)
+  * Doesn't have to work properly in all cases, but should allow multiple bondings and unbondings to different validators
+* Implement proper converter that uses governance set rate but talks IBC fully and calls into Virtual Staking to make stake
+* Cross-chain full stack tests with IBC and staking (using osmosisd testnet config for consumer side, wasmd for provider side)
+* Rewards not yet implemented
+* Improve provider-side UI
+
+**Part 5: Rewards**
+
+* Make custom Virtual Staking module if needed
+  * Minimal changes to Osmosis contracts if possible, so can be backported
+  * Custom SDK app with this module (based on wasmd) for consumer side
+  * Handles reward withdrawl
+  * Handles multi bonding/unbonding in quick succession (not blocked by 7 pending unbonds issue)
+* Add reward flow to Converter
+* Send rewards over IBC to RemoteStaking contract
+* Add reward withdrawal to remote staking
+* Add cross-chain staking to UI
+
+**Part 6: Finalize Binaries**
+
+* Close any TODOs or known issues / bugs that fit in MVP scope
+  * Create well-defined GitHub issues for items to be addressed later (label V1 or V2)
+
+* At least one:
+  * Create fork of (wasmd? junod?) that supports virtual staking
+  * Create fork of osmosisd that supports virtual staking (ideally reusing as much as possible)
+* Provide dev net environment showing this is working with a usable UI (for internal testing)
+
+**Part 7: Bring to testnet**
+
+* Pass code to the chains' testnets, so they can bring to the masses

docs/README.md

@@ -0,0 +1,122 @@
+# Mesh Security Architecture
+
+This is an architectural overview of the various components of Mesh Security.
+These attempt to explain a full-refined v2 state. As needed, we will include
+simplifications used for MVP (testnet) or v1 (production-ready, feature-limited)
+as footnotes in the documents.
+
+```mermaid
+flowchart TD
+  %%{init: {'theme': 'forest'}}%%
+  
+  subgraph Osmosis
+  A{{$OSMO}} -- User Deposit --> B(Vault);
+  B -- $OSMO --> C(Local Staker);
+  C -- $OSMO --> D[Native Staking]
+  B -- Lein --> E(External Staker Juno);
+  B -- Lein --> G(External Staker Stars);
+  end
+  
+  E -. IBC .-> M;
+  H -. IBC .-> N;
+
+  subgraph Akash
+  H{{Akash Provider}};
+  end
+
+  subgraph Juno
+  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;
+
+  subgraph Stargaze
+  R{{Osmosis Receiver}} -- virtual stake --> S(Virtual Staking);
+  S -- $STARS --> T[Native Staking];
+  end
+
+```
+
+You can get a good overview of the whole system flow in the above diagram. 
+The design should allow one chain to provide security to multiple chains, while
+at the same time receiving security from multiple chains. 
+
+A key to understanding the design, is that the whole system is _delegator-centeric_ 
+not _validator-centric_. This means that we don't try to match the same validators on
+multiple chains, or even subsets, but rather focus on leveraging the security
+provided by staking tokens to secure validators on multiple chains.  This provides a way to
+scale bidirectionally, while avoiding some sort of infinite-loop recursion, as
+chains can only provide security in their native token(s).
+
+## Use Cases
+
+Before we dig into the architecture of Mesh Security, please take a look at
+the [use cases we aim to serve](./UseCases.md).
+
+## Definitions
+
+* **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.
+  Notably, chain A and chain B may have two pairings in opposite directions at the same time.
+* **Provider** _(also "Provider Chain")_ - when looking at one pairing, this is the chain which 
+  locks up tokens and provides them as staking collateral to the other chain. 
+* **Consumer** _(also "Consumer Chain")_ - when looking at one pairing, this is the chain which
+  adjusts validator weights and provides rewards based on remote collateral.
+* **Collateral** - Tokens locked up on the provider chain, which are providing security
+  guarantees to one or more providers. These tokens may be slashed upon any slashing event
+  in the consumers.
+* **Staking** _(also "Delegation")_ - The act of providing collateral for a validator, such that the
+  staker receives a portion of the block rewards if they behave correctly, as well as the slashing risk
+  if they misbehave.
+* **Unstaking** _(also "Unbonding")_ - The act of initialing the removal of stake from a system. During
+  the "unbonding period", the collateral will not receive any rewards, but will be liable to slashing
+  based on misbehavior of that validator.
+* **Unbonding period** - The time delay between initiating unbonding and having free access to the
+  underlying collateral. Once this time has passed after unstaking, all claims on the underlying
+  collateral are released and 
+* **Rewards** - Block rewards are issued to validators in the native token of the consumer chain.
+  A portion of these rewards goes to the stakers and is collected cross-chain.
+* **Slashing** - If a validator misbehaves, the tokens delegated to it, which provided the
+  voting power, can be slashed. The percentage of slashing for each misbehavior depends on the chain.
+  This slash must be reflected by stakers on the provider chain, but we may make some approximations
+  as needed to implement this efficiently.
+* **Jailing** - If a validator misbehaves, it may be jailed, or removed from the validator set and
+  prevented from returning. Tokens staked to it would be partially slashed and should be unstaked
+  as soon as possible, as they will receive no more rewards. Stake to a jailed validator still must
+  wait the unbonding period to be liquid.
+* **Latency** - Time delay from an action being initiated and the effects being reflected in
+  another contract or chain. This doesn't refer to the unbonding period, but rather the delay between
+  initiating bonding or unbonding on the provider and the equivalent action occurring on the consumer. 
+
+## Sections
+
+Below are links to detailed documents on various sub-systems:
+
+[Provider](./provider/Provider.md):
+  * [Vault](./provider/Vault.md)
+  * [Local Staking](./provider/LocalStaking.md)
+  * [External Staking](./provider/ExternalStaking.md)
+  * TODO - Rust interfaces
+
+[Consumer](./consumer/Consumer.md):
+  * [Converter](./consumer/Converter.md)
+  * [Virtual Staking](./consumer/VirtualStaking.md)
+  * SDK Changes
+
+[IBC Protocol](./ibc/Overview.md):
+  * [Cross-Chain Staking](./ibc/Staking.md)
+  * [Reward Flow](./ibc/Rewards.md)
+  * [Handling Slashing Evidence](./ibc/Slashing.md)
+
+## Limitations
+
+**Unbonding Limits**
+
+As we are focused on the standard implementation of the Cosmos SDK, one account may only have
+a fixed number of simultaneous unbondings on a given delegator. By default, that number is 7.
+We must batch together multiple unbonding requests so there are never more than that number
+active at once. The typical solution for LSDs is to divide the unbonding period into segments,
+so if the unbonding period is 3 weeks, the contract initiates unbonding every 3 days for all
+requests that occurred in that period.

docs/UseCases.md

@@ -0,0 +1,83 @@
+# Use Cases
+
+## Sibling Chains
+
+Two chains of similar size want to support each other.
+There can be a difference of the strength, such that
+larger -> smaller has more weight than smaller -> larger.
+
+```mermaid
+flowchart LR
+  %%{init: {'theme': 'forest'}}%%
+  A(Juno) -- 40% --> B(Star);
+  B -- 20% --> A;
+```
+
+## Full Mesh
+
+This is meant for multiple chains with market caps within
+say an order of magnitude that all have supportive relations
+and want to enter a joint security zone. They can all provide meaningful levels of security
+to each other. This leads to many bidirectional flows and
+even loops (yes, the algorithm handles this).
+
+Note that Osmosis is about 5x the size of the other two,
+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;
+```
+
+## DAOs migrating to own chain
+
+A number of Juno DAOs launching their own chains. They want to inherit most of their security from Juno,
+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;
+```
+
+## Almost Replicated Security
+
+Mesh Security is not ICSv1 "Replicated Security". We do not map validators from provider to consumer, but rather delegators.
+And the power is the subset of staked tokens that opt-in, so will always be lower than full stake. By design we always require
+a native staking token in the consumer chain, but we can approximate "replciated security" for the "fully owned subsidiary"
+use case.
+
+You can launch a chain with a governance token with minimal distribution to bootstrap the chain. Then accept another chain as a
+provider, locking it's token 1:1 with the native token (hardcoded "oracle" feed), and allow it to control up to 99% of the voting power
+of the chain, including gov votes. The end effect is the new chain is almost 100% controlled by the cross-stakers of the parent chain:
+
+```mermaid
+flowchart TD
+  %%{init: {'theme': 'forest'}}%%
+  Juno -- 99%, gov --> Eve;
+```
+
+
+## Credibly Neutral Common Good
+
+There are some items that should be neutral or independent of multiple chains,
+like a shared name service. In this case, we allow multiple controlling chains to 
+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;
+```
+