Appendix C: Runtime API

Description of how to interact with the Runtime through its exported functions

C.1. General Information

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 C.4.1.) 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.

C.1.1. JSON-RPC API for external services

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.

C.2. Runtime Constants

C.2.1. __heap_base

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 2.6.3.1..

C.3. Runtime Call Convention

Definition 228. Runtime API Call Convention

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 216) to the SCALE-encoded return data.

See Section 2.6.3. for more information about the behavior of the Wasm Runtime. Also, note that any storage changes must be fork-aware (Section 2.4.5.).

C.4. Module Core

note

This section describes Version 3 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

C.4.1. Core_version

note

For newer Runtimes, the version identifiers can be read directly from the Wasm blob in the form of custom sections (Section 2.6.3.4.). 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 C.1.1..

Arguments

• None

Return

• A data structure of the following format:

  Table 7. Details of the version that the data type returns from the Runtime function.

  Name	Type	Description
  spec_name	String	Runtime identifier
  impl_name	String	Name of the implementation (e.g. C++)
  authoring_version	Unsigned 32-bit integer	Version of the authorship interface
  spec_version	Unsigned 32-bit integer	Version of the Runtime specification
  impl_version	Unsigned 32-bit integer	Version of the Runtime implementation
  apis	ApiVersions (Definition 229)	List of supported APIs along with their version
  transaction_version	Unsigned 32-bit integer	Version of the transaction format
  state_version	Unsigned 8-bit integer	Version of the trie format

Definition 229. ApiVersions

ApiVersions is a specialized type for the (Section C.4.1.) 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.

C.4.2. Core_execute_block

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 11, 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 10, and the block body, as described in Definition 13.

Return

• None.

C.4.3. Core_initialize_block

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 10. The values ${H}_{{r}}$, ${H}_{{e}}$ and ${H}_{{d}}$ are left empty.

Return

• None.

C.5. Module Metadata

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

C.5.1. Metadata_metadata

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 C.1.1., and returns all the information necessary to build valid transactions.

Arguments

• None.

Return

• The scale-encoded (Section A.2.2.) runtime metadata as described in Chapter 12.

C.5.2. Metadata_metadata_at_version

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 A.2.2.) runtime metadata as described in Chapter 12 at the particular version.

C.5.3. Metadata_metadata_versions

Returns supported metadata versions.

Arguments

• None.

Return

• A vector of supported metadata versions of type vec<u32>.

C.6. Module BlockBuilder

note

This section describes Version 4 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.6.1. BlockBuilder_apply_extrinsic

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 230. This structure lets the block builder know whether an extrinsic should be included in the block or rejected.

Definition 230. ApplyExtrinsicResult

ApplyExtrinsicResult is a varying data type as defined in Definition 201. This structure can contain multiple nested structures, indicating either module dispatch outcomes or transaction invalidity errors.

Table 8. Possible values of varying data type ApplyExtrinsicResult.

Id	Description	Type
0	Outcome of dispatching the extrinsic.	DispatchOutcome (Definition 231)
1	Possible errors while checking the validity of a transaction.	TransactionValidityError (Definition 234)

info

As long as a DispatchOutcome (Definition 231) 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 231. DispatchOutcome

DispatchOutcome is the varying data type as defined in Definition 201.

Table 9. Possible values of varying data type DispatchOutcome.

Id	Description	Type
0	Extrinsic is valid and was submitted successfully.	None
1	Possible errors while dispatching the extrinsic.	DispatchError (Definition 232)

Definition 232. DispatchError

DispatchError is a varying data type as defined in Definition 198. Indicates various reasons why a dispatch call failed.

Table 10. Possible values of varying data type DispatchError.

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 233)

Definition 233. CustomModuleError

CustomModuleError is a tuple appended after a possible error in as defined in Definition 232.

Table 11. Possible values of varying data type CustomModuleError.

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 200). The optional value is a SCALE-encoded byte array containing a valid UTF-8 sequence.

info

Whenever TransactionValidityError (Definition 234) 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 235 and respectively Definition 236.

Definition 234. TransactionValidityError

TransactionValidityError is a varying data type as defined in Definition 198. It indicates possible errors that can occur while checking the validity of a transaction.

Table 12. Possible values of varying data type TransactionValidityError.

Id	Description	Type
0	Transaction is invalid.	InvalidTransaction (Definition 235)
1	Transaction validity can’t be determined.	UnknownTransaction (Definition 236)

Definition 235. InvalidTransaction

InvalidTransaction is a varying data type as defined in Definition 198 and specifies the invalidity of the transaction in more detail.

Table 13. Possible values of varying data type InvalidTransaction.

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 236. UnknownTransaction

UnknownTransaction is a varying data type as defined in Definition 198 and specifies the unknown invalidity of the transaction in more detail.

Table 14. Possible values of varying data type UnknownTransaction.

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

C.6.2. BlockBuilder_finalize_block

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 10.

C.6.3. BlockBuilder_inherent_extrinisics:

Generates the inherent extrinsics, which are explained in more detail in Section 2.3.3.. This function takes a SCALE-encoded hash table as defined in Definition 202 and returns an array of extrinsics. The Polkadot Host must submit each of those to the BlockBuilder_apply_extrinsic, described in Section C.6.1.. This procedure is outlined in Build-Block.

Arguments

• A Inherents-Data structure as defined in Definition 15.

Return

• A byte array of varying sizes containing extrinisics. Each extrinsic is a byte array of varying size.

C.6.4. BlockBuilder_check_inherents

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 10 and the block body as described in Definition 13.

• A Inherents-Data structure as defined in Definition 15.

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 15 containing any errors created by this Runtime function.

C.7. Module TaggedTransactionQueue

note

This section describes Version 2 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.7.1. TaggedTransactionQueue_validate_transaction

This entry is invoked against extrinsics submitted through a transaction network message (Section 4.8.6.) or by an off-chain worker through the Host API (Section B.6.2.).

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 C.4.2..

Arguments

• The source of the transaction as defined in Definition 237.

• A byte array that contains the transaction.

• The hash of the parent of the block that the transaction is included in.

  Definition 237. TransactionSource

  TransactionSource is an enum describing the source of a transaction and can have one of the following values:

  Table 15. The TransactionSource enum

  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 201 which contains the type ValidTransaction as defined in Definition 238 on success and the type TransactionValidityError as defined in Definition 234 on failure.

  Definition 238. ValidTransaction

  ValidTransaction is a tuple that contains information concerning a valid transaction.

  Table 16. The tuple provided by in the case the transaction is judged to be valid.

  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.

C.8. Module OffchainWorkerApi

note

This section describes Version 2 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

Does not require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.8.1. OffchainWorkerApi_offchain_worker

Starts an off-chain worker and generates extrinsics. [To do: when is this called?]

Arguments

• The block header as defined in Definition 10.

Return

• None.

C.9. Module ParachainHost

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

C.9.1. ParachainHost_validators

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.

C.9.2. ParachainHost_validator_groups

Returns the validator groups (Definition 146) used during the current session. The validators in the groups are referred to by the validator set Id (Definition 78).

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 78).

  • ${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.

C.9.3. ParachainHost_availability_cores

Returns information on all availability cores (Definition 145).

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 200) 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 200) 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 151). 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 146) 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 116).

  • ${C}_{{i}}$ is an Option value (Definition 200) which can contain the collators public key indicating who should author the block.

C.9.4. ParachainHost_persisted_validation_data

Returns the persisted validation data for the given parachain Id and a given occupied core assumption.

Arguments

• The parachain Id (Definition 144).

• An occupied core assumption (Definition 239).

Return

• An Option value (Definition 200) which can contain the persisted validation data (Definition 240). 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 239. Occupied Core Assumption

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:

$${A}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\\{1}&\rightarrow&\phi\\{2}&\rightarrow&\phi\end{matrix}\right.}$$

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 240. Persisted Validation Data

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}}}$, is a datastructure of the following format:

$${D}_{{{p}{v}}}={\left({P}_{{h}},{H}_{{i}},{H}_{{r}},{m}_{{b}}\right)}$$

where

• ${P}_{{h}}$ is the parent head data (Definition 143).

• ${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 C.9.4.).

C.9.5. ParachainHost_assumed_validation_data

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 144).
• Expected Persistent Validation Data Hash (Definition 240).

Return

• An Option value (Definition 200) which can contain the pair of persisted validation data (Definition 240) and Validation Code Hash. The value is None if the parachain Id is not registered or the validation data hash does not match the expected one.

C.9.6. ParachainHost_check_validation_outputs

Checks if the given validation outputs pass the acceptance criteria.

Arguments

• The parachain Id (Definition 144).

• The candidate commitments (Definition 117).

Return

• A boolean indicating whether the candidate commitments pass the acceptance criteria.

C.9.7. ParachainHost_session_index_for_child

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.

C.9.8. ParachainHost_validation_code

Fetches the validation code (Runtime) of a parachain by parachain Id.

Arguments

• The parachain Id (Definition 144).

• The occupied core assumption (Definition 239).

Return

• An Option value (Definition 200) 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.

C.9.9. ParachainHost_validation_code_by_hash

Returns the validation code (Runtime) of a parachain by its hash.

Arguments

• The hash value of the validation code.

Return

• An Option value (Definition 200) 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.

C.9.10. ParachainHost_validation_code_hash

Returns the validation code hash of a parachain.

Arguments

• The parachain Id (Definition 144).
• An occupied core assumption (Definition 239).

Return

• An Option value (Definition 200) containing the hash value of the validation code. This value is empty if the parachain Id cannot be found or the assumption is wrong.

C.9.11. 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 144).

Return

• An Option value (Definition 200) containing the committed candidate receipt (Definition 114). This value is empty if the given parachain Id is not assigned to an occupied availability core.

C.9.12. ParachainHost_candidate_events

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 114).

  • ${h}$ is the parachain head data (Definition 143).

  • ${I}_{{c}}$ is the index of the availability core as can be retrieved in Section C.9.3. 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 146) that is responsible of backing the candidate.

C.9.13. ParachainHost_session_info

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 200) 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 C.9.1.).

  • ${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 C.9.1.). 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 C.9.1.).

  • ${G}$ indicates the validator groups in shuffled order.

  • ${v}_{{n}}$ is public key of the authority.

  • ${A}_{{n}}$ is the authority set Id (Definition 78).

  • ${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.

C.9.14. ParachainHost_dmq_contents

Returns all the pending inbound messages in the downward message queue for a given parachain.

Arguments

• The parachain Id (Definition 144).

Return

• An array of inbound downward messages (Definition 148).

C.9.15. 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 144).

Return

• An array of inbound HRMP messages (Definition 150).

C.9.16. ParachainHost_on_chain_votes

Returns disputes relevant from on-chain, backing votes, and resolved disputes.

Arguments

• None

Return

• An Option (Definition 200) type which can contain the scraped on-chain votes data (Definition 241).

Definition 241. Scraped On Chain Vote

Contains the scraped runtime backing votes and resolved disputes.

The scraped on-chain votes data, $SOCV$, is a data structure of the following format:

$$SOCV = (S_i,BV,d) \\ BV = [C_r, [(i,a)]]$$

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 114). Each candidate $C_r$ has a list of $(i,a)$, the pair of validator index and validation attestations (Definition 113).
• $d$ is a set of dispute statements (Section 8.7.2.1.). 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.

C.9.17. ParachainHost_pvfs_require_precheck

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.

C.9.18. ParachainHost_submit_pvf_check_statement

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 C.9.17.) anymore.

Arguments

• A PVF pre checking statement (Definition 242) to be submitted into the transaction pool.
• Validator Signature (Definition 113).

Return

• None

Definition 242. PVF Check Statement

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 $S_{pvf}$, is a datastructure of the following format:

$$S_{pvf} = (b,VC_H,S_i,V_i)$$

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 113).

C.9.19. ParachainHost_disputes

This runtime API fetches all on-chain disputes.

Arguments

• None

Return

• A list of (SessionIndex, CandidateHash, DisputeState).

caution

TODO clarify DisputeState

C.9.20. ParachainHost_executor_params

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

C.10. Module GrandpaApi

note

This section describes Version 2 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.10.1. GrandpaApi_grandpa_authorities

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 33. Any future authority changes get tracked via Runtime-to-consensus engine messages, as described in Section 3.3.2..

Arguments

• None.

Return

• An authority list as defined in Definition 33.

C.10.2. GrandpaApi_current_set_id

This entry fetches the list of GRANDPA authority set IDs (Definition 78). Any future authority changes get tracked via Runtime-to-consensus engine messages, as described in Section 3.3.2..

Arguments

• None.

Return

• An authority set ID as defined in Definition 78.

C.10.3. 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 85. 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 78.

  • ${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 C.10.4..

Return

• A SCALE encoded Option as defined in Definition 200 containing an empty value on success.

C.10.4. GrandpaApi_generate_key_ownership_proof

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 C.10.3..

Arguments

• The authority set id as defined in Definition 78.

• The 256-bit public key of the authority.

Return

• A SCALE encoded Option as defined in Definition 200 containing the proof in an opaque form.

C.11. Module BabeApi

note

This section describes Version 2 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialized_block (Section C.4.3.) to be called beforehand.

C.11.1. BabeApi_configuration

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 17. The tuple provided by 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 64.	Tuple containing two unsigned 64bit integers
  GenesisAuthorities	The authority list for the genesis epoch as defined in Definition 33.	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 5.2.).	A one-byte enum as defined in Definition 63 as ${2}_{{\text{nd}}}$.

C.11.2. BabeApi_current_epoch_start

Finds the start slot of the current epoch.

Arguments

• None.

Return

• A unsigned 64-bit integer indicating the slot number.

C.11.3. BabeApi_current_epoch

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 33.

  • ${r}$ is a 256-bit array containing the randomness for the epoch as defined in Definition 76.

C.11.4. BabeApi_next_epoch

Produces information about the next epoch.

Arguments

• None.

Return

• Returns the same data structure as described in Section C.11.3..

C.11.5. BabeApi_generate_key_ownership_proof

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 C.11.6..

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 200 containing the proof in an opaque form.

C.11.6. 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 59 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 C.11.5..

Return

• A SCALE encoded Option as defined in Definition 200 containing an empty value on success.

C.12. Module AuthorityDiscoveryApi

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require (Section Section C.4.3.) to be called beforehand.

C.12.1. AuthorityDiscoveryApi_authorities

A function that helps to discover authorities.

Arguments

• None.

Return

• A byte array of varying size containing 256-bit public keys of the authorities.

C.13. Module SessionKeys

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.13.1. SessionKeys_generate_session_keys

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 200 containing an array of varying sizes indicating the seed.

Return

• A byte array of varying size containing the encoded session keys.

C.13.2. SessionKeys_decode_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.

C.14. Module AccountNonceApi

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.14.1. AccountNonceApi_account_nonce

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 C.1.1..

Arguments

• The 256-bit public key of the account.

Return

• A 32-bit unsigned integer indicating the nonce of the account.

C.15. Module TransactionPaymentApi

note

This section describes Version 2 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility.

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

C.15.1. TransactionPaymentApi_query_info

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 C.1.1..

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 198) 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.

C.15.2. 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 C.1.1..

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 200 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.

C.16. Module TransactionPaymentCallApi

All calls in this module require Core_initialize_block (Section C.4.3.) to be called beforehand.

caution

TODO clarify differences between RuntimeCall and Extrinsics

C.16.1. 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 198) 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.

C.16.2. 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 200 containing the following data structure:

    $$f = (f_b, f_l, f_a)$$

    where:

    • $f_b$ is the minimum required fee for the Call.
    • $f_l$ is the length fee, the amount paid for the encoded length (in bytes) of the Call.
    • $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.

C.17. Module Nomination Pools

note

This section describes Version 1 of this API. Please check Core_version (Section C.4.1.) to ensure compatibility. Currently supports only one RPC endpoint.

C.17.1. NominationPoolsApi_pending_rewards

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 154).

Return

• The SCALE encoded balance of type u128 representing the pending reward of the account ID. The default value is Zero in case of errors in fetching the rewards.

C.17.2. NominationPoolsApi_points_to_balance

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

C.17.3. NominationPoolsApi_balance_to_points

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