Add documentation to SubmitSignedTransaction and actually make it work (#4200)

* Add documentation to signed transactions and actually make them work. * Fix naming and bounds. * Forgotten import. * Remove warning. * Make accounts optional, fix logic. * Split the method to avoid confusing type error message. * Move executor tests to integration. * Add submit transactions tests. * Make `submit_transaction` tests compile * Remove a file that was accidently committed * Add can_sign helper function. * Fix compilation. * Add a key to keystore. * Fix the tests. * Remove env_logger. * Fix sending multiple transactions. * Remove commented code. * Bring back criterion. * Remove stray debug log. * Apply suggestions from code review Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com> * Make sure to initialize block correctly. * Initialize block for offchain workers. * Add test for transaction validity. * Fix tests. * Review suggestions. * Remove redundant comment. * Make sure to use correct block number of authoring. * Change the runtime API. * Support both versions. * Bump spec version, fix RPC test. Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com> Co-authored-by: Gavin Wood <github@gavwood.com> Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>
2026-04-26 16:57:58 +00:00 · 2020-01-10 01:46:55 +01:00
parent a1e0076aa8
commit 74d6e660c6
29 changed files with 2096 additions and 1413 deletions
@@ -531,6 +531,27 @@ pub fn ensure_none<OuterOrigin, AccountId>(o: OuterOrigin) -> Result<(), BadOrig
 	}
 }

+/// A type of block initialization to perform.
+pub enum InitKind {
+	/// Leave inspectable storage entries in state.
+	///
+	/// i.e. `Events` are not being reset.
+	/// Should only be used for off-chain calls,
+	/// regular block execution should clear those.
+	Inspection,
+
+	/// Reset also inspectable storage entries.
+	///
+	/// This should be used for regular block execution.
+	Full,
+}
+
+impl Default for InitKind {
+	fn default() -> Self {
+		InitKind::Full
+	}
+}
+
 impl<T: Trait> Module<T> {
 	/// Deposits an event into this block's event record.
 	pub fn deposit_event(event: impl Into<T::Event>) {
@@ -633,6 +654,7 @@ impl<T: Trait> Module<T> {
 		parent_hash: &T::Hash,
 		txs_root: &T::Hash,
 		digest: &DigestOf<T>,
+		kind: InitKind,
 	) {
 		// populate environment
 		storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &0u32);
@@ -641,9 +663,12 @@ impl<T: Trait> Module<T> {
 		<ParentHash<T>>::put(parent_hash);
 		<BlockHash<T>>::insert(*number - One::one(), parent_hash);
 		<ExtrinsicsRoot<T>>::put(txs_root);
-		<Events<T>>::kill();
-		EventCount::kill();
-		<EventTopics<T>>::remove_all();
+
+		if let InitKind::Full = kind {
+			<Events<T>>::kill();
+			EventCount::kill();
+			<EventTopics<T>>::remove_all();
+		}
 	}

 	/// Remove temporary "environment" entries in storage.
@@ -1220,7 +1245,13 @@ mod tests {
 	#[test]
 	fn deposit_event_should_work() {
 		new_test_ext().execute_with(|| {
-			System::initialize(&1, &[0u8; 32].into(), &[0u8; 32].into(), &Default::default());
+			System::initialize(
+				&1,
+				&[0u8; 32].into(),
+				&[0u8; 32].into(),
+				&Default::default(),
+				InitKind::Full,
+			);
 			System::note_finished_extrinsics();
 			System::deposit_event(1u16);
 			System::finalize();
@@ -1235,7 +1266,13 @@ mod tests {
 				]
 			);

-			System::initialize(&2, &[0u8; 32].into(), &[0u8; 32].into(), &Default::default());
+			System::initialize(
+				&2,
+				&[0u8; 32].into(),
+				&[0u8; 32].into(),
+				&Default::default(),
+				InitKind::Full,
+			);
 			System::deposit_event(42u16);
 			System::note_applied_extrinsic(&Ok(()), 0, Default::default());
 			System::note_applied_extrinsic(&Err(DispatchError::BadOrigin), 0, Default::default());
@@ -1264,6 +1301,7 @@ mod tests {
 				&[0u8; 32].into(),
 				&[0u8; 32].into(),
 				&Default::default(),
+				InitKind::Full,
 			);
 			System::note_finished_extrinsics();

@@ -1329,6 +1367,7 @@ mod tests {
 					&[n as u8 - 1; 32].into(),
 					&[0u8; 32].into(),
 					&Default::default(),
+					InitKind::Full,
 				);

 				System::finalize();
@@ -14,49 +14,19 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-//! Module helpers for offchain calls.
+//! Module helpers for off-chain calls.

 use codec::Encode;
-use sp_runtime::app_crypto::{self, RuntimeAppPublic};
+use sp_std::convert::TryInto;
+use sp_std::prelude::Vec;
+use sp_runtime::app_crypto::{RuntimeAppPublic, AppPublic, AppSignature};
 use sp_runtime::traits::{Extrinsic as ExtrinsicT, IdentifyAccount};
+use frame_support::debug;

-/// A trait responsible for signing a payload using given account.
-pub trait Signer<Public, Signature> {
-	/// Sign any encodable payload with given account and produce a signature.
-	///
-	/// Returns `Some` if signing succeeded and `None` in case the `account` couldn't be used.
-	fn sign<Payload: Encode>(public: Public, payload: &Payload) -> Option<Signature>;
-}
-
-/// A `Signer` implementation for any `AppPublic` type.
+/// Creates runtime-specific signed transaction.
 ///
-/// This implementation additionaly supports conversion to/from multi-signature/multi-signer
-/// wrappers.
-/// If the wrapped crypto doesn't match `AppPublic`s crypto `None` is returned.
-impl<Public, Signature, AppPublic> Signer<Public, Signature> for AppPublic where
-	AppPublic: RuntimeAppPublic
-		+ app_crypto::AppPublic
-		+ From<<AppPublic as app_crypto::AppPublic>::Generic>,
-	<AppPublic as RuntimeAppPublic>::Signature: app_crypto::AppSignature,
-	Signature: From<
-		<<AppPublic as RuntimeAppPublic>::Signature as app_crypto::AppSignature>::Generic
-	>,
-	Public: sp_std::convert::TryInto<<AppPublic as app_crypto::AppPublic>::Generic>
-{
-	fn sign<Payload: Encode>(public: Public, raw_payload: &Payload) -> Option<Signature> {
-		raw_payload.using_encoded(|payload| {
-			let public = public.try_into().ok()?;
-			AppPublic::from(public).sign(&payload)
-				.map(
-					<<AppPublic as RuntimeAppPublic>::Signature as app_crypto::AppSignature>
-					 ::Generic::from
-				)
-				.map(Signature::from)
-		})
-	}
-}
-
-/// Creates a runtime-specific signed transaction.
+/// This trait should be implemented by your `Runtime` to be able
+/// to submit `SignedTransaction`s` to the pool from off-chain code.
 pub trait CreateTransaction<T: crate::Trait, Extrinsic: ExtrinsicT> {
 	/// A `Public` key representing a particular `AccountId`.
 	type Public: IdentifyAccount<AccountId=T::AccountId> + Clone;
@@ -77,15 +47,67 @@ pub trait CreateTransaction<T: crate::Trait, Extrinsic: ExtrinsicT> {
 	) -> Option<(Extrinsic::Call, Extrinsic::SignaturePayload)>;
 }

-type PublicOf<T, Call, X> = <
-	<X as SubmitSignedTransaction<T, Call>>::CreateTransaction as CreateTransaction<
-		T,
-		<X as SubmitSignedTransaction<T, Call>>::Extrinsic,
-	>
+/// A trait responsible for signing a payload using given account.
+///
+/// This trait is usually going to represent a local public key
+/// that has ability to sign arbitrary `Payloads`.
+///
+/// NOTE: Most likely you don't need to implement this trait manually.
+/// It has a blanket implementation for all `RuntimeAppPublic` types,
+/// so it's enough to pass an application-specific crypto type.
+///
+/// To easily create `SignedTransaction`s have a look at the
+/// [`TransactionSubmitter`] type.
+pub trait Signer<Public, Signature> {
+	/// Sign any encodable payload with given account and produce a signature.
+	///
+	/// Returns `Some` if signing succeeded and `None` in case the `account` couldn't
+	/// be used (for instance we couldn't convert it to required application specific crypto).
+	fn sign<Payload: Encode>(public: Public, payload: &Payload) -> Option<Signature>;
+}
+
+/// A `Signer` implementation for any `AppPublic` type.
+///
+/// This implementation additionaly supports conversion to/from multi-signature/multi-signer
+/// wrappers.
+/// If the wrapped crypto doesn't match `AppPublic`s crypto `None` is returned.
+impl<Public, Signature, TAnyAppPublic> Signer<Public, Signature> for TAnyAppPublic where
+	TAnyAppPublic: RuntimeAppPublic
+		+ AppPublic
+		+ From<<TAnyAppPublic as AppPublic>::Generic>,
+	<TAnyAppPublic as RuntimeAppPublic>::Signature: AppSignature,
+	Signature: From<
+		<<TAnyAppPublic as RuntimeAppPublic>::Signature as AppSignature>::Generic
+	>,
+	Public: TryInto<<TAnyAppPublic as AppPublic>::Generic>
+{
+	fn sign<Payload: Encode>(public: Public, raw_payload: &Payload) -> Option<Signature> {
+		raw_payload.using_encoded(|payload| {
+			let public = public.try_into().ok()?;
+			TAnyAppPublic::from(public).sign(&payload)
+				.map(
+					<<TAnyAppPublic as RuntimeAppPublic>::Signature as AppSignature>
+					 ::Generic::from
+				)
+				.map(Signature::from)
+		})
+	}
+}
+
+/// Retrieves a public key type for given `SignAndSubmitTransaction`.
+pub type PublicOf<T, Call, X> = <
+	<X as SignAndSubmitTransaction<T, Call>>::CreateTransaction
+	as
+	CreateTransaction<T, <X as SignAndSubmitTransaction<T, Call>>::Extrinsic>
 >::Public;

-/// A trait to sign and submit transactions in offchain calls.
-pub trait SubmitSignedTransaction<T: crate::Trait, Call> {
+/// A trait to sign and submit transactions in off-chain calls.
+///
+/// NOTE: Most likely you should not implement this trait yourself.
+/// There is an implementation for
+/// [`TransactionSubmitter`] type, which
+/// you should use.
+pub trait SignAndSubmitTransaction<T: crate::Trait, Call> {
 	/// Unchecked extrinsic type.
 	type Extrinsic: ExtrinsicT<Call=Call> + codec::Encode;

@@ -107,15 +129,30 @@ pub trait SubmitSignedTransaction<T: crate::Trait, Call> {
 		let call = call.into();
 		let id = public.clone().into_account();
 		let expected = <crate::Module<T>>::account_nonce(&id);
+		debug::native::debug!(
+			target: "offchain",
+			"Creating signed transaction from account: {:?} (nonce: {:?})",
+			id,
+			expected,
+		);
 		let (call, signature_data) = Self::CreateTransaction
-			::create_transaction::<Self::Signer>(call, public, id, expected)
+			::create_transaction::<Self::Signer>(call, public, id.clone(), expected)
 			.ok_or(())?;
+		// increment the nonce. This is fine, since the code should always
+		// be running in off-chain context, so we NEVER persists data.
+		<crate::Module<T>>::inc_account_nonce(&id);
+
 		let xt = Self::Extrinsic::new(call, Some(signature_data)).ok_or(())?;
 		sp_io::offchain::submit_transaction(xt.encode())
 	}
 }

 /// A trait to submit unsigned transactions in off-chain calls.
+///
+/// NOTE: Most likely you should not implement this trait yourself.
+/// There is an implementation for
+/// [`TransactionSubmitter`] type, which
+/// you should use.
 pub trait SubmitUnsignedTransaction<T: crate::Trait, Call> {
 	/// Unchecked extrinsic type.
 	type Extrinsic: ExtrinsicT<Call=Call> + codec::Encode;
@@ -130,9 +167,114 @@ pub trait SubmitUnsignedTransaction<T: crate::Trait, Call> {
 	}
 }

+/// A utility trait to easily create signed transactions
+/// from accounts in node's local keystore.
+///
+/// NOTE: Most likely you should not implement this trait yourself.
+/// There is an implementation for
+/// [`TransactionSubmitter`] type, which
+/// you should use.
+pub trait SubmitSignedTransaction<T: crate::Trait, Call> {
+	/// A `SignAndSubmitTransaction` implementation.
+	type SignAndSubmit: SignAndSubmitTransaction<T, Call>;
+
+	/// Find local keys that match given list of accounts.
+	///
+	/// Technically it finds an intersection between given list of `AccountId`s
+	/// and accounts that are represented by public keys in local keystore.
+	/// If `None` is passed it returns all accounts in the keystore.
+	///
+	/// Returns both public keys and `AccountId`s of accounts that are available.
+	/// Such accounts can later be used to sign a payload or send signed transactions.
+	fn find_local_keys(accounts: Option<impl IntoIterator<Item = T::AccountId>>) -> Vec<(
+		T::AccountId,
+		PublicOf<T, Call, Self::SignAndSubmit>,
+	)>;
+
+	/// Find all available local keys.
+	///
+	/// This is equivalent of calling `find_local_keys(None)`.
+	fn find_all_local_keys() -> Vec<(T::AccountId, PublicOf<T, Call, Self::SignAndSubmit>)> {
+		Self::find_local_keys(None as Option<Vec<_>>)
+	}
+
+	/// Check if there are keys for any of given accounts that could be used to send a transaction.
+	///
+	/// This check can be used as an early-exit condition to avoid doing too
+	/// much work, before we actually realise that there are no accounts that you
+	/// we could use for signing.
+	fn can_sign_with(accounts: Option<impl IntoIterator<Item = T::AccountId>>) -> bool {
+		!Self::find_local_keys(accounts).is_empty()
+	}
+
+	/// Check if there are any keys that could be used for signing.
+	///
+	/// This is equivalent of calling `can_sign_with(None)`.
+	fn can_sign() -> bool {
+		Self::can_sign_with(None as Option<Vec<_>>)
+	}
+
+	/// Create and submit signed transactions from supported accounts.
+	///
+	/// This method should intersect given list of accounts with the ones
+	/// supported locally and submit signed transaction containing given `Call`
+	/// with every of them.
+	///
+	/// Returns a vector of results and account ids that were supported.
+	#[must_use]
+	fn submit_signed_from(
+		call: impl Into<Call> + Clone,
+		accounts: impl IntoIterator<Item = T::AccountId>,
+	) -> Vec<(T::AccountId, Result<(), ()>)> {
+		let keys = Self::find_local_keys(Some(accounts));
+		keys.into_iter().map(|(account, pub_key)| {
+			let call = call.clone().into();
+			(
+				account,
+				Self::SignAndSubmit::sign_and_submit(call, pub_key)
+			)
+		}).collect()
+	}
+
+	/// Create and submit signed transactions from all local accounts.
+	///
+	/// This method submits a signed transaction from all local accounts
+	/// for given application crypto.
+	///
+	/// Returns a vector of results and account ids that were supported.
+	#[must_use]
+	fn submit_signed(
+		call: impl Into<Call> + Clone,
+	) -> Vec<(T::AccountId, Result<(), ()>)> {
+		let keys = Self::find_all_local_keys();
+		keys.into_iter().map(|(account, pub_key)| {
+			let call = call.clone().into();
+			(
+				account,
+				Self::SignAndSubmit::sign_and_submit(call, pub_key)
+			)
+		}).collect()
+	}
+}
+
 /// A default type used to submit transactions to the pool.
-pub struct TransactionSubmitter<S, C, E> {
-	_signer: sp_std::marker::PhantomData<(S, C, E)>,
+///
+/// This is passed into each runtime as an opaque associated type that can have either of:
+/// - [`SignAndSubmitTransaction`]
+/// - [`SubmitUnsignedTransaction`]
+/// - [`SubmitSignedTransaction`]
+/// and used accordingly.
+///
+/// This struct should be constructed by providing the following generic parameters:
+/// * `Signer` - Usually the application specific key type (see `app_crypto`).
+/// * `CreateTransaction` - A type that is able to produce signed transactions,
+///		usually it's going to be the entire `Runtime` object.
+/// * `Extrinsic` - A runtime-specific type for in-block extrinsics.
+///
+/// If you only need the ability to submit unsigned transactions,
+/// you may substitute both `Signer` and `CreateTransaction` with any type.
+pub struct TransactionSubmitter<Signer, CreateTransaction, Extrinsic> {
+	_signer: sp_std::marker::PhantomData<(Signer, CreateTransaction, Extrinsic)>,
 }

 impl<S, C, E> Default for TransactionSubmitter<S, C, E> {
@@ -144,7 +286,7 @@ impl<S, C, E> Default for TransactionSubmitter<S, C, E> {
 }

 /// A blanket implementation to simplify creation of transaction signer & submitter in the runtime.
-impl<T, E, S, C, Call> SubmitSignedTransaction<T, Call> for TransactionSubmitter<S, C, E> where
+impl<T, E, S, C, Call> SignAndSubmitTransaction<T, Call> for TransactionSubmitter<S, C, E> where
 	T: crate::Trait,
 	C: CreateTransaction<T, E>,
 	S: Signer<<C as CreateTransaction<T, E>>::Public, <C as CreateTransaction<T, E>>::Signature>,
@@ -155,10 +297,68 @@ impl<T, E, S, C, Call> SubmitSignedTransaction<T, Call> for TransactionSubmitter
 	type Signer = S;
 }

-/// A blanket impl to use the same submitter for usigned transactions as well.
+/// A blanket implementation to use the same submitter for unsigned transactions as well.
 impl<T, E, S, C, Call> SubmitUnsignedTransaction<T, Call> for TransactionSubmitter<S, C, E> where
 	T: crate::Trait,
 	E: ExtrinsicT<Call=Call> + codec::Encode,
 {
 	type Extrinsic = E;
 }
+
+/// A blanket implementation to support local keystore of application-crypto types.
+impl<T, C, E, S, Call> SubmitSignedTransaction<T, Call> for TransactionSubmitter<S, C, E> where
+	T: crate::Trait,
+	C: CreateTransaction<T, E>,
+	E: ExtrinsicT<Call=Call> + codec::Encode,
+	S: Signer<<C as CreateTransaction<T, E>>::Public, <C as CreateTransaction<T, E>>::Signature>,
+	// Make sure we can unwrap the app crypto key.
+	S: RuntimeAppPublic + AppPublic + Into<<S as AppPublic>::Generic>,
+	// Make sure we can convert from wrapped crypto to public key (e.g. `MultiSigner`)
+	S::Generic: Into<PublicOf<T, Call, Self>>,
+	// For simplicity we require the same trait to implement `SignAndSubmitTransaction` too.
+	Self: SignAndSubmitTransaction<T, Call, Signer = S, Extrinsic = E, CreateTransaction = C>,
+{
+	type SignAndSubmit = Self;
+
+	fn find_local_keys(accounts: Option<impl IntoIterator<Item = T::AccountId>>) -> Vec<(
+		T::AccountId,
+		PublicOf<T, Call, Self::SignAndSubmit>,
+	)> {
+		// Convert app-specific keys into generic ones.
+		let local_accounts_and_keys = S::all()
+			.into_iter()
+			.map(|app_key| {
+				// unwrap app-crypto
+				let generic_pub_key: <S as AppPublic>::Generic = app_key.into();
+				// convert to expected public key type (might be MultiSigner)
+				let signer_pub_key: PublicOf<T, Call, Self::SignAndSubmit> = generic_pub_key.into();
+				// lookup accountid for that pubkey
+				let account = signer_pub_key.clone().into_account();
+				(account, signer_pub_key)
+			}).collect::<Vec<_>>();
+
+		if let Some(accounts) = accounts {
+			let mut local_accounts_and_keys = local_accounts_and_keys;
+			// sort by accountId to allow bin-search.
+			local_accounts_and_keys.sort_by(|a, b| a.0.cmp(&b.0));
+
+			// get all the matching accounts
+			accounts.into_iter().filter_map(|acc| {
+				let idx = local_accounts_and_keys.binary_search_by(|a| a.0.cmp(&acc)).ok()?;
+				local_accounts_and_keys.get(idx).cloned()
+			}).collect()
+		} else {
+			// just return all account ids and keys
+			local_accounts_and_keys
+		}
+	}
+
+	fn can_sign_with(accounts: Option<impl IntoIterator<Item = T::AccountId>>) -> bool {
+		// early exit if we care about any account.
+		if accounts.is_none() {
+			!S::all().is_empty()
+		} else {
+			!Self::find_local_keys(accounts).is_empty()
+		}
+	}
+}