56 releases (36 major breaking)

new 38.0.0 Jul 18, 2024
37.0.0 Jun 21, 2024
36.0.0 May 23, 2024
35.0.0 Apr 30, 2024
2.0.0-alpha.5 Mar 24, 2020

#1348 in Magic Beans

Download history 11449/week @ 2024-03-29 11375/week @ 2024-04-05 9386/week @ 2024-04-12 9067/week @ 2024-04-19 9758/week @ 2024-04-26 8481/week @ 2024-05-03 8008/week @ 2024-05-10 8859/week @ 2024-05-17 9540/week @ 2024-05-24 9843/week @ 2024-05-31 7734/week @ 2024-06-07 7560/week @ 2024-06-14 11451/week @ 2024-06-21 7232/week @ 2024-06-28 8676/week @ 2024-07-05 10061/week @ 2024-07-12

38,731 downloads per month
Used in 714 crates (278 directly)

Apache-2.0

645KB
13K SLoC

I/O host interface for Substrate runtime.

License: Apache-2.0


lib.rs:

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:

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");
});

Dependencies

~14–28MB
~449K SLoC