Skip to content

Commit

Permalink
docs: update staking params
Browse files Browse the repository at this point in the history
  • Loading branch information
@MSalopek
MSalopek committed Feb 12, 2024
1 parent dfc0b06 commit 8110bd6
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 92 deletions.
40 changes: 9 additions & 31 deletions docs/docs/governance/current-parameters.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,32 +93,6 @@ export const currentParams = {
min_deposit_ratio: "0.010000000000000000",
},
},
liquidity: {
CircuitBreakerEnabled: false,
InitPoolCoinMintAmount: "1000000",
MaxOrderAmountRatio: "0.100000000000000000",
MaxReserveCoinAmount: "0",
MinInitDepositAmount: "1000000",
PoolCreationFee: [
{
amount: "40000000",
denom: "uatom",
},
],
PoolTypes: [
{
description:
"Standard liquidity pool with pool price function X/Y, ESPM constraint, and two kinds of reserve coins",
id: 1,
max_reserve_coin_num: 2,
min_reserve_coin_num: 2,
name: "StandardLiquidityPool",
},
],
SwapFeeRate: "0.003000000000000000",
UnitBatchHeight: 1,
WithdrawFeeRate: "0.000000000000000000",
},
mint: {
blocks_per_year: "4360000",
goal_bonded: "0.670000000000000000",
Expand All @@ -135,11 +109,15 @@ export const currentParams = {
slash_fraction_downtime: "0.000100000000000000",
},
staking: {
BondDenom: "uatom",
HistoricalEntries: 10000,
MaxEntries: 7,
MaxValidators: 180,
UnbondingTime: "1814400000000000",
unbonding_time: "86400s",
max_validators: 100,
max_entries: 7,
historical_entries: 10000,
bond_denom: "stake",
min_commission_rate: "0.000000000000000000",
validator_bond_factor: "-1.000000000000000000",
global_liquid_staking_cap: "1.000000000000000000",
validator_liquid_staking_cap: "1.000000000000000000",
},
transfer: {
ReceiveEnabled: true,
Expand Down
54 changes: 29 additions & 25 deletions docs/docs/governance/proposal-types/params-change/Staking.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
---
title: staking subspace
title: x/staking
---

```shell
gaiad q staking params
```

import { KeyValueTable } from '@site/src/js/KeyValueTable';
import { Var } from '@site/src/js/Var';
import { currentParams } from '@site/docs/governance/current-parameters.js';
Expand All @@ -14,51 +18,51 @@ The `staking` module is responsible for supporting an advanced Proof of Stake (P

## Governance notes on parameters

### `UnbondingTime`
### `unbonding_time`

**The time duration required for bonded ATOMs to unbond and become transferrable, in nanoseconds.**

- on-chain value: <Var children={currentParams.staking.UnbondingTime} />
- on-chain value: <Var children={currentParams.staking.unbonding_time} />
- `cosmoshub-4` default: `1814400000000000`
- `cosmoshub-3` default: `1814400000000000`

In order to participate as a Cosmos Hub validator or delegator, ATOMs must be bonded (also known as staking). Once bonded, ATOMs are locked by the protocol and are no longer transferrable. When ATOM unbonding is initiated, the `UnbondingTime` of 1814400000000000 nanoseconds (21 days) duration must pass before the ATOMs will be unlocked and transferrable.
In order to participate as a Cosmos Hub validator or delegator, ATOMs must be bonded (also known as staking). Once bonded, ATOMs are locked by the protocol and are no longer transferrable. When ATOM unbonding is initiated, the `unbonding_time` of 1814400000000000 nanoseconds (21 days) duration must pass before the ATOMs will be unlocked and transferrable.

ATOMs are used as a bond when staking. A bond may be slashed (ie. partially destroyed) when a validator has been proven to have broken protocol rules. Why? Primarily as a solution to the "[nothing-at-stake](https://medium.com/coinmonks/understanding-proof-of-stake-the-nothing-at-stake-theory-1f0d71bc027)" problem. In the scenario of an accidental or malicious attempt to rewrite history and reverse a transaction, a new chain ("fork") may be created in parallel with the primary chain. Without the risk of losing this bond, the optimal strategy for any validator is to validate blocks on both chains so that the validator gets their reward no matter which fork wins. A bond makes it more likely that the optimal strategy for validators will be to only validate blocks for the true ("canonical") chain.

Why is `UnbondingTime` so long? It can take time to discover that a validator has committed equivocation ie. signed two blocks at the same block height. If a validator commits equivocation and then unbonds before being caught, the protocol can no longer slash (ie. partially destroy) the validator's bond.
Why is `unbonding_time` so long? It can take time to discover that a validator has committed equivocation ie. signed two blocks at the same block height. If a validator commits equivocation and then unbonds before being caught, the protocol can no longer slash (ie. partially destroy) the validator's bond.

#### Decreasing the value of `UnbondingTime`
#### Decreasing the value of `unbonding_time`

Decreasing the value of the `UnbondingTime` parameter will reduce the time it takes to unbond ATOMs. This will make it less likely for a validator's bond to be slashed after committing equivocation (aka double-signing).
Decreasing the value of the `unbonding_time` parameter will reduce the time it takes to unbond ATOMs. This will make it less likely for a validator's bond to be slashed after committing equivocation (aka double-signing).

#### Increasing the value of `UnbondingTime`
#### Increasing the value of `unbonding_time`

Increasing the value of the `UnbondingTime` parameter will increase the time it takes to unbond ATOMs. This will make it more likely for a validator's bond to be slashed after committing equivocation (aka double-signing).
Increasing the value of the `unbonding_time` parameter will increase the time it takes to unbond ATOMs. This will make it more likely for a validator's bond to be slashed after committing equivocation (aka double-signing).

#### Notes

The ability to punish a validator for committing equivocation is associated with the strength of the protocol's security guarantees.

1 second is equal to 1,000,000,000 nanoseconds.

## `MaxValidators`
## `max_validators`

**The maximum number of validators that may participate in validating blocks, earning rewards, and governance voting.**

- on-chain value: <Var children={currentParams.staking.MaxValidators} />
- on-chain value: <Var children={currentParams.staking.max_validators} />
- `cosmoshub-4` default: `125`
- `cosmoshub-3` default: `125`

Validators are ranked by stake-backing based upon the sum of their delegations, and only the top 125 are designated to be active (aka "the active set"). The active set may change any time delegation amounts change. Only active validators may participate in validating blocks, earning rewards, and governance voting. ATOM-holders may participate in staking by delegating their bonded ATOMs to one or more validators in the active set. Delegators may only earn rewards and have their governance votes count if they are delegating to an active validator, the set of which is capped by `MaxValidators`.
Validators are ranked by stake-backing based upon the sum of their delegations, and only the top 125 are designated to be active (aka "the active set"). The active set may change any time delegation amounts change. Only active validators may participate in validating blocks, earning rewards, and governance voting. ATOM-holders may participate in staking by delegating their bonded ATOMs to one or more validators in the active set. Delegators may only earn rewards and have their governance votes count if they are delegating to an active validator, the set of which is capped by `max_validators`.

#### Decreasing the value of `MaxValidators`
#### Decreasing the value of `max_validators`

Decreasing the value of the `MaxValidators` parameter will likely reduce the number of validators actively participating in validating blocks, earning rewards, and governance voting for the Cosmos Hub. This may decrease the time it takes to produce each new Cosmos Hub block.
Decreasing the value of the `max_validators` parameter will likely reduce the number of validators actively participating in validating blocks, earning rewards, and governance voting for the Cosmos Hub. This may decrease the time it takes to produce each new Cosmos Hub block.

#### Increasing the value of `MaxValidators`
#### Increasing the value of `max_validators`

Increasing the value of the `MaxValidators` parameter will likely increase the number of validators actively participating in validating blocks, earning rewards, and governance voting for the Cosmos Hub. This may increase the time it takes to produce each new Cosmos Hub block.
Increasing the value of the `max_validators` parameter will likely increase the number of validators actively participating in validating blocks, earning rewards, and governance voting for the Cosmos Hub. This may increase the time it takes to produce each new Cosmos Hub block.

#### Notes

Expand All @@ -68,8 +72,8 @@ It may be argued that after the Cosmos creators, the validator cohort may be the

### `KeyMaxEntries`

- **The maximum number of unbondings between a delegator and validator within the [unbonding period](#UnbondingTime).**
- **A delegator's maximum number of simultaneous redelegations from one validator to another validator within the [unbonding period](#1-UnbondingTime).**
- **The maximum number of unbondings between a delegator and validator within the [unbonding period](#unbonding_time).**
- **A delegator's maximum number of simultaneous redelegations from one validator to another validator within the [unbonding period](#1-unbonding_time).**

- on-chain value: <Var children={currentParams.staking.KeyMaxEntries} />
- `cosmoshub-4` default: `7`
Expand All @@ -89,25 +93,25 @@ Increasing the value of the `KeyMaxEntries` parameter will, within the unbonding

Aleksandr (All in Bits; Fission Labs) wrote more about `KeyMaxEntries` [here in this article](https://blog.cosmos.network/re-delegations-in-the-cosmos-hub-7d2f5ea59f56).

### `BondDenom`
### `bond_denom`

**The unit and denomination for the asset bonded in the system.**

- on-chain value: <Var children={currentParams.staking.BondDenom} />
- on-chain value: <Var children={currentParams.staking.bond_denom} />
- `cosmoshub-4` default: `uatom`
- `cosmoshub-3` default: `uatom`

When using an asset as a bond on the Cosmos Hub, the unit and denomination of the asset is denoted as the `uatom`, or micro-ATOM, where 1 ATOM is considered 1000000uatom. The protocol doesn't use ATOM for bonds, only uatom.

#### Changing the value of `BondDenom`
#### Changing the value of `bond_denom`

Changing the `BondDenom` parameter will make any bond transactions with `uatom` fail and will require the new `BondDenom` parameter string in order for bond transactions to be successful. Changing this parameter is likely to have breaking changes for applications that offer staking and delegation functionality.
Changing the `bond_denom` parameter will make any bond transactions with `uatom` fail and will require the new `bond_denom` parameter string in order for bond transactions to be successful. Changing this parameter is likely to have breaking changes for applications that offer staking and delegation functionality.

### `HistoricalEntries`
### `historical_entries`

**The number of HistoricalEntries to keep.**
**The number of historical_entries to keep.**

- on-chain value: <Var children={currentParams.staking.HistoricalEntries} />
- on-chain value: <Var children={currentParams.staking.historical_entries} />
- `cosmoshub-4` default: `10000`
- Did not exist in `cosmoshub-3` genesis

Expand Down
41 changes: 5 additions & 36 deletions docs/docs/governance/proposal-types/params-change/param-index.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: Index of Governable Parameters
title: Legacy subspace parameters
order: 2
---

import { KeyValueTable } from '@site/src/js/KeyValueTable';
import { Var } from '@site/src/js/Var';
import { currentParams } from '@site/docs/governance/current-parameters.js';
import { KeyValueTable } from "@site/src/js/KeyValueTable";
import { Var } from "@site/src/js/Var";
import { currentParams } from "@site/docs/governance/current-parameters.js";

## Querying on-chain parameters
## Querying legacy on-chain parameters

Given a subspace and an associated key, you can query on chain parameters using the CLI.

Expand All @@ -16,34 +16,3 @@ gaiad query params subspace <subspace_name> <key> --node <node_address> --chain-
```

For more information on specific modules, refer to the [Cosmos SDK documentation on modules](https://docs.cosmos.network/main/modules).

## Current subspaces, keys, and values

{/* <div
children={Object.entries(currentParams).map(
([subspaceName, subspaceData]) => (
<section
className="space-y-6"
id={subspaceName}
key={subspaceName}
>
<h2>
<Var children={subspaceName} /> subspace
</h2>
<KeyValueTable
data={subspaceData}
renderKey={(key) => (
<a href={`${subspaceName}.html#${key.toLowerCase()}`}>
<code>{key}</code>
</a>
)}
/>
<p>
Read more about the governance implications of the{' '}
<a href={`${subspaceName}.html`}>{subspaceName} subspace here.</a>
</p>
</section>
)
)}
className="flex flex-col gap-8"
/> */}

0 comments on commit 8110bd6

Please sign in to comment.