Crate sp_io

Substrate Primitives: IO

This crate contains interfaces for the runtime to communicate with the outside world, ergo io. In other context, such interfaces are referred to as “host functions”.

Each set of host functions are defined with an instance of the sp_runtime_interface::runtime_interface macro.

Most notably, this crate contains host functions for:

• hashing
• crypto
• trie
• offchain
• storage
• allocator
• logging

All of the default host functions provided by this crate, and by default contained in all substrate-based clients are amalgamated in SubstrateHostFunctions.

Externalities

Host functions go hand in hand with the concept of externalities. Externalities are an environment in which host functions are provided, and thus can be accessed. Some host functions are only accessible in an externality environment that provides it.

A typical error for substrate developers is the following:

use sp_io::storage::get;
let data = get(b"hello world");

This code will panic with the following error:

thread 'main' panicked at '`get_version_1` called outside of an Externalities-provided environment.'

Such error messages should always be interpreted as “code accessing host functions accessed outside of externalities”.

An externality is any type that implements sp_externalities::Externalities. A simple example of which is TestExternalities, which is commonly used in tests and is exported from this crate.

use sp_io::{storage::get, TestExternalities};
TestExternalities::default().execute_with(|| {
	let data = get(b"hello world");
});

Modules

allocator

Wasm only interface that provides functions for calling into the allocator.

crypto

Interfaces for working with crypto related types from within the runtime.

default_child_storage

Interface for accessing the child storage for default child trie, from within the runtime.

hashing

Interface that provides functions for hashing with different algorithms.

logging

Interface that provides functions for logging from within the runtime.

misc

Interface that provides miscellaneous functions for communicating between the runtime and the node.

offchain

Interface that provides functions to access the offchain functionality.

offchain_index

Interface that provides functions to access the Offchain DB.

panic_handler

WASM-only interface which allows for aborting the execution in case of an unrecoverable error.

storage

Interface for accessing the storage from within the runtime.

transaction_index

Interface that provides transaction indexing API.

trie

Interface that provides trie related functionality.

wasm_tracing

Interface to provide tracing facilities for wasm. Modelled after tokios tracing-crate interfaces. See sp-tracing for more information.

Structs

Crossing

Crossing is a helper wrapping any Encode-Decodeable type for transferring over the wasm barrier.

MultiRemovalResults

Results concerning an operation to remove many keys.

UseDalekExt

Extension to signal to [crypt::ed25519_verify] to use the dalek crate.

Enums

EcdsaVerifyError

Error verifying ECDSA signature

KillStorageResult

The outcome of calling storage_kill. Returned value is the number of storage items removed from the backend from making the storage_kill call.

Functions

init_tracing

Initialize tracing of sp_tracing not necessary – noop. To enable build without std and with the with-tracing-feature.

unreachable

Crashes the execution of the program.

Type Aliases

SubstrateHostFunctions

The host functions Substrate provides for the Wasm runtime environment.

TestExternalities

Type alias for Externalities implementation used in tests.