Fix syntax / links

docs/README.md

@@ -45,7 +45,7 @@ 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_
+A key to understanding the design, is that the whole system is _delegator-centric_
 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
@@ -65,9 +65,9 @@ Addressing some common points people raise up, which are hidden in the docs.
 
 There are many questions if this isn't "fractional reserve banking" or such.
 This does use the same collateral to back multiple claims (staking), but
-the [final invariant in the vault](https://github.com/osmosis-labs/mesh-security/blob/main/contracts/vault/README.md#invariants)
+the [final invariant in the vault](https://github.com/osmosis-labs/mesh-security/blob/main/contracts/provider/vault/README.md#invariants)
 ensures there is sufficient collateral to cover the maximum loss
-(eg. if all local and cross-staked validators double-sign).
+(e.g. if all local and cross-staked validators double-sign).
 If the double slash penalty is 5%, you can safely cross stake 20x.
 If it were to be raised to say 40%, you could only safely cross stake 2.5x
 This is more like insurance companies holding reserves for the worse cases expected losses,
@@ -76,9 +76,9 @@ not the total value of all property insured.
 ### Power Limits on Remote Chains
 
 Another common concern is whether there are effective limits in the power a remote
-chain can exert over one chain. Would it be possible for a higher cap chain (eg $ATOM)
+chain can exert over one chain. Would it be possible for a higher cap chain (e.g. $ATOM)
 to take over more than one-third, or even two-thirds or the power of a smaller cap chain
-(eg $STARS) it is cross-staking on.
+(e.g. $STARS) it is cross-staking on.
 
 Clearly the consumer chain wants to put some limits. The first limit is the
 [discount applied during the conversion](https://github.com/osmosis-labs/mesh-security/blob/main/docs/consumer/Converter.md#price-normalization).
@@ -110,7 +110,7 @@ There are three main failure modes to consider:
 #### Huge Price Swing
 
 This is the most likely scenario. If the provider price rises too much, it may suddenly have
-disproportionate power over the affairs of the consumer. If the provier price falls too much,
+disproportionate power over the affairs of the consumer. If the provider price falls too much,
 in the period until the price oracle is updated, there may be less remote collateral
 than the virtual stake.
 
@@ -135,7 +135,7 @@ max cap limit preventing total takeover, so it just provides overly high rewards
 #### Byzantine Provider Chain
 
 The worst case is the provider claims to deposit millions of tokens on one malicious validator,
-while not actually locking any collateral on it's own chain. This is similar to the case of
+while not actually locking any collateral on its own chain. This is similar to the case of
 a hostile community on the provider chain selecting validators against the interest of the
 community on the consumer chain.
 
@@ -154,18 +154,18 @@ perceived stability.
 If a Consumer Chain goes Byzantine (or starts some mob-rule governance proposals), it can
 try to damage stake on the Provider chain. There are several ways it can try to do so:
 
-- Withholding all rewards to said Provider
-- Removing all voting power from said Provider
-- Refusing to unlock the virtual stake of the Provider
-- Unfairly slashing virtual stake from the Provider
+- Withholding all rewards to said Provider.
+- Removing all voting power from said Provider.
+- Refusing to unlock the virtual stake of the Provider.
+- Unfairly slashing virtual stake from the Provider.
 
 The first two are temporary and can be seen in the case when the consumer no longer trusts the
 provider and sets "max cap" to zero. This is a temporary effect but must be acknowledged as
 a possible risk, which is loss of benefits, but not loss of collateral.
 
 The third point is impossible, as the unlock period is implemented between the external staking
 contracts and the vault on the provider side. Nothing on the Consumer can lock up stake longer.
-And if a Provider feels they have unfairly withhold benefits (first two points), they could
+And if a Provider feels they have unfairly withheld benefits (first two points), they could
 make a governance vote to allow immediate unbonding of all cross-stake to that consumer.
 
 The last point is a bit trickier. We will not fully define slashing until v1, but the design is
@@ -201,7 +201,7 @@ Some common terms are defined here, which may be used throughout the documentati
   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
+  collateral are released.
 - **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
@@ -212,7 +212,7 @@ Some common terms are defined here, which may be used throughout the documentati
   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
+- **Latency** - Time delay from an action being initiated and its 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.
 

docs/UseCases.md

@@ -1,16 +1,16 @@
 # 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.
+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 governance 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)
+(Note that these are not clear percentages. 40 / (100 + 40) = 28.5% of the total power in the hands of that provider).
 
 ## Sibling Chains
 
@@ -52,7 +52,7 @@ You could analyze Juno in this example:
 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
+## DAOs migrating to their 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.
@@ -65,13 +65,14 @@ flowchart TD
   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)
+Note that less than 1/3 power is 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.
-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"
+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 "replicated 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

docs/provider/DAOs.md

@@ -1,23 +1,23 @@
 # DAO DAO Extension
 
-After discussing this general diagram, we realized there is some value in
-a simplified version of this, which may also be a great starting place to
+After discussing this general diagram, we realized that there is some value in
+a simplified version of this, which may also be a great starting place for
 testing out UX without the complications of IBC. DAOs have their own
 token, governance, staking, and reward contracts. We can compare them to
-low-cap chains embedded in a host chain. Let's look at two ways of using DAOs locally
+low-cap chains embedded in a host chain. Let's look at two ways of using DAOs locally.
 
 This document holds some brainstorm idea of how one might reuse much of the
 design but customize some pieces to allow DAOs partially secured by native
 tokens, or let huge DAOs provide security to the chain they run on.
-None of this is fleshed out or on the road map, but is here to give
+None of this is fleshed out or on the roadmap, but is here to give
 an idea on the flexibility of Mesh Security and may inspire someone
-to develop it further
+to develop it further.
 
 ## Bootstrapping DAOs
 
 When a new DAO launches, it often wants to accomplish two things:
 
-1. Ensure a reasonable security for the DAO (regardless of low market cap)
+1. Ensure a reasonable security for the DAO (regardless of low market cap).
 2. Airdrop some tokens to native stakers.
 
 By using a variant of mesh security, they can do both, acting as a
@@ -52,10 +52,10 @@ it just stakes. Without delegation, this also brings up many questions
 about governance power and such, which may be easier to prototype
 in DAO contracts than modifying the Cosmos SDK staking module.
 
-**Recommendation** Once the MVP Vault is built, it would be good to assign
+**Recommendation**: Once the MVP Vault is built, it would be good to assign
 one contract dev to work out this External Staker implementation to
 some standard DAO DAO staking contract (can be a "hacked" version that
-just holds a lot of the DAO token, like we did in HackWasm Medellin).
+just holds a lot of the DAO token, like we did in HackWasm Medellín).
 This will unblock frontend developers and allow us to get much quicker
 feedback on UX issues in such a system, while the backend engineers
 are working with the complexities of IBC and staking virtual tokens in
@@ -86,10 +86,10 @@ flowchart LR
 
 Note this would require a different implementation for vault (to handle cw20),
 and likely a different "local staker" interface (you don't select validators, but rather unbonding time).
-The "External Staker JUNO" would be similar to the normal [Receiver model](../consumer/Receiver.md)
-and we will need a full implementation of the [Consumer side](../consumer/Consumer.md)
+The "External Staker JUNO" would be similar to the normal [Receiver model](../consumer/Receiver.md), and
+we will need a full implementation of the [Consumer side](../consumer/Consumer.md)
 implemented on the same chain.
 
-**Recommendation** We do not build this either as MVP or v1, and view later if it makes
+**Recommendation**: We do not build this either as MVP or v1, and view later if it makes
 sense at all. However, we should consider this use case in our designs to ensure our interfaces
 and invariants make this possible.

docs/provider/Provider.md

@@ -33,7 +33,7 @@ which they can withdraw assuming there are no outstanding liens on that amount.
 Each vault contains _exactly one_ denom and has _exactly one_ local staking
 module. This local staker can stake the vault token with the
 native staking module. It actually accepts the original token, which makes
-it different than external stakers, which accept liens. By depositing in the vault
+it different from external stakers, which accept liens. By depositing in the vault
 and staking in the local staker, I will have achieved the same effect
 (and get the same rewards) as directly staking... but I can now use my balance
 for more.
@@ -45,16 +45,16 @@ staking token, but have opted in to accepting a portion
 of their security from this vault in exchange for a portion
 of their rewards. In the basic model, these accept a lien
 from the vault and will communicate with a consumer interface
-to inform how much stake is locked to which validator and
+to inform how much stake is locked to which validator, and
 to receive rewards.
 [Read more about external staking](./ExternalStaking.md).
 
 The connection to the consumer is over IBC and the consumer is
 responsible for converting these "virtual tokens" into delegations
-in the native staking module. Note that the consumer must first opt-in to
+in their native staking module. Note that the consumer must first opt in to
 accept the provider's tokens and can place multiple restrictions and limits
-on to how much power can be granted into any external chain.
-[Read more about consumers](../consumers/Consumer.md).
+on how much power can be granted to any external chain.
+[Read more about consumers](../consumer/Consumer.md).
 
 ## Stakers and Governance
 
@@ -75,26 +75,26 @@ unbonding period), and naturally unstake when they want.
 For external staking, the cross-staker will never be able to override
 the vote, as they are not expected to be very active in local governance
 on these external protocols. (If they want to participate, they can take the
-cross-staking rewards and delegate those tokens directly to get a voice.)
+cross-staking rewards and delegate those tokens directly to get a voice).
 
 **Desired goal by v2:**
 
 There will be two supported configurations for external staking.
 Either the cross-staked tokens provides governance voting power
 to the validator in the same proportion that it provides Tendermint voting power.
-Or the cross-staked tokens only provide Tendermint voting power (security)
+Or, the cross-staked tokens only provide Tendermint voting power (security)
 without granting more governance power to that validator.
 There are [use cases](../UseCases.md) for each configuration.
 
-It is unclear if this is possible without forking the governance module
-and design work is [tracked in this issue](https://github.com/osmosis-labs/mesh-security-sdk/issues/48)
+It is unclear if this is possible without forking the governance module,
+and design work is [tracked in this issue](https://github.com/osmosis-labs/mesh-security-sdk/issues/48).
 
 ## Optional Extensions
 
 These won't be included in MVP and require more modifications
 to the core Cosmos SDK modules, which makes them more risky and
-more difficult to port to other chains. But could be considered
+more difficult to port to other chains. But, could be considered
 as chain-specific extensions.
 
-- Enable moving bonded tokens directly into the vault? (Custom SDK change)
-- Allow depositing vesting tokens to the vault? (deeper SDK change)
+- Enable moving bonded tokens directly into the vault? (custom SDK change).
+- Allow depositing vesting tokens to the vault? (deeper SDK change).