[][src]Macro srml_support::decl_module

macro_rules! decl_module {
    (
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$( <I>, I: $instantiable:path $( = $module_default_instance:path )? )?
		>
		for enum $call_type:ident where origin: $origin_type:ty $(, $where_ty:ty: $where_bound:path )* {
			$( $t:tt )*
		}
	) => { ... };
    (
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$( <I>, I: $instantiable:path $( = $module_default_instance:path )? )?
		>
		for enum $call_type:ident where
			origin: $origin_type:ty,
			system = $system:ident
			$(, $where_ty:ty: $where_bound:path )*
		{
			$($t:tt)*
		}
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{}
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$vis:vis fn deposit_event $(<$dpeg:ident $(, $dpeg_instance:ident)?>)* () = default;
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{}
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$vis:vis fn deposit_event $(<$dpeg:ident $(, $dpeg_instance:ident)?>)* (
			$($param_name:ident : $param:ty),*
		) { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{}
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		fn on_finalize($($param_name:ident : $param:ty),* ) { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{}
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		fn on_initialize($($param_name:ident : $param:ty),* ) { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?
		>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		fn offchain_worker($($param_name:ident : $param:ty),* ) { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?
		>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$( #[doc = $doc_attr:tt] )*
		const $name:ident: $ty:ty = $value:expr;
		$( $rest:tt )*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?
			>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		#[weight = $weight:expr]
		$fn_vis:vis fn $fn_name:ident(
			$origin:ident $(, $(#[$codec_attr:ident])* $param_name:ident : $param:ty)*
		) $( -> $result:ty )* { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident:
				$trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?
			>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$fn_vis:vis fn $fn_name:ident(
			$from:ident $(, $(#[$codec_attr:ident])* $param_name:ident : $param:ty)*
		) $( -> $result:ty )* { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$(#[weight = $weight:expr])?
		$fn_vis:vis fn $fn_name:ident(
			$origin:ident : T::Origin $(, $(#[$codec_attr:ident])* $param_name:ident : $param:ty)*
		) $( -> $result:ty )* { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$(#[weight = $weight:expr])?
		$fn_vis:vis fn $fn_name:ident(
			origin : $origin:ty $(, $(#[$codec_attr:ident])* $param_name:ident : $param:ty)*
		) $( -> $result:ty )* { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
		$(#[doc = $doc_attr:tt])*
		$(#[weight = $weight:expr])?
		$fn_vis:vis fn $fn_name:ident(
			$( $(#[$codec_attr:ident])* $param_name:ident : $param:ty),*
		) $( -> $result:ty )* { $( $impl:tt )* }
		$($rest:tt)*
	) => { ... };
    (@normalize
		$(#[$attr:meta])*
		pub struct $mod_type:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path $(= $module_default_instance:path)?)?>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
		[ $( $dispatchables:tt )* ]
	) => { ... };
    (@call
		$ingore:ident
		$mod_type:ident<$trait_instance:ident $(, $instance:ident)?> $fn_name:ident $origin:ident $system:ident [ $( $param_name:ident),* ]
	) => { ... };
    (@impl_deposit_event
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, I: $instantiable:path)?>;
		$system:ident;
		{ $( $other_where_bounds:tt )* }
	) => { ... };
    (@impl_deposit_event
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		$system:ident;
		{ $( $other_where_bounds:tt )* }
		$vis:vis fn deposit_event$(<$event_trait_instance:ident $(, $event_instance:ident)?>)?() = default;
	) => { ... };
    (@impl_deposit_event
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		$system:ident;
		{ $( $other_where_bounds:tt )* }
		$vis:vis fn deposit_event($param:ident : $param_ty:ty) { $( $impl:tt )* }
	) => { ... };
    (@impl_on_initialize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn on_initialize() { $( $impl:tt )* }
	) => { ... };
    (@impl_on_initialize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn on_initialize($param:ident : $param_ty:ty) { $( $impl:tt )* }
	) => { ... };
    (@impl_on_initialize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
	) => { ... };
    (@impl_on_finalize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn on_finalize() { $( $impl:tt )* }
	) => { ... };
    (@impl_on_finalize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn on_finalize($param:ident : $param_ty:ty) { $( $impl:tt )* }
	) => { ... };
    (@impl_on_finalize
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
	) => { ... };
    (@impl_offchain
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn offchain_worker() { $( $impl:tt )* }
	) => { ... };
    (@impl_offchain
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
		fn offchain_worker($param:ident : $param_ty:ty) { $( $impl:tt )* }
	) => { ... };
    (@impl_offchain
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		{ $( $other_where_bounds:tt )* }
	) => { ... };
    (@impl_function
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		$origin_ty:ty;
		$ignore:ident;
		$(#[doc = $doc_attr:tt])*
		$vis:vis fn $name:ident (
			$origin:ident $(, $param:ident : $param_ty:ty )*
		) { $( $impl:tt )* }
	) => { ... };
    (@impl_function
		$module:ident<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path)?>;
		$origin_ty:ty;
		$ignore:ident;
		$(#[doc = $doc_attr:tt])*
		$vis:vis fn $name:ident (
			$origin:ident $(, $param:ident : $param_ty:ty )*
		) -> $result:ty { $( $impl:tt )* }
	) => { ... };
    (@create_call_enum
		$( #[$attr:meta] )*
		$call_type:ident;
		<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?>
		{ $( $other_where_bounds:tt )* }
		{ $( $generated_variants:tt )* }
		{ $( $current_params:tt )* }
		variant $fn_name:ident;
		$( #[doc = $doc_attr:tt] )*
		#[compact]
		$type:ty;
		$( $rest:tt )*
	) => { ... };
    (@create_call_enum
		$( #[$attr:meta] )*
		$call_type:ident;
		<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?>
		{ $( $other_where_bounds:tt )* }
		{ $( $generated_variants:tt )* }
		{ $( $current_params:tt )* }
		variant $fn_name:ident;
		$(#[doc = $doc_attr:tt])*
		$type:ty;
		$( $rest:tt )*
	) => { ... };
    (@create_call_enum
		$( #[$attr:meta] )*
		$call_type:ident;
		<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?>
		{ $( $other_where_bounds:tt )* }
		{ $( $generated_variants:tt )* }
		{ $( $current_params:tt )* }
		variant $fn_name:ident;
		$(#[doc = $doc_attr:tt])*
		$(
			variant $next_fn_name:ident;
			$( $rest:tt )*
		)?
	) => { ... };
    (@create_call_enum
		$( #[$attr:meta] )*
		$call_type:ident;
		<$trait_instance:ident: $trait_name:ident$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?>
		{ $( $other_where_bounds:tt )* }
		{ $( $generated_variants:tt )* }
		{}
	) => { ... };
    (@imp
		$(#[$attr:meta])*
		pub struct $mod_type:ident<
			$trait_instance:ident: $trait_name:ident
			$(<I>, $instance:ident: $instantiable:path $(= $module_default_instance:path)?)?
		>
		for enum $call_type:ident where origin: $origin_type:ty, system = $system:ident {
			$(
				$(#[doc = $doc_attr:tt])*
				#[weight = $weight:expr]
				$fn_vis:vis fn $fn_name:ident(
					$from:ident $( , $(#[$codec_attr:ident])* $param_name:ident : $param:ty)*
				) $( -> $result:ty )* { $( $impl:tt )* }
				{ $($fn_instance:ident: $fn_instantiable:path)? }
			)*
		}
		{ $( $other_where_bounds:tt )* }
		{ $( $deposit_event:tt )* }
		{ $( $on_initialize:tt )* }
		{ $( $on_finalize:tt )* }
		{ $( $offchain:tt )* }
		{ $( $constants:tt )* }
	) => { ... };
}

Declares a Module struct and a Call enum, which implements the dispatch logic.

Declaration

decl_module! {
	pub struct Module<T: Trait> for enum Call where origin: T::Origin {

		// Private functions are dispatchable, but not available to other
		// SRML modules.
		fn my_function(origin, var: u64) -> Result {
			// Your implementation
			Ok(())
		}

		// Public functions are both dispatchable and available to other
		// SRML modules.
		pub fn my_public_function(origin) -> Result {
			// Your implementation
			Ok(())
		}
	}
}

The declaration is set with the header where:

The first parameter of dispatchable functions must always be origin.

Shorthand Example

The macro automatically expands a shorthand function declaration to return the Result type. These functions are the same:

decl_module! {
	pub struct Module<T: Trait> for enum Call where origin: T::Origin {

		fn my_long_function(origin) -> Result {
			// Your implementation
			Ok(())
		}

		fn my_short_function(origin) {
			// Your implementation
		}
	}
}

Privileged Function Example

A privileged function checks that the origin of the call is ROOT.

decl_module! {
	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
		fn my_privileged_function(origin) -> Result {
			ensure_root(origin)?;
			// Your implementation
			Ok(())
		}
	}
}

Multiple Module Instances Example

A Substrate module can be built such that multiple instances of the same module can be used within a single runtime. For example, the Balances module can be added multiple times to your runtime in order to support multiple, independent currencies for your blockchain. Here is an example of how you would declare such a module using the decl_module! macro:

pub trait Trait<I: Instance=DefaultInstance>: system::Trait {}

decl_module! {
	pub struct Module<T: Trait<I>, I: Instance = DefaultInstance> for enum Call where origin: T::Origin {
		// Your implementation
	}
}

Note: decl_storage must be called to generate Instance trait and optionally DefaultInstance type.

Where clause

Besides the default origin: T::Origin, you can also pass other bounds to the module declaration. This where bound will be replicated to all types generated by this macro. The chaining of multiple trait bounds with + is not supported. If multiple bounds for one type are required, it needs to be split up into multiple bounds.

pub trait Trait: system::Trait where Self::AccountId: From<u32> {}

decl_module! {
	pub struct Module<T: Trait> for enum Call where origin: T::Origin, T::AccountId: From<u32> {
		// Your implementation
	}
}

Reserved Functions

The following are reserved function signatures:

The following reserved functions also take the block number (with type T::BlockNumber) as an optional input: