From 68169611c12bc609b4ecaa99c50f0e2166986eb9 Mon Sep 17 00:00:00 2001 From: riley-stride <104941670+riley-stride@users.noreply.github.com> Date: Thu, 15 Dec 2022 13:58:05 -0500 Subject: [PATCH] chore: markdownlint . --fix (#514) --- x/README.md | 9 ++++++--- x/claim/README.md | 20 ++++++++++---------- x/icacallbacks/README.md | 11 ++++++++++- x/interchainquery/README.md | 28 +++++++++++++++------------- x/mint/README.md | 15 +++++++-------- x/records/README.md | 11 +++++++++-- x/stakeibc/README.md | 24 ++++++++++++++++-------- 7 files changed, 73 insertions(+), 45 deletions(-) diff --git a/x/README.md b/x/README.md index 1b7e781ec..6a4c5257f 100644 --- a/x/README.md +++ b/x/README.md @@ -9,7 +9,7 @@ category: 62c5c5ff03a5bf069004def2 `stakeibc` - Manages minting and burning of stAssets, staking and unstaking of native assets across chains. `icacallbacks` - Callbacks for interchain accounts. `records` - IBC middleware wrapping the transfer module, does record keeping on IBC transfers and ICA calls -`claim` - airdrop logic for Stride's rolling, task-based airdrop +`claim` - airdrop logic for Stride's rolling, task-based airdrop `interchainquery` - Issues queries between IBC chains, verifies state proof and executes callbacks. `epochs` - Makes on-chain timers which other modules can execute code during. `mint` - Controls token supply emissions, and what modules they are directed to. @@ -21,13 +21,16 @@ Stride is proud to be an open-source project, and we welcome all other projects We operate under the Apache 2.0 License, and have used the following modules from fellow Cosmos projects. Huge thank you to these projects! We use the following modules from [Osmosis](https://github.com/osmosis-labs/osmosis) provided under [this License](https://github.com/osmosis-labs/osmosis/blob/main/LICENSE): + ``` x/epochs x/mint ``` -We use the following module (marketed as public infra) from [Quicksilver](https://github.com/ingenuity-build/quicksilver) provided under [this License](https://github.com/ingenuity-build/quicksilver/blob/main/LICENSE): + +We use the following module (marketed as public infra) from [Quicksilver](https://github.com/ingenuity-build/quicksilver) provided under [this License](https://github.com/ingenuity-build/quicksilver/blob/main/LICENSE): + ``` x/interchainqueries ``` -Relevant licenses with full attribution can be found in the relevant repo subdirectories. \ No newline at end of file +Relevant licenses with full attribution can be found in the relevant repo subdirectories. diff --git a/x/claim/README.md b/x/claim/README.md index 1ab120ca9..4d0dd4045 100644 --- a/x/claim/README.md +++ b/x/claim/README.md @@ -7,6 +7,7 @@ category: 6392913957c533007128548e # The Claim Module Users are required participate in core network activities to claim their airdrop. An Airdrop recipient is given 20% of the airdrop amount which is not in vesting, and then they have to perform the following activities to get the rest: + * 20% vesting over 3 months by staking * 60% vesting over 3 months by liquid staking @@ -35,20 +36,20 @@ Every action must be performed to claim the full amount. A claim record is a struct that contains data about the claims process of each airdrop recipient. -It contains an address, the initial claimable airdrop amount, and an array of bools representing +It contains an address, the initial claimable airdrop amount, and an array of bools representing whether each action has been completed. The position in the array refers to enum number of the action. So for example, `[true, true]` means that `ActionLiquidStake` and `ActionDelegateStake` are completed. ```golang type ClaimRecord struct { - // address of claim user - Address string - // weight that represent the portion from total allocation - Weight sdk.Dec - // true if action is completed - // index of bool in array refers to action enum # - ActionCompleted []bool + // address of claim user + Address string + // weight that represent the portion from total allocation + Weight sdk.Dec + // true if action is completed + // index of bool in array refers to action enum # + ActionCompleted []bool } ``` @@ -116,6 +117,7 @@ message ClaimRecord { ]; } ``` + When a user get airdrop for his/her action, claim record is created to prevent duplicated actions on future actions. ### State @@ -138,7 +140,6 @@ message GenesisState { Claim module's state consists of `params`, and `claim_records`. - Claim module provides below params ```protobuf @@ -214,4 +215,3 @@ strided query claim total-claimable $(strided keys show -a {your key name}) Acti | ----- | ------------- | --------------- | | claim | sender | {receiver} | | claim | amount | {claim_amount} | - diff --git a/x/icacallbacks/README.md b/x/icacallbacks/README.md index 7ae086930..d762e9fe3 100644 --- a/x/icacallbacks/README.md +++ b/x/icacallbacks/README.md @@ -12,6 +12,7 @@ The challenges faced before creating the icacallbacks modules were: (1) Messages must be handled one-off (by matching on message type) - really what we want to do is update state in acks based on the _transaction_ sent (2) Message responses are almost always empty, e.g. `MsgDelegateResponse`, which leads to (3) Matching processed messages to state on the controller is very challenging (sometimes impossible) based on the attributes of the message sent. For example, given the following type + ``` type Gift struct { from string @@ -20,14 +21,17 @@ type Gift struct { reason string } ``` + two ICA bank sends associated with gifts that have the same `from`, `to` and `amount` but _different_ `reasons` are indistinguishable today in acks. `icacontroller` solves the issues as follows + - Callbacks can be registered to process data associated with a particular IBC packet, per module (solves 1) - ICA auth modules can store callback data using `icacallbacks`, passing in both a callback and args - Arguments to the callback can be (un)marshaled and contain arbitrary keys, allowing for updates to data on the controller chain based on the success / failure of the ICA call (solves 2 / 3) ### Technical notes + - Callbacks are uniquely identifiable through `portId/channelId/sequence` keys - Only modules that have registered callbacks can invoke them - `icacallbacks` doesn't have a message server / handler (it can only be called by other modules) @@ -37,6 +41,7 @@ two ICA bank sends associated with gifts that have the same `from`, `to` and `am - We're using protos to serialize / deserialize callback arguments The flow to add callbacks is to call `ICACallbacksKeeper.SetCallbackData` after sending an IBC transaction. When the ack returns + - the callback is fetched using the callback key - the module is fetched using the portId / channelId and the callback is invoked and deleted. @@ -45,17 +50,21 @@ The middleware structure is as follows ![middleware](https://user-images.githubusercontent.com/1331345/183272460-5225d67d-95ee-47e2-8200-11de013a0695.png) ### Invariants + - `portId, channelId` pair map to a unique module (important for fetching the correct `CallbackHandler` from a received packet) - callback ids are unique within modules (they don't have to be unique between modules, because `CallICACallback` is scoped to a module) ## Keeper functions + - `CallRegisteredICACallback()`: invokes the relevant callback asssociated with an ICA ## State + - `CallbackData`: stores the callback type, arguments and associated packet - `CallbackHandler` - `Callbacks` - `Callback` ## Events -The `icacallbacks` module does not currently emit any events. + +The `icacallbacks` module does not currently emit any events. diff --git a/x/interchainquery/README.md b/x/interchainquery/README.md index 126b90726..baaf887c4 100644 --- a/x/interchainquery/README.md +++ b/x/interchainquery/README.md @@ -14,6 +14,7 @@ parent: # Interchain Query ## Abstract + Stride uses interchain queries and interchain accounts to perform multichain liquid staking. The `interchainquery` module creates a framework that allows other modules to query other appchains using IBC. The `interchainquery` module is used to make bank balance ICQ queries to withdrawal account every N. The callback triggers ICA bank sends for 90% of the rewards to the delegation account and 10% to the stride hostzone revenue account. The ICA bank send logic is in x/stakeibc/keeper/callbacks.go. ## Contents @@ -21,7 +22,7 @@ Stride uses interchain queries and interchain accounts to perform multichain liq 1. **[Concepts](#concepts)** 2. **[State](#state)** 3. **[Events](#events)** -4. **[Keeper](#keeper)** +4. **[Keeper](#keeper)** 5. **[Msgs](#msgs)** 6. **[Queries](#queries)** @@ -56,22 +57,23 @@ The `interchainquery` module emits an event at the end of every `stride_epoch`s The purpose of this event is to send interchainqueries that query data about staking rewards, which Stride uses to reinvest (aka autocompound) staking rewards. ```go - event := sdk.NewEvent( - sdk.EventTypeMessage, - sdk.NewAttribute(sdk.AttributeKeyModule, types.AttributeValueCategory), - sdk.NewAttribute(sdk.AttributeKeyAction, types.AttributeValueQuery), - sdk.NewAttribute(types.AttributeKeyQueryId, queryInfo.Id), - sdk.NewAttribute(types.AttributeKeyChainId, queryInfo.ChainId), - sdk.NewAttribute(types.AttributeKeyConnectionId, queryInfo.ConnectionId), - sdk.NewAttribute(types.AttributeKeyType, queryInfo.QueryType), - sdk.NewAttribute(types.AttributeKeyHeight, "0"), - sdk.NewAttribute(types.AttributeKeyRequest, hex.EncodeToString(queryInfo.Request)), - ) + event := sdk.NewEvent( + sdk.EventTypeMessage, + sdk.NewAttribute(sdk.AttributeKeyModule, types.AttributeValueCategory), + sdk.NewAttribute(sdk.AttributeKeyAction, types.AttributeValueQuery), + sdk.NewAttribute(types.AttributeKeyQueryId, queryInfo.Id), + sdk.NewAttribute(types.AttributeKeyChainId, queryInfo.ChainId), + sdk.NewAttribute(types.AttributeKeyConnectionId, queryInfo.ConnectionId), + sdk.NewAttribute(types.AttributeKeyType, queryInfo.QueryType), + sdk.NewAttribute(types.AttributeKeyHeight, "0"), + sdk.NewAttribute(types.AttributeKeyRequest, hex.EncodeToString(queryInfo.Request)), + ) ``` ## Keeper ### Keeper Functions + `interchainquery/keeper/` module provides utility functions to manage ICQs ```go @@ -102,9 +104,9 @@ message MsgSubmitQueryResponse { ``` ## Queries + ```protobuf // Query PendingQueries lists all queries that have been requested (i.e. emitted) // but have not had a response submitted yet message QueryPendingQueriesRequest {} ``` - diff --git a/x/mint/README.md b/x/mint/README.md index b2b93b3a1..607c8d7d2 100644 --- a/x/mint/README.md +++ b/x/mint/README.md @@ -17,6 +17,7 @@ The `x/distribution` module is responsible for allocating tokens to stakers, com The mint module uses time basis epochs from the `x/epochs` module. The `x/mint` module is designed by Osmosis. It is used to handle the regular printing of new tokens within a chain. Its core function is to: + - Mint new tokens once per epoch (default one week) - Have a "Reductioning factor" every period, which reduces the amount of rewards per epoch. (default: period is 3 years, where a year is 52 epochs. The next period's rewards are 2/3 of the prior period's rewards) @@ -32,9 +33,9 @@ type Params struct { EpochIdentifier string // identifier of epoch ReductionPeriodInEpochs int64 // number of epochs between reward reductions ReductionFactor sdk.Dec // reduction multiplier to execute on each period - DistributionProportions DistributionProportions // distribution_proportions defines the proportion of the minted denom - WeightedDeveloperRewardsReceivers []WeightedAddress // address to receive developer rewards - MintingRewardsDistributionStartEpoch int64 // start epoch to distribute minting rewards + DistributionProportions DistributionProportions // distribution_proportions defines the proportion of the minted denom + WeightedDeveloperRewardsReceivers []WeightedAddress // address to receive developer rewards + MintingRewardsDistributionStartEpoch int64 // start epoch to distribute minting rewards } ``` @@ -54,8 +55,6 @@ The minting module contains the following parameters: | weighted_developer_rewards_receivers | array | [{"address": "osmoxx", "weight": "1"}] | | minting_rewards_distribution_start_epoch | int64 | 10 | - - ## EpochProvision Calculate the provisions generated for each epoch based on current epoch provisions. The provisions are then minted by the `mint` module's `ModuleMinterAccount`. These rewards are transferred to a `FeeCollector`, which handles distributing the rewards per the chains needs. (See TODO.md for details) This fee collector is specified as the `auth` module's `FeeCollector` `ModuleAccount`. @@ -68,6 +67,7 @@ func (m Minter) EpochProvision(params Params) sdk.Coin { ``` **Notes** + 1. `mint_denom` defines denom for minting token - uosmo 2. `genesis_epoch_provisions` provides minting tokens per epoch at genesis. 3. `epoch_identifier` defines the epoch identifier to be used for mint module e.g. "weekly" @@ -77,7 +77,6 @@ func (m Minter) EpochProvision(params Params) sdk.Coin { 7. `weighted_developer_rewards_receivers` provides the addresses that receives developer rewards by weight 8. `minting_rewards_distribution_start_epoch` defines the start epoch of minting to make sure minting start after initial pools are set - ## Begin-Epoch Minting parameters are recalculated and inflation @@ -95,6 +94,7 @@ func (m Minter) NextEpochProvisions(params Params) sdk.Dec { return m.EpochProvisions.Mul(params.ReductionFactor) } ``` + ## Reductioning factor This is a generalization over the Bitcoin style halvenings. @@ -119,7 +119,6 @@ The minting module emits the following events: | mint | epoch_provisions | {epochProvisions} | | mint | amount | {amount} | - ## Minter The minter is a space for holding current rewards information. @@ -128,4 +127,4 @@ The minter is a space for holding current rewards information. type Minter struct { EpochProvisions sdk.Dec // Rewards for the current epoch } -``` \ No newline at end of file +``` diff --git a/x/records/README.md b/x/records/README.md index 76ebb12aa..ef76f7f10 100644 --- a/x/records/README.md +++ b/x/records/README.md @@ -6,17 +6,19 @@ category: 6392913957c533007128548e # The Records Module -The records module handles record keeping and accounting for the Stride blockchain. +The records module handles record keeping and accounting for the Stride blockchain. It is [IBC middleware](https://ibc.cosmos.network/main/ibc/middleware/develop.html). IBC middleware wraps core IBC modules and other middlewares. Specifically, the records module adds a middleware stack to `app.go` with the following structure: `records -> transfer`. All ibc packets routed to the `transfer` module will first pass through `records`, where we can apply custom logic (record keeping) before passing messages to the underlying `transfer` module. Note: + - The middleware stack is added in `app.go` - The custom handler logic is added in `ibc_module.go` by implementing the IBCModule interface ## Keeper functions Deposit Records + - `GetDepositRecordCount()` - `SetDepositRecordCount()` - `AppendDepositRecord()` @@ -27,6 +29,7 @@ Deposit Records - `GetDepositRecordByEpochAndChain()` Epoch Unbonding Records + - `SetEpochUnbondingRecord()` - `GetEpochUnbondingRecord()` - `RemoveEpochUnbondingRecord()` @@ -37,6 +40,7 @@ Epoch Unbonding Records - `SetHostZoneUnbondings()` User Redemption Records + - `SetUserRedemptionRecord()` - `GetUserRedemptionRecord()` - `RemoveUserRedemptionRecord()` @@ -46,9 +50,11 @@ User Redemption Records ## State Callbacks + - `TransferCallback` Genesis + - `UserRedemptionRecord` - `Params` - `RecordsPacketData` @@ -70,4 +76,5 @@ Genesis - `AllEpochUnbondingRecord` ## Events -The `records` module emits does not currently emit any events. + +The `records` module emits does not currently emit any events. diff --git a/x/stakeibc/README.md b/x/stakeibc/README.md index fc86c835e..f2b23f6b4 100644 --- a/x/stakeibc/README.md +++ b/x/stakeibc/README.md @@ -7,19 +7,21 @@ category: 6392913957c533007128548e # The StakeIBC Module The StakeIBC Module contains Stride's main app logic: + - it exposes core liquid staking entry points to the user (liquid staking and redeeming) - it executes automated beginBlocker and endBlocker logic to stake funds on relevant host zones using Interchain Accounts - it handles registering new host zones and adjusting host zone validator sets and weights - it defines Stride's core data structures (e.g. hostZone) -- it defines all the callbacks used when issuing Interchain Account logic +- it defines all the callbacks used when issuing Interchain Account logic -Nearly all of Stride's functionality is built using interchain accounts (ICAs), which are a new functionality in Cosmos, and a critical component of IBC. ICAs allow accounts on Zone A to be controlled by Zone B. ICAs communicate with one another using Interchain Queries (ICQs), which involve Zone A querying Zone B for relevant information. +Nearly all of Stride's functionality is built using interchain accounts (ICAs), which are a new functionality in Cosmos, and a critical component of IBC. ICAs allow accounts on Zone A to be controlled by Zone B. ICAs communicate with one another using Interchain Queries (ICQs), which involve Zone A querying Zone B for relevant information. Two Zones communicate via a connection and channel. All communications between the Controller Zone (the chain that is querying) and the Host Zone (the chain that is being queried) is done through a dedicated IBC channel between the two chains, which is opened the first time the two chains interact. For context, ICS standards define that each channel is associated with a particular connection, and a connection may have any number of associated channels. ## Params + ``` DepositInterval (default uint64 = 1) DelegateInterval (default uint64 = 1) @@ -56,30 +58,35 @@ SafetyNumValidators (default uint64 = 35) ## State Callbacks + - `SplitDelegation` -- `DelegateCallback` -- `ClaimCallback` -- `ReinvestCallback` -- `UndelegateCallback` -- `RedemptionCallback` +- `DelegateCallback` +- `ClaimCallback` +- `ReinvestCallback` +- `UndelegateCallback` +- `RedemptionCallback` - `Rebalancing` -- `RebalanceCallback` +- `RebalanceCallback` HostZone + - `HostZone` - `ICAAccount` - `MinValidatorRequirements` Host Zone Validators + - `Validator` - `ValidatorExchangeRate` Misc + - `GenesisState` - `EpochTracker` - `Delegation` Governance + - `AddValidatorProposal` ## Queries @@ -109,6 +116,7 @@ Governance Type: Attribute Key → Attribute Value -------------------------------------------------- + registerHostZone: module → stakeibc registerHostZone: connectionId → connectionId registerHostZone: chainId → chainId