CHERRY-PICK #4200: Add documentation to SubmitSignedTransaction and a…

…ctually make it work

Squashed commit of the following:

commit dc8d71c
Author: Tomasz Drwięga <[email protected]>
Date:   Tue Dec 3 16:29:33 2019 +0100

    Split the method to avoid confusing type error message.

commit 0c4c037
Author: Tomasz Drwięga <[email protected]>
Date:   Tue Dec 3 16:19:55 2019 +0100

    Make accounts optional, fix logic.

commit d715f64
Author: Tomasz Drwięga <[email protected]>
Date:   Tue Dec 3 10:06:20 2019 +0100

    Remove warning.

commit 3f38218
Merge: f85b890 368318c
Author: Tomasz Drwięga <[email protected]>
Date:   Tue Dec 3 07:08:05 2019 +0100

    Merge branch 'master' into td-signed-transactions

commit f85b890
Merge: f8c9540 d8d5da2
Author: Tomasz Drwięga <[email protected]>
Date:   Mon Dec 2 13:57:25 2019 +0100

    Merge branch 'master' into td-signed-transactions

commit f8c9540
Author: Tomasz Drwięga <[email protected]>
Date:   Mon Nov 25 17:34:52 2019 +0100

    Forgotten import.

commit a645b90
Author: Tomasz Drwięga <[email protected]>
Date:   Mon Nov 25 17:32:10 2019 +0100

    Fix naming and bounds.

commit bc28c60
Author: Tomasz Drwięga <[email protected]>
Date:   Mon Nov 25 17:01:05 2019 +0100

    Add documentation to signed transactions and actually make them work.

bin/node/runtime/src/lib.rs

@@ -778,22 +778,29 @@ impl_runtime_apis! {
 #[cfg(test)]
 mod tests {
 	use super::*;
-	use system::offchain::SubmitSignedTransaction;
-
-	fn is_submit_signed_transaction<T>(_arg: T) where
-		T: SubmitSignedTransaction<
-			Runtime,
-			Call,
-			Extrinsic=UncheckedExtrinsic,
-			CreateTransaction=Runtime,
-			Signer=ImOnlineId,
-		>,
-	{}
+	use system::offchain::{SignAndSubmitTransaction, SubmitSignedTransaction};
 
 	#[test]
 	fn validate_bounds() {
-		let x = SubmitImOnlineTransaction::default();
-		is_submit_signed_transaction(x);
+		fn is_submit_signed_transaction<T>() where
+			T: SubmitSignedTransaction<
+				Runtime,
+				Call,
+			>,
+		{}
+
+		fn is_sign_and_submit_transaction<T>() where
+			T: SignAndSubmitTransaction<
+				Runtime,
+				Call,
+				Extrinsic=UncheckedExtrinsic,
+				CreateTransaction=Runtime,
+				Signer=ImOnlineId,
+			>,
+		{}
+
+		is_submit_signed_transaction::<SubmitImOnlineTransaction>();
+		is_sign_and_submit_transaction::<SubmitImOnlineTransaction>();
 	}
 
 	#[test]

frame/system/src/offchain.rs

@@ -17,14 +17,52 @@
 //! Module helpers for offchain 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 support::debug;
+
+/// Creates runtime-specific signed transaction.
+///
+/// This trait should be implemented by your `Runtime` to be able
+/// to submit `SignedTransaction`s` to the pool from offchain code.
+pub trait CreateTransaction<T: crate::Trait, Extrinsic: ExtrinsicT> {
+	/// A `Public` key representing a particular `AccountId`.
+	type Public: Clone + IdentifyAccount<AccountId=T::AccountId>;
+	/// A `Signature` generated by the `Signer`.
+	type Signature;
+
+	/// Attempt to create signed extrinsic data that encodes call from given account.
+	///
+	/// Runtime implementation is free to construct the payload to sign and the signature
+	/// in any way it wants.
+	/// Returns `None` if signed extrinsic could not be created (either because signing failed
+	/// or because of any other runtime-specific reason).
+	fn create_transaction<F: Signer<Self::Public, Self::Signature>>(
+		call: Extrinsic::Call,
+		public: Self::Public,
+		account: T::AccountId,
+		nonce: T::Index,
+	) -> Option<(Extrinsic::Call, Extrinsic::SignaturePayload)>;
+}
 
 /// 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.
+	/// 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>;
 }
 
@@ -33,59 +71,43 @@ pub trait Signer<Public, Signature> {
 /// 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,
+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<
-		<<AppPublic as RuntimeAppPublic>::Signature as app_crypto::AppSignature>::Generic
+		<<TAnyAppPublic as RuntimeAppPublic>::Signature as AppSignature>::Generic
 	>,
-	Public: sp_std::convert::TryInto<<AppPublic as app_crypto::AppPublic>::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()?;
-			AppPublic::from(public).sign(&payload)
+			TAnyAppPublic::from(public).sign(&payload)
 				.map(
-					<<AppPublic as RuntimeAppPublic>::Signature as app_crypto::AppSignature>
+					<<TAnyAppPublic as RuntimeAppPublic>::Signature as AppSignature>
 					 ::Generic::from
 				)
 				.map(Signature::from)
 		})
 	}
 }
 
-/// Creates runtime-specific signed transaction.
-pub trait CreateTransaction<T: crate::Trait, Extrinsic: ExtrinsicT> {
-	/// A `Public` key representing a particular `AccountId`.
-	type Public: IdentifyAccount<AccountId=T::AccountId> + Clone;
-	/// A `Signature` generated by the `Signer`.
-	type Signature;
-
-	/// Attempt to create signed extrinsic data that encodes call from given account.
-	///
-	/// Runtime implementation is free to construct the payload to sign and the signature
-	/// in any way it wants.
-	/// Returns `None` if signed extrinsic could not be created (either because signing failed
-	/// or because of any other runtime-specific reason).
-	fn create_transaction<F: Signer<Self::Public, Self::Signature>>(
-		call: Extrinsic::Call,
-		public: Self::Public,
-		account: T::AccountId,
-		nonce: T::Index,
-	) -> 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,
-	>
+/// 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> {
+///
+/// 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,6 +129,12 @@ 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)
 			.ok_or(())?;
@@ -116,6 +144,10 @@ pub trait SubmitSignedTransaction<T: crate::Trait, Call> {
 }
 
 /// A trait to submit unsigned transactions in offchain 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 +162,91 @@ 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>,
+	)>;
+
+	/// 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_local_keys(None as Option<Vec<_>>);
+		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 +258,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 +269,60 @@ 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
+		}
+	}
+}
+