From c85474a83ee222422fe942864807b2abfaa65e4b Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Mon, 22 Apr 2024 10:58:14 +0200 Subject: [PATCH 01/11] ADR CosmoLayer: Initial draft --- docs/docs/adrs/adr-016-cosmolayer.md | 214 +++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 docs/docs/adrs/adr-016-cosmolayer.md diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md new file mode 100644 index 0000000000..b18042a675 --- /dev/null +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -0,0 +1,214 @@ +# ADR 016: CosmoLayer + +## Changelog + +- 2024-04-05: Initial draft of ADR + +## Status + +Draft + +## Context + +> This section contains all the context one needs to understand the current state, +> and why there is a problem. It should be as succinct as possible and introduce +> the high level idea behind the solution. + +CosmoLayer enables re-staking of Ethereum tokens to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by staked Ethereum and native tokens. + +CosmoLayer is based on 4 parts + +- EigenLayer AVS contract (restaking, slashing of validators) +- Oracle (tracks how much ETH has been delegated to each validator) +- Cosmos modules (combines external and native stakes to derive power of each validator) +- Bridge to EigenLayer (needed for rewards to be sent back to EigenLayer) +where each part is described by its own ADR. + +Present [ADR](01-cosmolayer-cosmos_module.md) describes the Cosmos modules of the solution. + +``` +- Any Cosmos blockchain can deploy an EigenLayer AVS + +- An EigenLayer allows Ethereum stakers to restake their Eth and other tokens to other systems (Cosmos chains)` +``` + +## Alternative Approaches + +> This section contains information around alternative options that are considered +> before making a decision. It should contain a explanation on why the alternative +> approach(es) were not chosen. + +### Reward Distribution + +1. External stakers rewarded with native cosmos-chain tokens + - No channel back to source of stakes (EigenLayer/Babylon) needed. + - Stakers are not rewarded in form of 'source' tokens + - Transfer of the rewards back to external stake is up to the user + - All external staker addresses need to be sent to cosmos chain + - External stakers need to have an address on th cosmos chain where their external staking address is mapped against +2. External stakers rewarded with source stakes (EigenLayer/Babylon) +This can be realized by a bridge transfering back rewards to stakers on Eigenlayer, +wich requires + - a pool of tokens - with sufficient size - on EigenLayer to distribute rewards to Ethereum stakers. + - complex (distribution logic/contract on Eigenlayer/Babylon) + - bridge can be implemented by `Slinky Oracle` module or on cosmos-chain + + +## Decision + +> This section records the decision that was made. +> It is best to record as much info as possible from the discussion that happened. +> This aids in not having to go back to the Pull Request to get the needed information. + +## Detailed Design +> This section does not need to be filled in at the start of the ADR, but must +> be completed prior to the merging of the implementation. +> +> Here are some common questions that get answered as part of the detailed design: +> +> - What are the user requirements? +> +> - What systems will be affected? +> +> - What new data structures are needed, what data structures will be changed? +> +> - What new APIs will be needed, what APIs will be changed? +> +> - What are the efficiency considerations (time/space)? +> +> - What are the expected access patterns (load/throughput)? +> +> - Are there any logging, monitoring or observability needs? +> +> - Are there any security considerations? +> +> - Are there any privacy considerations? +> +> - How will the changes be tested? +> +> - If the change is large, how will the changes be broken up for ease of review? +> +> - Will these changes require a breaking (major) release? +> +> - Does this change require coordination with the SDK or other? + + +----- +The `Cosmos Modules` are an integral part of the CosmoLayer solution and consist of a `Power Mixing` and a `Reward Handler` module. +The `Power Mixing` module provides the capability of deriving validator power based on stake originated from Ethereum and the native staking module. +The `Reward Handler` is in charge of sending rewards to external stakers on Ethereum EigenLayer. + +--- + +### Power Mixing + +Power Mixing provides the final validator powers based on staking information of the native chain and the external stakes e.g. from Ethereum EigenLayer. The information about external staking and related price feeds are received from `Slinky Oracle`. +Once the final validator powers are determined the result is submitted to the underlying CometBFT consensus layer by [updating](https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#updating-the-validator-set) the validator set. + +Requirements: + +- validator updates are performed on each EndBlock +- a validator's power is determined based on its native on-chain stakes and external stakes +- price information of staked tokens is used to determine a validator’s power, e.g. price ratio (price of native on-chain token / price of external stake) +- price information of native/external tokens are received from the `[Slinky Oracle](https://www.notion.so/informalsystems/02-cosmolayer-oracle.md)` +- external staking information are received from the `Slinky Oracle` +- native staking information are received from the `Cosmos SDK Staking Module` +- Set of validator stakes from `Slinky Oracle` always have the current price, full set of validators, and current stakes + +The `Power Mixing` module implements: + +- `UpdateValidatorSet()` +queries current Validators from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) +queries current validatorset from oracle (see below) +powerMix() determines validator power from local and external staked validator sets +update validator set on cometBFT ABCI (x/staking is doing this in ValidatorUpdates 'values are overwritten in every block', ICS provider module intervenes in this behaviour during `EndBlock`) + +### Queries + +The following queries will be provided by `Slinky Oracle` (extension to current implementation) + +```protobuf +message ExtValidatorUpdates { + repeated ExtValPower powers; + PriceUpdate price; +} + +message ExtValPower { + string validator_address; + uint64 stakes; +} + +// TBD if this is needed +message GetExtDelegators { + string eth_address; + uint64 stakes; +} +``` + +```protobuf +message PriceUpdate { + float ratio; + string denom; +} +``` + +### Questions: + +- When are validator powers re-calculated (price update)? +Event based from `oracle` [price triggerd] / interval? +→ Reqular updates e.g. next epoch +- How does 'Unbonding' work for ETH stake? +(TokenManager on Eigenlayer. TBD if unbonding period on Eigenlayer match with cosmos-chain [bootstrapping/setup] is a requirement) +- What are the external delegator addresses used for? +Only needed if rewards are issued locally? +- Are thre any ICS dependencies to be considered? +- Determinims of the validator powers ? → deterministic due to extended votes +- Determinism of the price feed? → yes but capability of backtracking how a price was determined by `Slinky Oracle` needs to be checked (TODO) +- Slashing: double signing evidence? + +### Alternative Solution + +- Oracle provides only price feeds and external validator stakes are received by a bridge to AVS + +--- + +### Reward Handler + +For native staked tokens the `Distribution Module` of the Cosmos SDK is taking care of sending the rewards to stakers. +For stakes originated from Ethereum the `Reward Handler` module sends rewards to the AVS contract of the related Cosmos chain. +The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and Ethereum Eigenlayer. + +**Alternative Solution** + +1. the `Reward Handler` sends rewards to the related Eigenlayer AVS of the chain via `Slinky Oracle` which establish a bridge to Ethereum. +2. the `Reward Handler` issues rewards for external staker to their address on the Cosmos chain. +This requires: + 1. sending all external stakers to cosmos chain + 2. mapping of restaker addresses to their registered addresses on cosmos chain + + +## Consequences + +> This section describes the consequences, after applying the decision. All +> consequences should be summarized here, not just the "positive" ones. + +### Positive + +* Allow Ethereum stakers to re-stake their tokens to secure a Cosmos chain + +### Negative + +* Additional complexity for staking +* Depenency to external sources e.g (price feeds) for validator power calculation +* backtracking of price feeds at a certain point in time + +### Neutral + + +## References + +> Are there any relevant PR comments, issues that led up to this, or articles +> referenced for why we made the given design choice? If so link them here! + +- [Cosmolayer - Oracle](./02-cosmolayer-oracle.md) +- {reference link} From 414af81141cfab61fe4d4f3fdf7da4380337ab65 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 24 Apr 2024 09:08:40 +0200 Subject: [PATCH 02/11] update adr: slinky api --- docs/docs/adrs/adr-016-cosmolayer.md | 92 ++++++++++++---------------- 1 file changed, 39 insertions(+), 53 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index b18042a675..5ce6a02199 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -14,23 +14,19 @@ Draft > and why there is a problem. It should be as succinct as possible and introduce > the high level idea behind the solution. -CosmoLayer enables re-staking of Ethereum tokens to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by staked Ethereum and native tokens. +CosmoLayer enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by staked Ethereum and native tokens. -CosmoLayer is based on 4 parts +CosmoLayer solution consists of 4 parts -- EigenLayer AVS contract (restaking, slashing of validators) -- Oracle (tracks how much ETH has been delegated to each validator) -- Cosmos modules (combines external and native stakes to derive power of each validator) +- External staking solution such as Babylon or EigenLayer AVS contract +- Oracle (tracks how much ETH has been delegated to each validator and provides price feeds for external tokens) +- CosmoLayer: Cosmos modules (combines external and native stakes to derive power of each validator) - Bridge to EigenLayer (needed for rewards to be sent back to EigenLayer) -where each part is described by its own ADR. -Present [ADR](01-cosmolayer-cosmos_module.md) describes the Cosmos modules of the solution. +External staking information is received from an oracle together with price information of related stakes. +The CosmosLayer derives validator powers based on external and native staking information and initiates rewarding of external depositors. -``` -- Any Cosmos blockchain can deploy an EigenLayer AVS - -- An EigenLayer allows Ethereum stakers to restake their Eth and other tokens to other systems (Cosmos chains)` -``` +Present ADR describes the _Cosmos modules_ of the solution. ## Alternative Approaches @@ -38,21 +34,6 @@ Present [ADR](01-cosmolayer-cosmos_module.md) describes the Cosmos modules of th > before making a decision. It should contain a explanation on why the alternative > approach(es) were not chosen. -### Reward Distribution - -1. External stakers rewarded with native cosmos-chain tokens - - No channel back to source of stakes (EigenLayer/Babylon) needed. - - Stakers are not rewarded in form of 'source' tokens - - Transfer of the rewards back to external stake is up to the user - - All external staker addresses need to be sent to cosmos chain - - External stakers need to have an address on th cosmos chain where their external staking address is mapped against -2. External stakers rewarded with source stakes (EigenLayer/Babylon) -This can be realized by a bridge transfering back rewards to stakers on Eigenlayer, -wich requires - - a pool of tokens - with sufficient size - on EigenLayer to distribute rewards to Ethereum stakers. - - complex (distribution logic/contract on Eigenlayer/Babylon) - - bridge can be implemented by `Slinky Oracle` module or on cosmos-chain - ## Decision @@ -93,10 +74,10 @@ wich requires > - Does this change require coordination with the SDK or other? ------ + The `Cosmos Modules` are an integral part of the CosmoLayer solution and consist of a `Power Mixing` and a `Reward Handler` module. -The `Power Mixing` module provides the capability of deriving validator power based on stake originated from Ethereum and the native staking module. -The `Reward Handler` is in charge of sending rewards to external stakers on Ethereum EigenLayer. +The `Power Mixing` module provides the capability of deriving validator power based on stake originated from external sources such as Ethereum/Bitcoin and the native staking module. +The `Reward Handler` is in charge of sending rewards to external stakers. --- @@ -110,10 +91,11 @@ Requirements: - validator updates are performed on each EndBlock - a validator's power is determined based on its native on-chain stakes and external stakes - price information of staked tokens is used to determine a validator’s power, e.g. price ratio (price of native on-chain token / price of external stake) -- price information of native/external tokens are received from the `[Slinky Oracle](https://www.notion.so/informalsystems/02-cosmolayer-oracle.md)` -- external staking information are received from the `Slinky Oracle` +- price information of native/external tokens are received from `[Slinky Oracle](https://www.notion.so/informalsystems/02-cosmolayer-oracle.md)` +- staking information of EigenLayer are received from the `Slinky Oracle` +- staking information of Bitcoin are received from Babylon's Bitcoin staking protocol - native staking information are received from the `Cosmos SDK Staking Module` -- Set of validator stakes from `Slinky Oracle` always have the current price, full set of validators, and current stakes +- set of validator stakes from `Slinky Oracle` always have the current price, full set of validators, and current stakes The `Power Mixing` module implements: @@ -128,27 +110,38 @@ update validator set on cometBFT ABCI (x/staking is doing this in ValidatorUpdat The following queries will be provided by `Slinky Oracle` (extension to current implementation) ```protobuf -message ExtValidatorUpdates { +service Query { + rpc GetExtValidators(GetExtValidatorRequest) returns (ExtValidatorsResponse) { + option (google.api.http).get = "/slinky/oracle/v1/get_validators"; + }; +} + +message GetExtValidatorRequest {} + +// ExtValidatorsResponse is the response from GetExtValidators queries +message ExtValidatorsResponse { repeated ExtValPower powers; - PriceUpdate price; } +// ExtValPower represents a validator with its staking and token information, +// where `stakes` is the total amount of stakes for a validator and `denom` is the +// source token of the stake e.g. ETH,BTC.g message ExtValPower { string validator_address; uint64 stakes; + string denom; } -// TBD if this is needed -message GetExtDelegators { - string eth_address; - uint64 stakes; -} ``` +current implementation of `Slinky Oracle` provides a query [GetPrice](https://github.com/skip-mev/slinky/blob/main/proto/slinky/oracle/v1/query.proto) +to get the latest price feed for a currency pair. + ```protobuf -message PriceUpdate { - float ratio; - string denom; +service Query { + rpc GetPrice(GetPriceRequest) returns (GetPriceResponse) { + option (google.api.http).get = "/slinky/oracle/v1/get_price"; + }; } ``` @@ -175,17 +168,10 @@ Only needed if rewards are issued locally? ### Reward Handler For native staked tokens the `Distribution Module` of the Cosmos SDK is taking care of sending the rewards to stakers. -For stakes originated from Ethereum the `Reward Handler` module sends rewards to the AVS contract of the related Cosmos chain. -The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and Ethereum Eigenlayer. - -**Alternative Solution** - -1. the `Reward Handler` sends rewards to the related Eigenlayer AVS of the chain via `Slinky Oracle` which establish a bridge to Ethereum. -2. the `Reward Handler` issues rewards for external staker to their address on the Cosmos chain. -This requires: - 1. sending all external stakers to cosmos chain - 2. mapping of restaker addresses to their registered addresses on cosmos chain +For stakes originated from external chains (Ethereum/Bitcoin) the `Reward Handler` module sends rewards to EigenLayer/Babylon. +The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and Eigenlayer/Babylon. +Note: currently there's no support paying rewards on EigneLayer (see [here](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/)) ## Consequences From 4d351d3efb3762c7c435ccf831e1b1e26f6f6044 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 24 Apr 2024 10:15:44 +0200 Subject: [PATCH 03/11] cleanup --- docs/docs/adrs/adr-016-cosmolayer.md | 94 ++++++---------------------- 1 file changed, 20 insertions(+), 74 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index 5ce6a02199..a55a7413fc 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -2,7 +2,7 @@ ## Changelog -- 2024-04-05: Initial draft of ADR +- 2024-04-24: Initial draft of ADR ## Status @@ -10,10 +10,6 @@ Draft ## Context -> This section contains all the context one needs to understand the current state, -> and why there is a problem. It should be as succinct as possible and introduce -> the high level idea behind the solution. - CosmoLayer enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by staked Ethereum and native tokens. CosmoLayer solution consists of 4 parts @@ -42,45 +38,11 @@ Present ADR describes the _Cosmos modules_ of the solution. > This aids in not having to go back to the Pull Request to get the needed information. ## Detailed Design -> This section does not need to be filled in at the start of the ADR, but must -> be completed prior to the merging of the implementation. -> -> Here are some common questions that get answered as part of the detailed design: -> -> - What are the user requirements? -> -> - What systems will be affected? -> -> - What new data structures are needed, what data structures will be changed? -> -> - What new APIs will be needed, what APIs will be changed? -> -> - What are the efficiency considerations (time/space)? -> -> - What are the expected access patterns (load/throughput)? -> -> - Are there any logging, monitoring or observability needs? -> -> - Are there any security considerations? -> -> - Are there any privacy considerations? -> -> - How will the changes be tested? -> -> - If the change is large, how will the changes be broken up for ease of review? -> -> - Will these changes require a breaking (major) release? -> -> - Does this change require coordination with the SDK or other? - - - -The `Cosmos Modules` are an integral part of the CosmoLayer solution and consist of a `Power Mixing` and a `Reward Handler` module. + +The Cosmos modules are an integral part of the CosmoLayer solution and consist of a `Power Mixing` and a `Reward Handler` module. The `Power Mixing` module provides the capability of deriving validator power based on stake originated from external sources such as Ethereum/Bitcoin and the native staking module. The `Reward Handler` is in charge of sending rewards to external stakers. ---- - ### Power Mixing Power Mixing provides the final validator powers based on staking information of the native chain and the external stakes e.g. from Ethereum EigenLayer. The information about external staking and related price feeds are received from `Slinky Oracle`. @@ -97,13 +59,11 @@ Requirements: - native staking information are received from the `Cosmos SDK Staking Module` - set of validator stakes from `Slinky Oracle` always have the current price, full set of validators, and current stakes -The `Power Mixing` module implements: - -- `UpdateValidatorSet()` -queries current Validators from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) -queries current validatorset from oracle (see below) -powerMix() determines validator power from local and external staked validator sets -update validator set on cometBFT ABCI (x/staking is doing this in ValidatorUpdates 'values are overwritten in every block', ICS provider module intervenes in this behaviour during `EndBlock`) +The `Power Mixing` implementation +- queries current validators from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) +and from `Slinky Oracle` (see below). +- determines validator power from local and external staked validator sets +- updates validator set on cometBFT ABCI (x/staking is doing this in ValidatorUpdates 'values are overwritten in every block', ICS provider module intervenes in this behavior during `EndBlock`) ### Queries @@ -145,25 +105,7 @@ service Query { } ``` -### Questions: - -- When are validator powers re-calculated (price update)? -Event based from `oracle` [price triggerd] / interval? -→ Reqular updates e.g. next epoch -- How does 'Unbonding' work for ETH stake? -(TokenManager on Eigenlayer. TBD if unbonding period on Eigenlayer match with cosmos-chain [bootstrapping/setup] is a requirement) -- What are the external delegator addresses used for? -Only needed if rewards are issued locally? -- Are thre any ICS dependencies to be considered? -- Determinims of the validator powers ? → deterministic due to extended votes -- Determinism of the price feed? → yes but capability of backtracking how a price was determined by `Slinky Oracle` needs to be checked (TODO) -- Slashing: double signing evidence? - -### Alternative Solution - -- Oracle provides only price feeds and external validator stakes are received by a bridge to AVS - ---- +For security reasons the amount of external stakes needs to be limited. Limitation of external staking will be driven by a `Governance Proposal`. ### Reward Handler @@ -171,7 +113,7 @@ For native staked tokens the `Distribution Module` of the Cosmos SDK is taking c For stakes originated from external chains (Ethereum/Bitcoin) the `Reward Handler` module sends rewards to EigenLayer/Babylon. The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and Eigenlayer/Babylon. -Note: currently there's no support paying rewards on EigneLayer (see [here](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/)) +Note: currently there's no support paying rewards on EigenLayer (see [here](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/)) ## Consequences @@ -180,21 +122,25 @@ Note: currently there's no support paying rewards on EigneLayer (see [here](http ### Positive -* Allow Ethereum stakers to re-stake their tokens to secure a Cosmos chain +* Allow external depositors to stake their tokens to secure a Cosmos chain ### Negative +* Dependency to external sources e.g (price feeds) for validator power calculation +* Security impact +### Neutral * Additional complexity for staking -* Depenency to external sources e.g (price feeds) for validator power calculation -* backtracking of price feeds at a certain point in time -### Neutral +## Questions: +- Determinism of the price feed? → yes, but capability of backtracking how a price was determined by `Slinky Oracle` needs to be checked (TODO) +- Slashing: subject of this ADR? (Defined but [not activated](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/) currently on EigenLayer). ## References > Are there any relevant PR comments, issues that led up to this, or articles > referenced for why we made the given design choice? If so link them here! -- [Cosmolayer - Oracle](./02-cosmolayer-oracle.md) -- {reference link} +- [Slinky Oracle](https://github.com/skip-mev/slinky) +- [EigenLayer](https://docs.eigenlayer.xyz/) +- [Babylon](https://babylonchain.io/) From 7fe4d6a60b1d0a64841c2a85fd2916eb52b2e06c Mon Sep 17 00:00:00 2001 From: bernd-m <43466467+bermuell@users.noreply.github.com> Date: Mon, 29 Apr 2024 14:57:54 +0200 Subject: [PATCH 04/11] Apply suggestions from code review Co-authored-by: Marius Poke --- docs/docs/adrs/adr-016-cosmolayer.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index a55a7413fc..30fc4fcfaf 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -10,19 +10,19 @@ Draft ## Context -CosmoLayer enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by staked Ethereum and native tokens. +CosmoLayer enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by both native tokens and external tokens (e.g., ETH, BTC). -CosmoLayer solution consists of 4 parts +CosmoLayer consists of the following four parts: -- External staking solution such as Babylon or EigenLayer AVS contract -- Oracle (tracks how much ETH has been delegated to each validator and provides price feeds for external tokens) -- CosmoLayer: Cosmos modules (combines external and native stakes to derive power of each validator) -- Bridge to EigenLayer (needed for rewards to be sent back to EigenLayer) +- A mechanism for delegating external tokens to Cosmos validators, such as Babylon or EigenLayer AVS contract. +- An oracle that tracks how much external stake has been delegated to each Cosmos validator and provides price feeds for external tokens. +- Power mixing: A mechanism to combine external and native stake to derive the power of each validator. +- A bridge that enables sending back rewards to the external source. External staking information is received from an oracle together with price information of related stakes. The CosmosLayer derives validator powers based on external and native staking information and initiates rewarding of external depositors. -Present ADR describes the _Cosmos modules_ of the solution. +This ADR describes the _Cosmos modules_ of the solution. ## Alternative Approaches @@ -45,7 +45,7 @@ The `Reward Handler` is in charge of sending rewards to external stakers. ### Power Mixing -Power Mixing provides the final validator powers based on staking information of the native chain and the external stakes e.g. from Ethereum EigenLayer. The information about external staking and related price feeds are received from `Slinky Oracle`. +Power Mixing provides the final validator powers based on staking information of the native chain and the external stakes. The information about external staking and related price feeds are received from an oracle. Once the final validator powers are determined the result is submitted to the underlying CometBFT consensus layer by [updating](https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#updating-the-validator-set) the validator set. Requirements: From 605ba3bb790ce8453f8377e68fa75597cd0ee466 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Mon, 29 Apr 2024 17:49:43 +0200 Subject: [PATCH 05/11] addressed comments --- docs/docs/adrs/adr-016-cosmolayer.md | 113 +++++++++++++++++++++------ 1 file changed, 88 insertions(+), 25 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index 30fc4fcfaf..0c527c75c3 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -29,7 +29,10 @@ This ADR describes the _Cosmos modules_ of the solution. > This section contains information around alternative options that are considered > before making a decision. It should contain a explanation on why the alternative > approach(es) were not chosen. - +### Rewards +As an alternative for sending rewards back to the external chains, stakers could be rewarded on the Cosmos chain. +This would require a mapping of external addresses to addresses on Cosmos chain for each staker on external source. +In addition detailed external staking information such as staking addresses, amount of stakes per staker and validator, etc have to be provided by the oracle. ## Decision @@ -37,11 +40,16 @@ This ADR describes the _Cosmos modules_ of the solution. > It is best to record as much info as possible from the discussion that happened. > This aids in not having to go back to the Pull Request to get the needed information. +### Rewards +Rewards will be sent back to external chains instead of paying rewards for external stakers on Cosmos chain +- due to amount of additional staking information to be sent and tracked by the oracle +- due to the additional complexity of managing external and Cosmos addresses + ## Detailed Design -The Cosmos modules are an integral part of the CosmoLayer solution and consist of a `Power Mixing` and a `Reward Handler` module. +The `Power Mixing` feature and `Reward Distribution` protocol are an integral part of the CosmoLayer solution. The `Power Mixing` module provides the capability of deriving validator power based on stake originated from external sources such as Ethereum/Bitcoin and the native staking module. -The `Reward Handler` is in charge of sending rewards to external stakers. +The `Reward Distribution` is in charge of sending rewards to external stakers. ### Power Mixing @@ -53,26 +61,80 @@ Requirements: - validator updates are performed on each EndBlock - a validator's power is determined based on its native on-chain stakes and external stakes - price information of staked tokens is used to determine a validator’s power, e.g. price ratio (price of native on-chain token / price of external stake) -- price information of native/external tokens are received from `[Slinky Oracle](https://www.notion.so/informalsystems/02-cosmolayer-oracle.md)` -- staking information of EigenLayer are received from the `Slinky Oracle` -- staking information of Bitcoin are received from Babylon's Bitcoin staking protocol +- price information of native/external tokens are received from an oracle +- staking information from external sources received from the oracle - native staking information are received from the `Cosmos SDK Staking Module` -- set of validator stakes from `Slinky Oracle` always have the current price, full set of validators, and current stakes +- set of validator stakes from oracle always have the current price, full set of validators, and current stakes The `Power Mixing` implementation -- queries current validators from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) -and from `Slinky Oracle` (see below). -- determines validator power from local and external staked validator sets -- updates validator set on cometBFT ABCI (x/staking is doing this in ValidatorUpdates 'values are overwritten in every block', ICS provider module intervenes in this behavior during `EndBlock`) +- queries current validators and their powers from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) +and from oracle (see below). +- calculates power updates by mixing power values of external an internal sources + +```golang +// MixPowers calculates power updates by mixing validator powers from different sources +func (k *Keeper) MixPowers(source ...PowerSource) []abci.ValidatorUpdate { + var valUpdate []abci.ValidatorUpdate + for _, ps := source { + valUpdate = mixPower(valUpdate, ps) + } + return valUpdate +} + +func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate { + + // GetRegisteredPowerSources (including local staking module) + registeredPowerSource := am.keeper.GetRegisteredPowerSource() + valUpdate := am.keeper.GetValidatorUpdates(registeredPowerSource...) + on_chain_validator_updates := am.staking_keeper.BlockValidatorUpdates(ctx) + oracle_validator_updates := am.orakle_keeper.GetExtValidators(ctx) + return oracle_validator_updates +} +``` + +#### Integration with `ICS provider` +The provider module updates the validator set on CometBFT instead of the SDK staking module (x/staking). The provider implementation will intervene in this behavior and ensure that the validator updates are taken from the `Power Mixing` feature + +External power sources are registered/enrolled by `Governance Proposal` and managed by the provider module. Only registered power sources can provide input to the `Power Mixing` feature. +Power sources will be assigned a unique identifier which will be used by the oracle, provider module and power mixing and rewarding feature. + +Updates with the next validator set are sent to consumer chains on each epoch (see `EndBlockVSU()`). +When collecting the validator updates for each consumer chain (see `QueueVSCPackets()`), the validator powers of the bonded validators will be updated with the validator powers from the external sources using the `Power Mixing` module. +These updates are sent as part of the VSC packets to all registered consumer chains. + +#### Integration with `ICS consumer` +Consumer chains receive validator updates as part of VSC packets from the provider. +These packets contain validator powers which were already mixed with external staked powers. + ### Queries -The following queries will be provided by `Slinky Oracle` (extension to current implementation) +```protobuf +// GetValidatorUpdates returns the power mixed validator results from the provided sources +service Query { + rpc GetValidatorUpdates(PowerMixedValUpdateRequest) PowerMixedValUpdateResponse {}; +} + +// PowerMixedValUpdateRequest contains the list of power sources on which the +// power mixing should be based on +message PowerMixedValUpdateRequest { + repeated PowerSource sources; +} + +// PowerMixedValUpdateResponse returns the validator set with the updated powers +// from the power mixing feature +message PowerMixedValUpdateResponse { + repeated abci.ValidatorUpdate val_set +} +``` + + +The following queries will be provided by the oracle ```protobuf service Query { rpc GetExtValidators(GetExtValidatorRequest) returns (ExtValidatorsResponse) { - option (google.api.http).get = "/slinky/oracle/v1/get_validators"; + option (google.api.http).get = "oracle/v1/get_validators"; }; } @@ -84,23 +146,25 @@ message ExtValidatorsResponse { } // ExtValPower represents a validator with its staking and token information, -// where `stakes` is the total amount of stakes for a validator and `denom` is the -// source token of the stake e.g. ETH,BTC.g +// where: +// `power_source_identifier` is the identifier of the registered power source +// `validator_address` is the address of the validator +// `stakes` is the total amount of stakes for a validator +// `denom` is the source token of the stake e.g. ETH,BTC +// `price_ratio` is the ratio of price of the external token to the price of the 'local' token +// message ExtValPower { + string power_source_identifier; string validator_address; uint64 stakes; string denom; + float price_ratio; } -``` - -current implementation of `Slinky Oracle` provides a query [GetPrice](https://github.com/skip-mev/slinky/blob/main/proto/slinky/oracle/v1/query.proto) -to get the latest price feed for a currency pair. - -```protobuf +// GetPrice returns a price feed for a given token service Query { rpc GetPrice(GetPriceRequest) returns (GetPriceResponse) { - option (google.api.http).get = "/slinky/oracle/v1/get_price"; + option (google.api.http).get = "/oracle/v1/get_price"; }; } ``` @@ -111,7 +175,7 @@ For security reasons the amount of external stakes needs to be limited. Limitati For native staked tokens the `Distribution Module` of the Cosmos SDK is taking care of sending the rewards to stakers. For stakes originated from external chains (Ethereum/Bitcoin) the `Reward Handler` module sends rewards to EigenLayer/Babylon. -The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and Eigenlayer/Babylon. +The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and EigenLayer/Babylon. Note: currently there's no support paying rewards on EigenLayer (see [here](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/)) @@ -133,7 +197,7 @@ Note: currently there's no support paying rewards on EigenLayer (see [here](http ## Questions: -- Determinism of the price feed? → yes, but capability of backtracking how a price was determined by `Slinky Oracle` needs to be checked (TODO) +- Determinism of the price feed? → yes, but capability of backtracking how a price was determined by oracle needs to be checked (TODO) - Slashing: subject of this ADR? (Defined but [not activated](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/) currently on EigenLayer). ## References @@ -141,6 +205,5 @@ Note: currently there's no support paying rewards on EigenLayer (see [here](http > Are there any relevant PR comments, issues that led up to this, or articles > referenced for why we made the given design choice? If so link them here! -- [Slinky Oracle](https://github.com/skip-mev/slinky) - [EigenLayer](https://docs.eigenlayer.xyz/) - [Babylon](https://babylonchain.io/) From 254d43bc10fa9413d9f984afae527fb36e545a6e Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 1 May 2024 09:37:37 +0200 Subject: [PATCH 06/11] cleanup of pseudo code, power sources --- docs/docs/adrs/adr-016-cosmolayer.md | 40 +++++++++++++++------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index 0c527c75c3..18cf34d198 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -71,35 +71,40 @@ The `Power Mixing` implementation and from oracle (see below). - calculates power updates by mixing power values of external an internal sources +Following pseudo code snippet shows a possible implementation of how power mixing +feature works. ```golang +// PowerSource is an abstract entity providing validator powers which +// are used by the mixer. This can be an oracle, staking module or an +// IBC connected bridge. +type PowerSource interface { + GetValPowers() []abci.ValidatorUpdate +} + // MixPowers calculates power updates by mixing validator powers from different sources func (k *Keeper) MixPowers(source ...PowerSource) []abci.ValidatorUpdate { var valUpdate []abci.ValidatorUpdate - for _, ps := source { + for _, ps := range source { valUpdate = mixPower(valUpdate, ps) } return valUpdate } -func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate { - - // GetRegisteredPowerSources (including local staking module) - registeredPowerSource := am.keeper.GetRegisteredPowerSource() - valUpdate := am.keeper.GetValidatorUpdates(registeredPowerSource...) - on_chain_validator_updates := am.staking_keeper.BlockValidatorUpdates(ctx) - oracle_validator_updates := am.orakle_keeper.GetExtValidators(ctx) - return oracle_validator_updates +func (k *keeper) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate { + // GetPowerSources (including local staking module) + registeredPowerSource := GetPowerSources() + return am.keeper.MixPowers(registeredPowerSource...) } ``` #### Integration with `ICS provider` -The provider module updates the validator set on CometBFT instead of the SDK staking module (x/staking). The provider implementation will intervene in this behavior and ensure that the validator updates are taken from the `Power Mixing` feature +The provider module updates the validator set on CometBFT instead of the SDK staking module (x/staking). The provider implementation will intervene in this behavior and ensure that the validator updates are taken from the `Power Mixing` feature. -External power sources are registered/enrolled by `Governance Proposal` and managed by the provider module. Only registered power sources can provide input to the `Power Mixing` feature. -Power sources will be assigned a unique identifier which will be used by the oracle, provider module and power mixing and rewarding feature. +External power sources are managed by the provider module. Only registered power sources can provide input to the `Power Mixing` feature. +Power sources will be assigned a unique identifier which will be used by the oracle, provider module and the power mixing and rewarding feature. Updates with the next validator set are sent to consumer chains on each epoch (see `EndBlockVSU()`). -When collecting the validator updates for each consumer chain (see `QueueVSCPackets()`), the validator powers of the bonded validators will be updated with the validator powers from the external sources using the `Power Mixing` module. +When collecting the validator updates for each consumer chain (see [`QueueVSCPackets()`](https://pkg.go.dev/github.com/cosmos/interchain-security/v4/x/ccv/provider/keeper#Keeper.QueueVSCPackets)), the validator powers of the bonded validators will be updated with the validator powers from the external sources using the `Power Mixing` module. These updates are sent as part of the VSC packets to all registered consumer chains. #### Integration with `ICS consumer` @@ -152,13 +157,12 @@ message ExtValidatorsResponse { // `stakes` is the total amount of stakes for a validator // `denom` is the source token of the stake e.g. ETH,BTC // `price_ratio` is the ratio of price of the external token to the price of the 'local' token -// message ExtValPower { string power_source_identifier; string validator_address; uint64 stakes; string denom; - float price_ratio; + float price_ratio; } // GetPrice returns a price feed for a given token @@ -169,13 +173,13 @@ service Query { } ``` -For security reasons the amount of external stakes needs to be limited. Limitation of external staking will be driven by a `Governance Proposal`. +For security reasons the amount of external stakes needs to be limited. Limitation of external staking could be driven by governance and is not subject of this version of the ADR. ### Reward Handler For native staked tokens the `Distribution Module` of the Cosmos SDK is taking care of sending the rewards to stakers. For stakes originated from external chains (Ethereum/Bitcoin) the `Reward Handler` module sends rewards to EigenLayer/Babylon. -The transfer of rewards is done using a [bridge](https://ethereum.org/en/bridges/) between the Cosmos chain and EigenLayer/Babylon. +The transfer of rewards is done using a bridge between the Cosmos chain and the external provider chain. Note: currently there's no support paying rewards on EigenLayer (see [here](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/)) @@ -196,8 +200,6 @@ Note: currently there's no support paying rewards on EigenLayer (see [here](http * Additional complexity for staking ## Questions: - -- Determinism of the price feed? → yes, but capability of backtracking how a price was determined by oracle needs to be checked (TODO) - Slashing: subject of this ADR? (Defined but [not activated](https://www.coindesk.com/tech/2024/04/10/eigenlayer-cryptos-biggest-project-launch-this-year-is-still-missing-crucial-functionality/) currently on EigenLayer). ## References From 0079a1e697cb9492709e5ec9e187eb1486177f38 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 8 May 2024 10:20:28 +0200 Subject: [PATCH 07/11] renaming to security aggregation --- docs/docs/adrs/adr-016-cosmolayer.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-cosmolayer.md index 18cf34d198..a248838bd9 100644 --- a/docs/docs/adrs/adr-016-cosmolayer.md +++ b/docs/docs/adrs/adr-016-cosmolayer.md @@ -1,4 +1,4 @@ -# ADR 016: CosmoLayer +# ADR 016: Security aggregation ## Changelog @@ -10,14 +10,14 @@ Draft ## Context -CosmoLayer enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating CosmoLayer, a Cosmos blockchain can be secured by both native tokens and external tokens (e.g., ETH, BTC). +Security Aggregation enables staking of tokens from external sources such as Ethereum or Bitcoin to Cosmos blockchains. By integrating Security Aggregation, a Cosmos blockchain can be secured by both native tokens and external tokens (e.g. ETH, BTC). -CosmoLayer consists of the following four parts: +Security Aggregation consists of the following parts: - A mechanism for delegating external tokens to Cosmos validators, such as Babylon or EigenLayer AVS contract. - An oracle that tracks how much external stake has been delegated to each Cosmos validator and provides price feeds for external tokens. -- Power mixing: A mechanism to combine external and native stake to derive the power of each validator. -- A bridge that enables sending back rewards to the external source. +- Power mixing: a mechanism to combine external and native stake to derive the power of each validator. +- A reward distribution protocol that enables sending back rewards to the external source. External staking information is received from an oracle together with price information of related stakes. The CosmosLayer derives validator powers based on external and native staking information and initiates rewarding of external depositors. @@ -47,7 +47,7 @@ Rewards will be sent back to external chains instead of paying rewards for exter ## Detailed Design -The `Power Mixing` feature and `Reward Distribution` protocol are an integral part of the CosmoLayer solution. +The `Power Mixing` feature and `Reward Distribution` protocol are an integral part of the Security Aggregation solution. The `Power Mixing` module provides the capability of deriving validator power based on stake originated from external sources such as Ethereum/Bitcoin and the native staking module. The `Reward Distribution` is in charge of sending rewards to external stakers. From 935dd3a9e2498daac38ee8f025124cefa625eea1 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 8 May 2024 10:22:14 +0200 Subject: [PATCH 08/11] mv adr --- .../{adr-016-cosmolayer.md => adr-016-securityaggregation.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/docs/adrs/{adr-016-cosmolayer.md => adr-016-securityaggregation.md} (100%) diff --git a/docs/docs/adrs/adr-016-cosmolayer.md b/docs/docs/adrs/adr-016-securityaggregation.md similarity index 100% rename from docs/docs/adrs/adr-016-cosmolayer.md rename to docs/docs/adrs/adr-016-securityaggregation.md From 65c61f0bf24612155646e60fc8418cef590a6432 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 8 May 2024 11:32:09 +0200 Subject: [PATCH 09/11] removed comments --- docs/docs/adrs/adr-016-securityaggregation.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/docs/adrs/adr-016-securityaggregation.md b/docs/docs/adrs/adr-016-securityaggregation.md index a248838bd9..c2b55469d3 100644 --- a/docs/docs/adrs/adr-016-securityaggregation.md +++ b/docs/docs/adrs/adr-016-securityaggregation.md @@ -26,9 +26,6 @@ This ADR describes the _Cosmos modules_ of the solution. ## Alternative Approaches -> This section contains information around alternative options that are considered -> before making a decision. It should contain a explanation on why the alternative -> approach(es) were not chosen. ### Rewards As an alternative for sending rewards back to the external chains, stakers could be rewarded on the Cosmos chain. This would require a mapping of external addresses to addresses on Cosmos chain for each staker on external source. @@ -36,10 +33,6 @@ In addition detailed external staking information such as staking addresses, amo ## Decision -> This section records the decision that was made. -> It is best to record as much info as possible from the discussion that happened. -> This aids in not having to go back to the Pull Request to get the needed information. - ### Rewards Rewards will be sent back to external chains instead of paying rewards for external stakers on Cosmos chain - due to amount of additional staking information to be sent and tracked by the oracle @@ -185,9 +178,6 @@ Note: currently there's no support paying rewards on EigenLayer (see [here](http ## Consequences -> This section describes the consequences, after applying the decision. All -> consequences should be summarized here, not just the "positive" ones. - ### Positive * Allow external depositors to stake their tokens to secure a Cosmos chain @@ -204,8 +194,5 @@ Note: currently there's no support paying rewards on EigenLayer (see [here](http ## References -> Are there any relevant PR comments, issues that led up to this, or articles -> referenced for why we made the given design choice? If so link them here! - - [EigenLayer](https://docs.eigenlayer.xyz/) - [Babylon](https://babylonchain.io/) From d83913c19519c7cf26c8262b1600ebbc4acac549 Mon Sep 17 00:00:00 2001 From: Bernd Mueller Date: Wed, 8 May 2024 11:42:39 +0200 Subject: [PATCH 10/11] minor change in code example --- docs/docs/adrs/adr-016-securityaggregation.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docs/adrs/adr-016-securityaggregation.md b/docs/docs/adrs/adr-016-securityaggregation.md index c2b55469d3..02542fb6ee 100644 --- a/docs/docs/adrs/adr-016-securityaggregation.md +++ b/docs/docs/adrs/adr-016-securityaggregation.md @@ -71,14 +71,16 @@ feature works. // are used by the mixer. This can be an oracle, staking module or an // IBC connected bridge. type PowerSource interface { - GetValPowers() []abci.ValidatorUpdate + GetValidatorUpdates() []abci.ValidatorUpdate } // MixPowers calculates power updates by mixing validator powers from different sources func (k *Keeper) MixPowers(source ...PowerSource) []abci.ValidatorUpdate { var valUpdate []abci.ValidatorUpdate for _, ps := range source { - valUpdate = mixPower(valUpdate, ps) + // mix powers from two sets of validator updates an return set of validator updates + // with aggregated powers + valUpdate = mixPower(valUpdate, ps.GetValidatorUpdates()) } return valUpdate } @@ -86,7 +88,7 @@ func (k *Keeper) MixPowers(source ...PowerSource) []abci.ValidatorUpdate { func (k *keeper) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate { // GetPowerSources (including local staking module) registeredPowerSource := GetPowerSources() - return am.keeper.MixPowers(registeredPowerSource...) + return k.MixPowers(registeredPowerSource...) } ``` From 71b956855fe9457fb728230d803434272e328bf9 Mon Sep 17 00:00:00 2001 From: Jehan Date: Wed, 8 May 2024 07:37:13 -0700 Subject: [PATCH 11/11] Apply suggestions from code review Grammar Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/docs/adrs/adr-016-securityaggregation.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/docs/adrs/adr-016-securityaggregation.md b/docs/docs/adrs/adr-016-securityaggregation.md index 02542fb6ee..9ff4134854 100644 --- a/docs/docs/adrs/adr-016-securityaggregation.md +++ b/docs/docs/adrs/adr-016-securityaggregation.md @@ -27,13 +27,13 @@ This ADR describes the _Cosmos modules_ of the solution. ## Alternative Approaches ### Rewards -As an alternative for sending rewards back to the external chains, stakers could be rewarded on the Cosmos chain. +As an alternative to sending rewards back to the external chains, stakers could be rewarded on the Cosmos chain. This would require a mapping of external addresses to addresses on Cosmos chain for each staker on external source. -In addition detailed external staking information such as staking addresses, amount of stakes per staker and validator, etc have to be provided by the oracle. +In addition detailed external staking information such as staking addresses, amount of stakes per staker and validator, etc. have to be provided by the oracle. ## Decision -### Rewards +### Rewards will be sent back to external chains instead of paying rewards for external stakers on Cosmos chain Rewards will be sent back to external chains instead of paying rewards for external stakers on Cosmos chain - due to amount of additional staking information to be sent and tracked by the oracle - due to the additional complexity of managing external and Cosmos addresses @@ -42,7 +42,7 @@ Rewards will be sent back to external chains instead of paying rewards for exter The `Power Mixing` feature and `Reward Distribution` protocol are an integral part of the Security Aggregation solution. The `Power Mixing` module provides the capability of deriving validator power based on stake originated from external sources such as Ethereum/Bitcoin and the native staking module. -The `Reward Distribution` is in charge of sending rewards to external stakers. +The `Reward Distribution` manages the process of sending rewards to external stakers. ### Power Mixing @@ -62,9 +62,8 @@ Requirements: The `Power Mixing` implementation - queries current validators and their powers from [x/staking](https://github.com/cosmos/cosmos-sdk/blob/a6f3fbfbeb7ea94bda6369a7163a523e118a123c/x/staking/types/staking.pb.go#L415) and from oracle (see below). -- calculates power updates by mixing power values of external an internal sources - -Following pseudo code snippet shows a possible implementation of how power mixing +- calculates power updates by mixing power values of external and internal sources +Following pseudocode snippet shows a possible implementation of how power mixing feature works. ```golang // PowerSource is an abstract entity providing validator powers which