| title |
|---|
Appendix C: Runtime API |
Description of how to interact with the Runtime through its exported functions
The Polkadot Host assumes that at least the constants and functions described in this Chapter are implemented in the Runtime Wasm blob.
It should be noted that the API can change through the Runtime updates. Therefore, a host should check the API versions of each module returned in the api field by Core_version (Section -sec-num-ref-) after every Runtime upgrade and warn if an updated API is encountered and that this might require an update of the host.
This section describes all Runtime API functions alongside their arguments and the return values. The functions are organized into modules, with each being versioned independently.
Polkadot Host implementers are encouraged to implement an API in order for external, third-party services to interact with the node. The JSON-RPC Interface for Polkadot Nodes (PCP6) is a Polkadot Standard Proposal for such an API and makes it easier to integrate the node with existing tools available in the Polkadot ecosystem, such as polkadot.js.org. The Runtime API has a few modules designed specifically for use in the official RPC API.
This constant indicates the beginning of the heap in memory. The space below is reserved for the stack and the data section. For more details please refer to Section -sec-num-ref-.
:::definition
The Runtime API Call Convention describes that all functions receive and return SCALE-encoded data and, as a result, have the following prototype signature:
(func $generic_runtime_entry
(param $ptr i32) (parm $len i32) (result i64))
where ptr points to the SCALE encoded tuple of the parameters passed to the function and len is the length of this data, while result is a pointer-size (Definition Definition -def-num-ref-) to the SCALE-encoded return data.
:::
See Section -sec-num-ref- for more information about the behavior of the Wasm Runtime. Also, note that any storage changes must be fork-aware (Section -sec-num-ref-).
:::note
This section describes Version 3 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
:::note For newer Runtimes, the version identifiers can be read directly from the Wasm blob in the form of custom sections (Section -sec-num-ref-). That method of retrieving this data should be preferred since it involves significantly less overhead. :::
Returns the version identifiers of the Runtime. This function can be used by the Polkadot Host implementation when it seems appropriate, such as for the JSON-RPC API as described in Section -sec-num-ref-.
Arguments
- None
Return
-
A data structure of the following format:
Table -tab-num- Details of the version that the data type returns from the Runtime function. {#tabl-rt-core-version}
Name Type Description spec_nameString Runtime identifier impl_nameString Name of the implementation (e.g. C++) authoring_versionUnsigned 32-bit integer Version of the authorship interface spec_versionUnsigned 32-bit integer Version of the Runtime specification impl_versionUnsigned 32-bit integer Version of the Runtime implementation apisApiVersions (Definition -def-num-ref-) List of supported APIs along with their version transaction_versionUnsigned 32-bit integer Version of the transaction format state_versionUnsigned 8-bit integer Version of the trie format
:::definition
ApiVersions is a specialized type for the (Section -sec-num-ref-) function entry. It represents an array of tuples, where the first value of the tuple is an array of 8-bytes containing the Blake2b hash of the API name. The second value of the tuple is the version number of the corresponding API.
$$ \begin{aligned} \mathrm{ApiVersions} :=& (T_0, \ldots, T_n) \ T :=& ((b_0, \ldots, b_7), \mathrm{UINT32}) \end{aligned} $$ :::
Requires Core_initialize_block to be called beforehand.
This function executes a full block and all its extrinsics and updates the state accordingly. Additionally, some integrity checks are executed, such as validating if the parent hash is correct and that the transaction root represents the transactions. Internally, this function performs an operation similar to the process described in Build-Block, by calling Core_initialize_block,BlockBuilder_apply_extrinsics and BlockBuilder_finalize_block.
This function should be called when a fully complete block is available that is not actively being built on, such as blocks received from other peers. State changes resulting from calling this function are usually meant to persist when the block is imported successfully.
Additionally, the seal digest in the block header, as described in Definition -def-num-ref-, must be removed by the Polkadot host before submitting the block.
Arguments
- A block represented as a tuple consisting of a block header, as described in Definition -def-num-ref-, and the block body, as described in Definition -def-num-ref-.
Return
- None.
Sets up the environment required for building a new block as described in Build-Block.
Arguments
- The header of the new block as defined in Definition -def-num-ref-. The values ${H}{{r}}$, ${H}{{e}}$ and
${H}_{{d}}$ are left empty.
Return
- None.
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
Returns native Runtime metadata in an opaque form. This function can be used by the Polkadot Host implementation when it seems appropriate, such as for the JSON-RPC API as described in Section -sec-num-ref-, and returns all the information necessary to build valid transactions.
Arguments
- None.
Return
- The scale-encoded (Section -sec-num-ref-) runtime metadata as described in Chapter -chap-num-ref-.
Returns native Runtime metadata in an opaque form at a particular version.
Arguments
- Metadata version represented by an unsigned 32-bit integer.
Return
- The scale-encoded (Section -sec-num-ref-) runtime metadata as described in Chapter -chap-num-ref- at the particular version.
Returns supported metadata versions.
Arguments
- None.
Return
- A vector of supported metadata versions of type
vec<u32>.
:::note
This section describes Version 4 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
Apply the extrinsic outside of the block execution function. This does not attempt to validate anything regarding the block, but it builds a list of transaction hashes.
Arguments
- A byte array of varying sizes containing the opaque extrinsic.
Return
- Returns the varying datatype ApplyExtrinsicResult as defined in Definition -def-num-ref-. This structure lets the block builder know whether an extrinsic should be included in the block or rejected.
:::definition
ApplyExtrinsicResult is a varying data type as defined in Definition -def-num-ref-. This structure can contain multiple nested structures, indicating either module dispatch outcomes or transaction invalidity errors.
Table -tab-num- Possible values of varying data type ApplyExtrinsicResult. {#tabl-rte-apply-extrinsic-result}
| Id | Description | Type |
|---|---|---|
| 0 | Outcome of dispatching the extrinsic. | DispatchOutcome (Definition -def-num-ref-) |
| 1 | Possible errors while checking the validity of a transaction. | TransactionValidityError (Definition -def-num-ref-) |
:::
:::info As long as a DispatchOutcome (Definition -def-num-ref-) is returned, the extrinsic is always included in the block, even if the outcome is a dispatch error. Dispatch errors do not invalidate the block and all state changes are persisted. :::
:::definition
DispatchOutcome is the varying data type as defined in Definition -def-num-ref-.
| Id | Description | Type |
|---|---|---|
| 0 | Extrinsic is valid and was submitted successfully. | None |
| 1 | Possible errors while dispatching the extrinsic. | DispatchError (Definition -def-num-ref-) |
| ::: |
:::definition
DispatchError is a varying data type as defined in Definition -def-num-ref-. Indicates various reasons why a dispatch call failed.
| Id | Description | Type |
|---|---|---|
| 0 | Some unknown error occurred. | SCALE encoded byte array containing a valid UTF-8 sequence. |
| 1 | Failed to look up some data. | None |
| 2 | A bad origin. | None |
| 3 | A custom error in a module. | CustomModuleError (Definition -def-num-ref-) |
| ::: |
:::definition
CustomModuleError is a tuple appended after a possible error in as defined in Definition -def-num-ref-.
Table -tab-num- Possible values of varying data type CustomModuleError. {#tabl-rte-custom-module-error}
| Name | Description | Type |
|---|---|---|
| Index | Module index matching the metadata module index. | Unsigned 8-bit integer. |
| Error | Module-specific error value. | Unsigned 8-bit integer |
| Message | Optional error message. | Varying data type Option (Definition -def-num-ref-). The optional value is a SCALE-encoded byte array containing a valid UTF-8 sequence. |
| ::: |
:::info Whenever TransactionValidityError (Definition -def-num-ref-) is returned, the contained error type will indicate whether an extrinsic should be outright rejected or requested for a later block. This behavior is clarified further in Definition -def-num-ref- and respectively Definition -def-num-ref-. :::
:::definition
TransactionValidityError is a varying data type as defined in Definition -def-num-ref-. It indicates possible errors that can occur while checking the validity of a transaction.
Table -tab-num- Possible values of varying data type TransactionValidityError. {#tabl-rte-transaction-validity-error}
| Id | Description | Type |
|---|---|---|
| 0 | Transaction is invalid. | InvalidTransaction (Definition -def-num-ref-) |
| 1 | Transaction validity can’t be determined. | UnknownTransaction (Definition -def-num-ref-) |
| ::: |
:::definition
InvalidTransaction is a varying data type as defined in Definition -def-num-ref- and specifies the invalidity of the transaction in more detail.
Table -tab-num- Possible values of varying data type InvalidTransaction. {#tabl-rte-invalid-transaction}
| Id | Description | Type | Reject |
|---|---|---|---|
| 0 | Call of the transaction is not expected. | None | Yes |
| 1 | General error to do with the inability to pay some fees (e.g., account balance too low). | None | Yes |
| 2 | General error to do with the transaction not yet being valid (e.g., nonce too high). | None | No |
| 3 | General error to do with the transaction being outdated (e.g., nonce too low). | None | Yes |
| 4 | General error to do with the transactions’ proof (e.g., signature) | None | Yes |
| 5 | The transaction birth block is ancient. | None | Yes |
| 6 | The transaction would exhaust the resources of the current block. | None | No |
| 7 | Some unknown error occurred. | Unsigned 8-bit integer | Yes |
| 8 | An extrinsic with mandatory dispatch resulted in an error. | None | Yes |
| 9 | A transaction with a mandatory dispatch (only inherents are allowed to have mandatory dispatch). | None | Yes |
| ::: |
:::definition
UnknownTransaction is a varying data type as defined in Definition -def-num-ref- and specifies the unknown invalidity of the transaction in more detail.
Table -tab-num- Possible values of varying data type UnknownTransaction. {#tabl-rte-unknown-transaction}
| Id | Description | Type | Reject |
|---|---|---|---|
| 0 | Could not look up some information that is required to validate the transaction. | None | Yes |
| 1 | No validator found for the given unsigned transaction. | None | Yes |
| 2 | Any other custom unknown validity that is not covered by this type. | Unsigned 8-bit integer | Yes |
| ::: |
Finalize the block - it is up to the caller to ensure that all header fields are valid except for the state root. State changes resulting from calling this function are usually meant to persist upon successful execution of the function and appending of the block to the chain.
Arguments
- None.
Return
- The header of the new block as defined in Definition -def-num-ref-.
Generates the inherent extrinsics, which are explained in more detail in Section -sec-num-ref-. This function takes a SCALE-encoded hash table as defined in Definition -def-num-ref- and returns an array of extrinsics. The Polkadot Host must submit each of those to the BlockBuilder_apply_extrinsic, described in Section -sec-num-ref-. This procedure is outlined in Build-Block.
Arguments
- A Inherents-Data structure as defined in Definition -def-num-ref-.
Return
- A byte array of varying sizes containing extrinisics. Each extrinsic is a byte array of varying size.
Checks whether the provided inherent is valid. This function can be used by the Polkadot Host when deemed appropriate, e.g., during the block-building process.
Arguments
-
A block represented as a tuple consisting of a block header as described in Definition -def-num-ref- and the block body as described in Definition -def-num-ref-.
-
A Inherents-Data structure as defined in Definition -def-num-ref-.
Return
-
A data structure of the following format:
$$ {\left({o},{{f}_{{e}},}{e}\right)} $$
where
-
${o}$ is a boolean indicating whether the check was successful. -
${f_e}$ is a boolean indicating whether a fatal error was encountered. -
${e}$ is a Inherents-Data structure as defined in Definition -def-num-ref- containing any errors created by this Runtime function.
-
:::note
This section describes Version 2 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
This entry is invoked against extrinsics submitted through a transaction network message (Section -sec-num-ref-) or by an off-chain worker through the Host API (Section -sec-num-ref-).
It indicates if the submitted blob represents a valid extrinsics, the order in which it should be applied and if it should be gossiped to other peers. Furthermore, this function gets called internally when executing blocks with the runtime function as described in Section -sec-num-ref-.
Arguments
-
The source of the transaction as defined in Definition -def-num-ref-.
-
A byte array that contains the transaction.
-
The hash of the parent of the block that the transaction is included in.
:::definition TransactionSource is an enum describing the source of a transaction and can have one of the following values:
| Id | Name | Description |
|---|---|---|
| 0 | InBlock | Transaction is already included in a block. |
| 1 | Local | Transaction is coming from a local source, e.g. off-chain worker. |
| 2 | External | Transaction has been received externally, e.g. over the network. |
| ::: |
Return
-
This function returns a Result as defined in Definition -def-num-ref- which contains the type ValidTransaction as defined in Definition -def-num-ref- on success and the type TransactionValidityError as defined in Definition -def-num-ref- on failure.
:::definition ValidTransaction is a tuple that contains information concerning a valid transaction.
Table -tab-num- The tuple provided by in the case the transaction is judged to be valid. {#tabl-rte-valid-transaction}
| Name | Description | Type |
|---|---|---|
| Priority | Determines the ordering of two transactions that have all their dependencies (required tags) are satisfied. | Unsigned 64-bit integer |
| Requires | List of tags specifying extrinsics which should be applied before the current extrinsics can be applied. | Array containing inner arrays |
| Provides | Informs Runtime of the extrinsics depending on the tags in the list that can be applied after current extrinsics are being applied. Describes the minimum number of blocks for the validity to be correct. | Array containing inner arrays |
| Longevity | After this period, the transaction should be removed from the pool or revalidated. | Unsigned 64-bit integer |
| Propagate | A flag indicating if the transaction should be gossiped to other peers. | Boolean |
:::
:::info
If Propagate is set to false the transaction will still be considered for inclusion in blocks that are authored on the current node, but should not be gossiped to other peers.
:::
:::info If this function gets called by the Polkadot Host in order to validate a transaction received from peers, the Polkadot Host disregards and rewinds state changes resulting in such a call. :::
:::note
This section describes Version 2 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
Does not require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
Starts an off-chain worker and generates extrinsics. [To do: when is this called?]
Arguments
- The block header as defined in Definition -def-num-ref-.
Return
- None.
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
Returns the validator set at the current state. The specified validators are responsible for backing parachains for the current state.
Arguments
- None.
Return
- An array of public keys representing the validators.
Returns the validator groups (Definition -def-num-ref-) used during the current session. The validators in the groups are referred to by the validator set Id (Definition -def-num-ref-).
Arguments
- None
Return
-
An array of tuples,
${T}$ , of the following format:$$ {T}={\left({I},{G}\right)} $$ $$ {I}={\left({v}{{n}},…{v}{{m}}\right)} $$ $$ {G}={\left({B}{{s}},{f},{B}{{c}}\right)} $$
where
-
${I}$ is an array of the validator set Ids (Definition -def-num-ref-). -
${B}_{{s}}$ indicates the block number where the session started. -
${f}$ indicates how often groups rotate. 0 means never. -
${B}_{{c}}$ indicates the current block number.
-
Returns information on all availability cores (Definition -def-num-ref-).
Arguments
- None
Return
-
An array of core states, S, of the following format:
$$ {S}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}{{o}}\{1}&\rightarrow&{C}{{s}}\{2}&\rightarrow&\phi\end{matrix}\right.} $$ $$ {C}{{o}}={\left({n}{{u}},{B}{{o}},{B}{{t}},{n}{{t}},{b},{G}{{i}},{C}{{h}},{C}{{d}}\right)} $$ $$ {C}{{s}}={\left({P}{{i}}{d},{C}_{{i}}\right)} $$
where
-
${S}$ specifies the core state. 0 indicates that the core is occupied, 1 implies it’s currently free but scheduled and given the opportunity to occupy and 2 implies it’s free and there’s nothing scheduled. -
${n}{{u}}$ is an Option value (Definition -def-num-ref-) which can contain a ${C}{{s}}$ value if the core was freed by the Runtime and indicates the assignment that is next scheduled on this core. An empty value indicates there is nothing scheduled.
-
${B}_{{o}}$ indicates the relay chain block number at which the core got occupied. -
${B}_{{t}}$ indicates the relay chain block number the core will time-out at, if any. -
${n}{{t}}$ is an Option value (Definition -def-num-ref-) which can contain a ${C}{{s}}$ value if the core is freed by a time-out and indicates the assignment that is next scheduled on this core. An empty value indicates there is nothing scheduled.
-
${b}$ is a bitfield array (Definition -def-num-ref-). A$>\frac{{2}}{{3}}$ majority of assigned validators voting with${1}$ values means that the core is available. -
${G}_{{i}}$ indicates the assigned validator group index (Definition -def-num-ref-) is to distribute availability pieces of this candidate. -
${C}_{{h}}$ indicates the hash of the candidate occupying the core. -
${C}_{{d}}$ is the candidate descriptor (Definition -def-num-ref-). -
${C}_{{i}}$ is an Option value (Definition -def-num-ref-) which can contain the collators public key indicating who should author the block.
-
Returns the persisted validation data for the given parachain Id and a given occupied core assumption.
Arguments
-
The parachain Id (Definition -def-num-ref-).
-
An occupied core assumption (Definition -def-num-ref-).
Return
- An Option value (Definition -def-num-ref-) which can contain the persisted validation data (Definition -def-num-ref-). The value is empty if the parachain Id is not registered or the core assumption is of index
${2}$ , meaning that the core was freed.
:::definition
An occupied core assumption is used for fetching certain pieces of information about a parachain by using the relay chain API. The assumption indicates how the Runtime API should compute the result. The assumptions, A, is a varying datatype of the following format:
where 0 indicates that the candidate occupying the core was made available and included to free the core, 1 indicates that it timed-out and freed the core without advancing the parachain and 2 indicates that the core was not occupied to begin with.
:::
:::definition
The persisted validation data provides information about how to create the inputs for the validation of a candidate by calling the Runtime. This information is derived from the parachain state and will vary from parachain to parachain, although some of the fields may be the same for every parachain. This validation data acts as a way to authorize the additional data (such as messages) the collator needs to pass to the validation function.
The persisted validation data,
$$ {D}{{{p}{v}}}={\left({P}{{h}},{H}{{i}},{H}{{r}},{m}_{{b}}\right)} $$
where
-
${P}_{{h}}$ is the parent head data (Definition -def-num-ref-). -
${H}_{{i}}$ is the relay chain block number this is in the context of. -
${H}_{{r}}$ is the relay chain storage root this is in the context of. -
${m}_{{b}}$ is the maximum legal size of the PoV block, in bytes.
The persisted validation data is fetched via the Runtime API (Section -sec-num-ref-).
:::
Returns the persisted validation data for the given parachain Id along with the corresponding Validation Code Hash. Instead of accepting validation about para, matches the validation data hash against an expected one and yields None if they are unequal.
Arguments
- The Parachain Id (Definition -def-num-ref-).
- Expected Persistent Validation Data Hash (Definition -def-num-ref-).
Return
- An Option value (Definition -def-num-ref-) which can contain the pair of persisted validation data (Definition -def-num-ref-) and Validation Code Hash. The value is
Noneif the parachain Id is not registered or the validation data hash does not match the expected one.
Checks if the given validation outputs pass the acceptance criteria.
Arguments
-
The parachain Id (Definition -def-num-ref-).
-
The candidate commitments (Definition -def-num-ref-).
Return
- A boolean indicating whether the candidate commitments pass the acceptance criteria.
Returns the session index that is expected at the child of a block.
:::caution TODO clarify session index :::
Arguments
- None
Return
- A unsigned 32-bit integer representing the session index.
Fetches the validation code (Runtime) of a parachain by parachain Id.
Arguments
-
The parachain Id (Definition -def-num-ref-).
-
The occupied core assumption (Definition -def-num-ref-).
Return
- An Option value (Definition -def-num-ref-) containing the full validation code in a byte array. This value is empty if the parachain Id cannot be found or the assumption is wrong.
Returns the validation code (Runtime) of a parachain by its hash.
Arguments
- The hash value of the validation code.
Return
- An Option value (Definition -def-num-ref-) containing the full validation code in a byte array. This value is empty if the parachain Id cannot be found or the assumption is wrong.
Returns the validation code hash of a parachain.
Arguments
- The parachain Id (Definition -def-num-ref-).
- An occupied core assumption (Definition -def-num-ref-).
Return
- An Option value (Definition -def-num-ref-) containing the hash value of the validation code. This value is empty if the parachain Id cannot be found or the assumption is wrong.
-sec-num- ParachainHost_candidate_pending_availability {#id-parachainhost_candidate_pending_availability}
Returns the receipt of a candidate pending availability for any parachain assigned to an occupied availability core.
Arguments
- The parachain Id (Definition -def-num-ref-).
Return
- An Option value (Definition -def-num-ref-) containing the committed candidate receipt (Definition -def-num-ref-). This value is empty if the given parachain Id is not assigned to an occupied availability core.
Returns an array of candidate events that occurred within the latest state.
Arguments
- None
Return
-
An array of single candidate events, E, of the following format:
$$ {E}={\left\lbrace\begin{matrix}{0}&\rightarrow&{d}\{1}&\rightarrow&{d}\{2}&\rightarrow&{\left({C}{{r}},{h},{I}{{c}}\right)}\end{matrix}\right.} $$ $$ {d}={\left({C}{{r}},{h},{I}{{c}},{G}_{{i}}\right)} $$
where
-
${E}$ specifies the event type of the candidate. 0 indicates that the candidate receipt was backed in the latest relay chain block, 1 indicates that it was included and became a parachain block at the latest relay chain block and 2 indicates that the candidate receipt was not made available and timed out. -
${C}_{{r}}$ is the candidate receipt (Definition -def-num-ref-). -
${h}$ is the parachain head data (Definition -def-num-ref-). -
${I}_{{c}}$ is the index of the availability core as can be retrieved in Section -sec-num-ref- that the candidate is occupying. If${E}$ is of variant${2}$ , then this indicates the core index the candidate was occupying. -
${G}_{{i}}$ is the group index (Definition -def-num-ref-) that is responsible of backing the candidate.
-
Get the session info of the given session, if available.
Arguments
- The unsigned 32-bit integer indicating the session index.
Return
-
An Option type (Definition -def-num-ref-) which can contain the session info structure,
${S}$ , of the following format:$$ {S}={\left({A},{D},{K},{G},{c},{z},{s},{d},{x},{a}\right)} $$ $$ {A}={\left({v}{{n}},…{v}{{m}}\right)} $$ $$ {D}={\left({v}{{{n}}},…{v}{{m}}\right)} $$ $$ {K}={\left({v}{{n}},…{v}{{m}}\right)} $$ $$ {G}={\left({{g}{{n}},}…{g}{{m}}\right)} $$ $$ {g}={\left({A}{{n}},…{A}_{{m}}\right)} $$
where
-
${A}$ indicates the validators of the current session in canonical order. There might be more validators in the current session than validators participating in parachain consensus, as returned by the Runtime API (Section -sec-num-ref-). -
${D}$ indicates the validator authority discovery keys for the given session in canonical order. The first couple of validators are equal to the corresponding validators participating in the parachain consensus, as returned by the Runtime API (Section -sec-num-ref-). The remaining authorities are not participating in the parachain consensus. -
${K}$ indicates the assignment keys for validators. There might be more authorities in the session that validators participating in parachain consensus, as returned by the Runtime API (Section -sec-num-ref-). -
${G}$ indicates the validator groups in shuffled order. -
${v}_{{n}}$ is public key of the authority. -
${A}_{{n}}$ is the authority set Id (Definition -def-num-ref-). -
${c}$ is an unsigned 32-bit integer indicating the number of availability cores used by the protocol during the given session. -
${z}$ is an unsigned 32-bit integer indicating the zeroth delay tranche width. -
${s}$ is an unsigned 32-bit integer indicating the number of samples an assigned validator should do for approval voting. -
${d}$ is an unsigned 32-bit integer indicating the number of delay tranches in total. -
${x}$ is an unsigned 32-bit integer indicating how many BABE slots must pass before an assignment is considered a “no-show”. -
${a}$ is an unsigned 32-bit integer indicating the number of validators needed to approve a block.
-
Returns all the pending inbound messages in the downward message queue for a given parachain.
Arguments
- The parachain Id (Definition -def-num-ref-).
Return
- An array of inbound downward messages (Definition -def-num-ref-).
-sec-num- ParachainHost_inbound_hrmp_channels_contents {#id-parachainhost_inbound_hrmp_channels_contents}
Returns the contents of all channels addressed to the given recipient. Channels that have no messages in them are also included.
Arguments
- The parachain Id (Definition -def-num-ref-).
Return
- An array of inbound HRMP messages (Definition -def-num-ref-).
Returns disputes relevant from on-chain, backing votes, and resolved disputes.
Arguments
- None
Return
- An Option (Definition -def-num-ref-) type which can contain the scraped on-chain votes data (Definition -def-num-ref-).
:::definition Contains the scraped runtime backing votes and resolved disputes.
The scraped on-chain votes data,
where:
-
$S_i$ is the u32 integer representing the session index in which the block was introduced. -
$BV$ is the set of backing validators for each candidate, represented by its candidate receipt (Definition -def-num-ref-). Each candidate$C_r$ has a list of$(i,a)$ , the pair of validator index and validation attestations (Definition -def-num-ref-). -
$d$ is a set of dispute statements (Section -sec-num-ref-). Note that the above$BV$ is unrelated to the backers of the dispute candidates. :::
:::caution PVF Pre-Checker subsystem is still Work-in-Progress, hence the below APIs are subject to change. :::
This runtime API fetches all PVFs that require pre-checking voting. The PVFs are identified by their code hashes. As soon as the PVF gains the required support, the runtime API will not return the PVF anymore.
Arguments
- None
Return
- A list of validation code hashes that require prechecking of votes by validators in the active set.
This runtime API submits the judgment for a PVF, whether it is approved or not. The voting process uses unsigned transactions. The check is circulated through the network via gossip, similar to a normal transaction. At some point, the validator will include the statement in the block, where it will be processed by the runtime. If that was the last vote before gaining the super-majority, this PVF would not be returned by pvfs_require_precheck (Section -sec-num-ref-) anymore.
Arguments
- A PVF pre checking statement (Definition -def-num-ref-) to be submitted into the transaction pool.
- Validator Signature (Definition -def-num-ref-).
Return
- None
:::definition
This is a statement by the validator who ran the pre-checking process for a PVF. A PVF is identified by the ValidationCodeHash. The statement is valid only during a single session, specified in the session_index.
The PVF Check Statement
where:
-
$b$ is a boolean denoting if the subject passed pre-checking. -
$VC_H$ is the validation code hash. -
$S_i$ is a u32 integer representing the session index. -
$V_i$ is the validator index (Definition -def-num-ref-). :::
This runtime API fetches all on-chain disputes.
Arguments
- None
Return
- A list of (SessionIndex, CandidateHash, DisputeState).
:::caution TODO clarify DisputeState :::
This runtime API returns execution parameters for the session.
Arguments
- Session Index
:::caution TODO clarify session index :::
Return
- Option type of Executor Parameters.
:::caution TODO clarify Executor Parameters :::
:::note
This section describes Version 2 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
This entry fetches the list of GRANDPA authorities according to the genesis block and is used to initialize an authority list at genesis, defined in Definition -def-num-ref-. Any future authority changes get tracked via Runtime-to-consensus engine messages, as described in Section -sec-num-ref-.
Arguments
- None.
Return
- An authority list as defined in Definition -def-num-ref-.
This entry fetches the list of GRANDPA authority set IDs (Definition -def-num-ref-). Any future authority changes get tracked via Runtime-to-consensus engine messages, as described in Section -sec-num-ref-.
Arguments
- None.
Return
- An authority set ID as defined in Definition -def-num-ref-.
-sec-num- GrandpaApi_submit_report_equivocation_unsigned_extrinsic {#sect-grandpaapi_submit_report_equivocation_unsigned_extrinsic}
A GRANDPA equivocation occurs when a validator votes for multiple blocks during one voting subround, as described further in Definition -def-num-ref-. The Polkadot Host is expected to identify equivocators and report those to the Runtime by calling this function.
Arguments
-
The equivocation proof of the following format:
$$ \begin{aligned} G_{\mathrm{Ep}} =& (\mathrm{id}{\mathbb{V}}, e, r, A{\mathrm{id}}, B^1_h, B^1_n, A^1_{\mathrm{sig}}, B^2_h, B^2_n, A^2_{\mathrm{sig}}) \ e =& \begin{cases} 0 & \quad \textrm{Equivocation at prevote stage} \ 1 & \quad \textrm{Equivocation at precommit stage} \end{cases} \end{aligned} $$
where
-
${m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}_{{{\mathbb{{{V}}}}}}$ is the authority set id as defined in Definition -def-num-ref-. -
${e}$ indicates the stage at which the equivocation occurred. -
${r}$ is the round number the equivocation occurred. -
${A}_{{{m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}}}$ is the public key of the equivocator. -
${B}^{{1}}_{h}$ is the block hash of the first block the equivocator voted for. -
${B}^{{1}}_{n}$ is the block number of the first block the equivocator voted for. -
${A}^{{1}}_{\left\lbrace{m}{a}{t}{h}{r}{m}{\left\lbrace{s}{i}{g}\right\rbrace}\right\rbrace}$ is the equivocators signature of the first vote. -
${B}^{{2}}_{h}$ is the block hash of the second block the equivocator voted for. -
${B}^{{2}}_{n}$ is the block number of the second block the equivocator voted for. -
${A}^{{2}}_{\left\lbrace{m}{a}{t}{h}{r}{m}{\left\lbrace{s}{i}{g}\right\rbrace}\right\rbrace}$ is the equivocators signature of the second vote. -
A proof of the key owner in an opaque form as described in Section -sec-num-ref-.
-
Return
- A SCALE encoded Option as defined in Definition -def-num-ref- containing an empty value on success.
Generates proof of the membership of a key owner in the specified block state. The returned value is used to report equivocations as described in Section -sec-num-ref-.
Arguments
-
The authority set id as defined in Definition -def-num-ref-.
-
The 256-bit public key of the authority.
Return
- A SCALE encoded Option as defined in Definition -def-num-ref- containing the proof in an opaque form.
:::note
This section describes Version 2 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialized_block (Section -sec-num-ref-) to be called beforehand.
This entry is called to obtain the current configuration of the BABE consensus protocol.
Arguments
- None.
Return
-
A tuple containing configuration data used by the Babe consensus engine.
Table -tab-num- The tuple provided by BabeApi_configuration. {#tabl-babeapi-configuration}
Name Description Type SlotDuration The slot duration in milliseconds. Currently, only the value provided by this type at genesis will be used. Dynamic slot duration may be supported in the future. Unsigned 64bit integer EpochLength The duration of epochs in slots. Unsigned 64bit integer Constant A constant value that is used in the threshold calculation formula as defined in Definition -def-num-ref-. Tuple containing two unsigned 64bit integers GenesisAuthorities The authority list for the genesis epoch as defined in Definition -def-num-ref-. Array of tuples containing a 256-bit byte array and an unsigned 64bit integer Randomness The randomness for the genesis epoch 32-byte array SecondarySlot Whether this chain should run with a round-robin-style secondary slot and if this secondary slot requires the inclusion of an auxiliary VRF output (Section -sec-num-ref-). A one-byte enum as defined in Definition -def-num-ref- as ${2}_{{\text{nd}}}$ .
Finds the start slot of the current epoch.
Arguments
- None.
Return
- A unsigned 64-bit integer indicating the slot number.
Produces information about the current epoch.
Arguments
- None.
Return
-
A data structure of the following format:
$$ {\left({e}{{i}},{s}{{s}},{d},{A},{r}\right)} $$
where
-
${e}_{{i}}$ is a unsigned 64-bit integer representing the epoch index. -
${s}_{{s}}$ is an unsigned 64-bit integer representing the starting slot of the epoch. -
${d}$ is an unsigned 64-bit integer representing the duration of the epoch. -
${A}$ is an authority list as defined in Definition -def-num-ref-. -
${r}$ is a 256-bit array containing the randomness for the epoch as defined in Definition -def-num-ref-.
-
Produces information about the next epoch.
Arguments
- None.
Return
- Returns the same data structure as described in Section -sec-num-ref-.
Generates proof of the membership of a key owner in the specified block state. The returned value is used to report equivocations as described in Section -sec-num-ref-.
Arguments
-
The unsigned 64-bit integer indicating the slot number.
-
The 256-bit public key of the authority.
Return
- A SCALE encoded Option as defined in Definition Definition -def-num-ref- containing the proof in an opaque form.
-sec-num- BabeApi_submit_report_equivocation_unsigned_extrinsic {#sect-babeapi_submit_report_equivocation_unsigned_extrinsic}
A BABE equivocation occurs when a validator produces more than one block at the same slot. The proof of equivocation are the given distinct headers that were signed by the validator and which include the slot number. The Polkadot Host is expected to identify equivocators and report those to the Runtime using this function.
:::info If there are more than two blocks that cause an equivocation, the equivocation only needs to be reported once i.e. no additional equivocations must be reported for the same slot. :::
Arguments
-
The equivocation proof of the following format:
$$ {B}{{{m}{a}{t}{h}{r}{m}{\left\lbrace{E}{p}\right\rbrace}}}={\left({A}{{{m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}}},{s},{h}{{1}},{h}{{2}}\right)} $$
where
-
${A}_{{{m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}}}$ is the public key of the equivocator. -
${s}$ is the slot as described in Definition -def-num-ref- at which the equivocation occurred. -
${h}_{{1}}$ is the block header of the first block produced by the equivocator. -
${h}_{{2}}$ is the block header of the second block produced by the equivocator.Unlike during block execution, the Seal in both block headers is not removed before submission. The block headers are submitted in its full form.
-
-
An proof of the key owner in an opaque form as described in Section -sec-num-ref-.
Return
- A SCALE encoded Option as defined in Definition -def-num-ref- containing an empty value on success.
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require (Section Section -sec-num-ref-) to be called beforehand.
A function that helps to discover authorities.
Arguments
- None.
Return
- A byte array of varying size containing 256-bit public keys of the authorities.
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
Generates a set of session keys with an optional seed. The keys should be stored within the keystore exposed by the Host API. The seed needs to be valid and UTF-8 encoded.
Arguments
- A SCALE-encoded Option as defined in Definition -def-num-ref- containing an array of varying sizes indicating the seed.
Return
- A byte array of varying size containing the encoded session keys.
Decodes the given public session keys. Returns a list of raw public keys, including their key type.
Arguments
- An array of varying size containing the encoded public session keys.
Return
-
An array of varying size containing tuple pairs of the following format:
$$ {\left({k},{k}_{{{m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}}}\right)} $$
where
${k}$ is an array of varying sizes containing the raw public key and${k}_{{{m}{a}{t}{h}{r}{m}{\left\lbrace{i}{d}\right\rbrace}}}$ is a 4-byte array indicating the key type.
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
Get the current nonce of an account. This function can be used by the Polkadot Host implementation when it seems appropriate, such as for the JSON-RPC API as described in Section -sec-num-ref-.
Arguments
- The 256-bit public key of the account.
Return
- A 32-bit unsigned integer indicating the nonce of the account.
:::note
This section describes Version 2 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
:::
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
Returns information of a given extrinsic. This function is not aware of the internals of an extrinsic, but only interprets the extrinsic as some encoded value and accounts for its weight and length, the Runtime’s extrinsic base weight, and the current fee multiplier.
This function can be used by the Polkadot Host implementation when it seems appropriate, such as for the JSON-RPC API as described in Section -sec-num-ref-.
Arguments
-
A byte array of varying sizes containing the extrinsic.
-
The length of the extrinsic. [To do: why is this needed?]
Return
-
A data structure of the following format:
$$ {\left({w},{c},{f}\right)} $$
where
-
${w}$ is the weight of the extrinsic. -
${c}$ is the "class" of the extrinsic, where a class is a varying data (Definition -def-num-ref-) type defined as:$$ c = \left{ \begin{array}{l} 0 \quad \textrm{Normal extrinsic} \ 1 \quad \textrm{Operational extrinsic} \ 2 \quad \textrm{Mandatory extrinsic, which is always included} \end{array} \right. $$
-
${f}$ is the inclusion fee of the extrinsic. This does not include a tip or anything else that depends on the signature.
-
-sec-num- TransactionPaymentApi_query_fee_details {#sect-rte-transactionpaymentapi-query-fee-details}
Query the detailed fee of a given extrinsic. This function can be used by the Polkadot Host implementation when it seems appropriate, such as for the JSON-RPC API as described in Section -sec-num-ref-.
Arguments
-
A byte array of varying sizes containing the extrinsic.
-
The length of the extrinsic.
Return
-
A data structure of the following format:
$$ {\left({f},{t}\right)} $$
where
-
${f}$ is a SCALE encoded as defined in Definition -def-num-ref- containing the following data structure:$$ {f}={\left({{f}{{b}},}{{f}{{l}},}{f}_{{a}}\right)} $$
where
-
${f_b}$ is the minimum required fee for an extrinsic. -
${f_l}$ is the length fee, the amount paid for the encoded length (in bytes) of the extrinsic. -
${f_a}$ is the “adjusted weight fee,” which is a multiplication of the fee multiplier and the weight fee. The fee multiplier varies depending on the usage of the network.
-
-
${t}$ is the tip for the block author.
-
All calls in this module require Core_initialize_block (Section -sec-num-ref-) to be called beforehand.
:::caution TODO clarify differences between RuntimeCall and Extrinsics :::
-sec-num- TransactionPaymentCallApi_query_call_info {#sect-rte-transactionpaymentcallapi-query-call-info}
Query information of a dispatch class, weight, and fee of a given encoded Call.
Arguments
- A byte array of varying sizes containing the
Call. - The length of the Call.
Return
-
A data structure of the following format:
$$ (w, c, f) $$
where:
-
$w$ is the weight of the call. -
$c$ is the "class" of the call, where a class is a varying data (Definition -def-num-ref-) type defined as:$$ c = \left{\begin{array}{l} 0 \quad \textrm{Normal dispatch}\ 1 \quad \textrm{Operational dispatch}\ 2 \quad \textrm{Mandatory dispatch, which is always included regardless of their weight} \end{array}\right. $$
-
$f$ is the partial-fee of the call. This does not include a tip or anything else that depends on the signature.
-
-sec-num- TransactionPaymentCallApi_query_call_fee_details {#sect-rte-transactionpaymentcallapi-query-call-fee-details}
Query the fee details of a given encoded Call including tip.
Arguments
- A byte array of varying sizes containing the
Call. - The length of the
Call.
Return
-
A data structure of the following format:
$$ (f, t) $$
where:
-
$f$ is a SCALE encoded as defined in Definition -def-num-ref- containing the following data structure:$$ f = (f_b, f_l, f_a) $$
where:
-
$f_b$ is the minimum required fee for theCall. -
$f_l$ is the length fee, the amount paid for the encoded length (in bytes) of theCall. -
$f_a$ is the "adjusted weight fee", which is a multiplication of the fee multiplier and the weight fee. The fee multiplier varies depending on the usage of the network.
-
-
$t$ is the tip for the block author.
-
:::note
This section describes Version 1 of this API. Please check Core_version (Section -sec-num-ref-) to ensure compatibility.
Currently supports only one RPC endpoint.
:::
Runtime API for accessing information about the nomination pools. Returns the pending rewards for the member that the Account ID was given for.
Arguments
- The account ID as a SCALE encoded 32-byte address of the sender (Definition -def-num-ref-).
Return
- The SCALE encoded balance of type
u128representing the pending reward of the account ID. The default value is Zero in case of errors in fetching the rewards.
Runtime API to convert the number of points to balances given the current pool state, which is often used for unbonding.
Arguments
- An unsigned 32-bit integer representing Pool Identifier
- An unsigned 32-bit integer Points
Return
- An unsigned 32-bit integer Balance
Runtime API to convert the given amount of balances to points for the current pool state, which is often used for bonding and issuing new funds in to the pool.
Arguments
- An unsigned 32-bit integer representing Pool Identifier
- An unsigned 32-bit integer Balance
Return
- An unsigned 32-bit integer Points