topsoil-core 0.2.0

Support code for the runtime.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

// This file is part of Soil.

// Copyright (C) Soil contributors.
// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later WITH Classpath-exception-2.0

//! Traits for querying pallet view functions.

use alloc::vec::Vec;
use codec::{Decode, DecodeAll, Encode, Output};
use scale_info::TypeInfo;
use Debug;

/// The unique identifier for a view function.
#[derive(Clone, Encode, Decode, Debug, TypeInfo)]
pub struct ViewFunctionId {
	/// The part of the id for dispatching view functions from the top level of the runtime.
	///
	/// Specifies which view function grouping this view function belongs to. This could be a group
	/// of view functions associated with a pallet, or a pallet agnostic group of view functions.
	pub prefix: [u8; 16],
	/// The part of the id for dispatching to a view function within a group.
	pub suffix: [u8; 16],
}

impl From<ViewFunctionId> for [u8; 32] {
	fn from(value: ViewFunctionId) -> Self {
		let mut output = [0u8; 32];
		output[..16].copy_from_slice(&value.prefix);
		output[16..].copy_from_slice(&value.suffix);
		output
	}
}

/// Error type for view function dispatching.
#[derive(Encode, Decode, Debug, TypeInfo)]
pub enum ViewFunctionDispatchError {
	/// View functions are not implemented for this runtime.
	NotImplemented,
	/// A view function with the given `ViewFunctionId` was not found
	NotFound(ViewFunctionId),
	/// Failed to decode the view function input.
	Codec,
}

impl From<codec::Error> for ViewFunctionDispatchError {
	fn from(_: codec::Error) -> Self {
		ViewFunctionDispatchError::Codec
	}
}

/// Implemented by both pallets and the runtime. The runtime is dispatching by prefix using the
/// pallet implementation of `ViewFunctionIdPrefix` then the pallet is dispatching by suffix using
/// the methods implementation of `ViewFunctionIdSuffix`.
///
/// In more details, `ViewFunctionId` = `ViewFunctionIdPrefix` ++ `ViewFunctionIdSuffix`, where
/// `ViewFunctionIdPrefix=twox_128(pallet_name)` and
/// `ViewFunctionIdSuffix=twox_128("fn_name(fnarg_types) -> return_ty")`. The prefix is the same as
/// the storage prefix for pallets. The suffix is generated from the view function method type
/// signature, so is guaranteed to be unique for that pallet implementation.
pub trait DispatchViewFunction {
	fn dispatch_view_function<O: Output>(
		id: &ViewFunctionId,
		input: &mut &[u8],
		output: &mut O,
	) -> Result<(), ViewFunctionDispatchError>;
}

impl DispatchViewFunction for () {
	fn dispatch_view_function<O: Output>(
		_id: &ViewFunctionId,
		_input: &mut &[u8],
		_output: &mut O,
	) -> Result<(), ViewFunctionDispatchError> {
		Err(ViewFunctionDispatchError::NotImplemented)
	}
}

/// Automatically implemented for each pallet by the macro [`pallet`](crate::pallet).
pub trait ViewFunctionIdPrefix {
	fn prefix() -> [u8; 16];
}

/// Automatically implemented for each pallet view function method by the macro
/// [`pallet`](crate::pallet).
pub trait ViewFunctionIdSuffix {
	const SUFFIX: [u8; 16];
}

/// Automatically implemented for each pallet view function method by the macro
/// [`pallet`](crate::pallet).
pub trait ViewFunction: DecodeAll {
	fn id() -> ViewFunctionId;
	type ReturnType: Encode;

	fn invoke(self) -> Self::ReturnType;

	fn execute<O: Output>(
		input: &mut &[u8],
		output: &mut O,
	) -> Result<(), ViewFunctionDispatchError> {
		let view_function = Self::decode_all(input)?;
		let result = view_function.invoke();
		Encode::encode_to(&result, output);
		Ok(())
	}
}

pub mod runtime_api {
	use super::*;

	subsoil::api::decl_runtime_apis! {
		#[api_version(1)]
		/// Runtime API for executing view functions
		pub trait RuntimeViewFunction {
			/// Execute a view function query.
			fn execute_view_function(
				query_id: ViewFunctionId,
				input: Vec<u8>,
			) -> Result<Vec<u8>, ViewFunctionDispatchError>;
		}
	}
}