diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 8c271fb2e8..f16d8aa7a8 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -45,6 +45,7 @@ module.exports = { sidebarDepth: 0, children: [ ['/METHODS_RPC.md', 'Substrate RPC'], + ['/METHODS_CONSTANTS.md', 'Constants (defaults)'], ['/METHODS_STORAGE.md', 'State storage (defaults)'], ['/METHODS_EXTRINSICS.md', 'Extrinsics (defaults)'], ['/METHODS_EVENTS.md', 'System events (defaults)'] diff --git a/docs/METHODS_CONSTANTS.md b/docs/METHODS_CONSTANTS.md new file mode 100644 index 0000000000..71ce9bf73b --- /dev/null +++ b/docs/METHODS_CONSTANTS.md @@ -0,0 +1,178 @@ +## Constants + +_The following sections contain the module constants, also known as parameter types. +- **[balances](#balances)** + +- **[contracts](#contracts)** + +- **[democracy](#democracy)** + +- **[elections](#elections)** + +- **[finalityTracker](#finalityTracker)** + +- **[staking](#staking)** + +- **[treasury](#treasury)** + + +___ + + +### balances + +▸ **creationFee**: `Balance` +- **summary**: The fee required to create an account. + +▸ **existentialDeposit**: `Balance` +- **summary**: The minimum amount required to keep an account open. + +▸ **transactionBaseFee**: `Balance` +- **summary**: The fee to be paid for making a transaction; the base. + +▸ **transactionByteFee**: `Balance` +- **summary**: The fee to be paid for making a transaction; the per-byte portion. + +▸ **transferFee**: `Balance` +- **summary**: The fee required to make a transfer. + +___ + + +### contracts + +▸ **blockGasLimit**: `Gas` +- **summary**: The maximum amount of gas that could be expended per block. A reasonable default value is 10_000_000. + +▸ **callBaseFee**: `Gas` +- **summary**: The base fee charged for calling into a contract. A reasonable default value is 135. + +▸ **contractFee**: `BalanceOf` +- **summary**: The fee required to create a contract instance. A reasonable default value is 21. + +▸ **createBaseFee**: `Gas` +- **summary**: The base fee charged for creating a contract. A reasonable default value is 175. + +▸ **creationFee**: `BalanceOf` +- **summary**: The fee required to create an account. + +▸ **maxDepth**: `u32` +- **summary**: The maximum nesting level of a call/create stack. A reasonable default value is 100. + +▸ **rentByteFee**: `BalanceOf` +- **summary**: Price of a byte of storage per one block interval. Should be greater than 0. + +▸ **rentDepositOffset**: `BalanceOf` +- **summary**: The amount of funds a contract should deposit in order to offset the cost of one byte. Let's suppose the deposit is 1,000 BU (balance units)/byte and the rent is 1 BU/byte/day, then a contract with 1,000,000 BU that uses 1,000 bytes of storage would pay no rent. But if the balance reduced to 500,000 BU and the storage stayed the same at 1,000, then it would pay 500 BU/day. + +▸ **signedClaimHandicap**: `BlockNumber` +- **summary**: Number of block delay an extrinsic claim surcharge has. When claim surcharge is called by an extrinsic the rent is checked for current_block - delay + +▸ **storageSizeOffset**: `u32` +- **summary**: Size of a contract at the time of creation. This is a simple way to ensure that empty contracts eventually gets deleted. + +▸ **surchargeReward**: `BalanceOf` +- **summary**: Reward that is received by the party whose touch has led to removal of a contract. + +▸ **tombstoneDeposit**: `BalanceOf` +- **summary**: The minimum amount required to generate a tombstone. + +▸ **transactionBaseFee**: `BalanceOf` +- **summary**: The fee to be paid for making a transaction; the base. + +▸ **transactionByteFee**: `BalanceOf` +- **summary**: The fee to be paid for making a transaction; the per-byte portion. + +▸ **transferFee**: `BalanceOf` +- **summary**: The fee required to make a transfer. + +___ + + +### democracy + +▸ **cooloffPeriod**: `BlockNumber` +- **summary**: Period in blocks where an external proposal may not be re-submitted after being vetoed. + +▸ **emergencyVotingPeriod**: `BlockNumber` +- **summary**: Minimum voting period allowed for an emergency referendum. + +▸ **enactmentPeriod**: `BlockNumber` +- **summary**: The minimum period of locking and the period between a proposal being approved and enacted. It should generally be a little more than the unstake period to ensure that voting stakers have an opportunity to remove themselves from the system in the case where they are on the losing side of a vote. + +▸ **launchPeriod**: `BlockNumber` +- **summary**: How often (in blocks) new public referenda are launched. + +▸ **minimumDeposit**: `BalanceOf` +- **summary**: The minimum amount to be used as a deposit for a public referendum proposal. + +▸ **votingPeriod**: `BlockNumber` +- **summary**: How often (in blocks) to check for new votes. + +___ + + +### elections + +▸ **candidacyBond**: `BalanceOf` +- **summary**: How much should be locked up in order to submit one's candidacy. A reasonable default value is 9. + +▸ **carryCount**: `u32` +- **summary**: How many runners-up should have their approvals persist until the next vote. A reasonable default value is 2. + +▸ **decayRatio**: `u32` +- **summary**: Decay factor of weight when being accumulated. It should typically be set to __at least__ `membership_size -1` to keep the collective secure. When set to `N`, it indicates `(1/N)^t` of staked is decayed at weight increment step `t`. 0 will result in no weight being added at all (normal approval voting). A reasonable default value is 24. + +▸ **inactiveGracePeriod**: `VoteIndex` +- **summary**: How many vote indices need to go by after a target voter's last vote before they can be reaped if their approvals are moot. A reasonable default value is 1. + +▸ **presentSlashPerVoter**: `BalanceOf` +- **summary**: The punishment, per voter, if you provide an invalid presentation. A reasonable default value is 1. + +▸ **votingBond**: `BalanceOf` +- **summary**: How much should be locked up in order to be able to submit votes. + +▸ **votingFee**: `BalanceOf` +- **summary**: The amount of fee paid upon each vote submission, unless if they submit a _hole_ index and replace it. + +▸ **votingPeriod**: `BlockNumber` +- **summary**: How often (in blocks) to check for new votes. A reasonable default value is 1000. + +___ + + +### finality_tracker + +▸ **reportLatency**: `BlockNumber` +- **summary**: The delay after which point things become suspicious. Default is 1000. + +▸ **windowSize**: `BlockNumber` +- **summary**: The number of recent samples to keep from this chain. Default is 101. + +___ + + +### staking + +▸ **bondingDuration**: `EraIndex` +- **summary**: Number of eras that staked funds must remain bonded for. + +▸ **sessionsPerEra**: `SessionIndex` +- **summary**: Number of sessions per era. + +___ + + +### treasury + +▸ **burn**: `Permill` +- **summary**: Percentage of spare funds (if any) that are burnt per spend period. + +▸ **proposalBond**: `Permill` +- **summary**: Fraction of a proposal's value that should be bonded in order to place the proposal. An accepted proposal gets these back. A rejected proposal does not. + +▸ **proposalBondMinimum**: `BalanceOf` +- **summary**: Minimum amount of funds that should be placed in a deposit for making a proposal. + +▸ **spendPeriod**: `BlockNumber` +- **summary**: Period between successive spends. diff --git a/docs/METHODS_EXTRINSICS.md b/docs/METHODS_EXTRINSICS.md index 83e8f59898..68f8aa1886 100644 --- a/docs/METHODS_EXTRINSICS.md +++ b/docs/METHODS_EXTRINSICS.md @@ -9,15 +9,15 @@ _The following sections contain Extrinsics methods are part of the default Subst - **[collective](#collective)** -- **[contract](#contract)** +- **[contracts](#contracts)** - **[democracy](#democracy)** -- **[council](#council)** +- **[elections](#elections)** -- **[](#)** +- **[finalityTracker](#finalityTracker)** -- **[grandpaFinality](#grandpaFinality)** +- **[grandpa](#grandpa)** - **[session](#session)** @@ -88,7 +88,7 @@ ___ ___ -### contract +### contracts ▸ **call**(dest: `Address`, value: `Compact`, gas_limit: `Compact`, data: `Bytes`) - **summary**: Makes a call to an account, optionally transferring some balance. * If the account is a smart-contract account, the associated code will be executed and any value will be transferred. * If the account is a regular account, any value will be transferred. * If no account exists and the call value is not less than `existential_deposit`, a regular account will be created and any value will be transferred. @@ -167,7 +167,7 @@ ___ ___ -### council +### elections ▸ **presentWinner**(candidate: `Address`, total: `Compact`, index: `Compact`) - **summary**: Claim that `signed` is one of the top Self::carry_count() + current_vote().1 candidates. Only works if the `block_number >= current_vote().0` and `< current_vote().0 + presentation_duration()` `signed` should have at least # - O(voters) compute. - One DB change. # @@ -202,7 +202,7 @@ ___ ___ -### +### finalityTracker ▸ **finalHint**(hint: `Compact`) - **summary**: Hint that the author of this block thinks the best finalized block is the given number. @@ -210,7 +210,7 @@ ___ ___ -### grandpaFinality +### grandpa ▸ **reportMisbehavior**(_report: `Bytes`) - **summary**: Report some misbehavior. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4135e17436..6ba8b631cc 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -11,6 +11,7 @@ ## Interfaces - [RPC](METHODS_RPC.md) +- [Constants (runtime)](METHODS_CONSTANTS.md) - [Chain state (runtime)](METHODS_STORAGE.md) - [Extrinsics (runtime)](METHODS_EXTRINSICS.md) - [Events (runtime)](METHODS_EVENTS.md) diff --git a/packages/api/README.md b/packages/api/README.md index d8c33d9a39..0718f9f481 100644 --- a/packages/api/README.md +++ b/packages/api/README.md @@ -12,6 +12,8 @@ The API wrappers provide a standard interface for use - - [Storage chain state (runtime node interface)](../METHODS_STORAGE.md) - `api.tx.
.` provides the ability to create a transaction, like chain state, this list is populated from a runtime query - [Extrinsics (runtime node interface)](../METHODS_EXTRINSICS.md) +- `api.consts.
.` provides access to the module constants (parameter types). + - [Constants (runtime node interface)](../METHODS_CONSTANTS.md) ## API Selection diff --git a/packages/types/src/scripts/MetadataMd.ts b/packages/types/src/scripts/MetadataMd.ts index ad72448e7e..8b2a1dfb91 100644 --- a/packages/types/src/scripts/MetadataMd.ts +++ b/packages/types/src/scripts/MetadataMd.ts @@ -14,6 +14,7 @@ import MetadataV6, { ModuleMetadataV6 } from '../Metadata/v6'; const ANCHOR_TOP = ''; const LINK_BACK_TO_TOP = ''; +const DESC_CONSTANTS = '\n\n_The following sections contain the module constants, also known as parameter types.\n'; const DESC_EXTRINSICS = '\n\n_The following sections contain Extrinsics methods are part of the default Substrate runtime._\n'; const DESC_EVENTS = '\n\nEvents are emitted for certain operations on the runtime. The following sections describe the events that are part of the default Substrate runtime.\n'; const DESC_RPC = '\n\n_The following sections contain RPC methods that are Remote Calls available by default and allow you to interact with the actual node, query, and submit. The RPCs are provided by Substrate itself._'; @@ -67,6 +68,36 @@ function sortByName (a: T, b: T): number { return nameA.localeCompare(nameB); } +function addConstants (metadata: MetadataV6): string { + const renderHeading = `## ${ANCHOR_TOP}Constants${DESC_CONSTANTS}`; + const orderedSections = metadata.modules.sort(sortByName); + let renderAnchors = ''; + const sections = orderedSections.reduce((md, moduleMetadata): string => { + if (moduleMetadata.constants.isEmpty) { + return md; + } + + const sectionName = stringLowerFirst(moduleMetadata.name.toString()); + + renderAnchors += sectionLink(sectionName); + + const renderSection = generateSectionHeader(md, sectionName); + const orderedConstants = moduleMetadata.constants.sort(sortByName); + + return orderedConstants.reduce((md, func): string => { + const methodName = stringLowerFirst(func.name.toString()); + const doc = func.documentation.reduce((md, doc): string => `${md} ${doc}`, ''); + const type = func.type; + const renderSignature = `${md}\n▸ **${methodName}**: ` + '`' + type + '`'; + const renderSummary = `${doc ? `\n- **summary**: ${doc}\n` : '\n'}`; + + return renderSignature + renderSummary; + }, renderSection); + }, ''); + + return renderHeading + renderAnchors + sections; +} + function addEvents (metadata: MetadataV6): string { const renderHeading = `## ${ANCHOR_TOP}Events${DESC_EVENTS}`; const orderedSections = metadata.modules.sort(sortByName); @@ -108,7 +139,7 @@ function addExtrinsics (metadata: MetadataV6): string { } const calls = meta.calls.unwrap(); - const sectionName = stringCamelCase(meta.prefix.toString()); + const sectionName = stringCamelCase(meta.name.toString()); renderAnchors += sectionLink(sectionName); @@ -181,6 +212,10 @@ function writeToRpcMd (): void { writeFile('docs/METHODS_RPC.md', addRpc()); } +function writeToConstantsMd (metadata: MetadataV6): void { + writeFile('docs/METHODS_CONSTANTS.md', addConstants(metadata)); +} + function writeToStorageMd (metadata: MetadataV6): void { const options = { flags: 'r', encoding: 'utf8' }; const data = fs.readFileSync('packages/types/src/scripts/METHODS_STORAGE_SUBSTRATE.md', options); @@ -199,6 +234,7 @@ function writeToEventsMd (metadata: MetadataV6): void { const metadata = new Metadata(rpcdata).asV6; writeToRpcMd(); +writeToConstantsMd(metadata); writeToStorageMd(metadata); writeToExtrinsicsMd(metadata); writeToEventsMd(metadata);