commenting and documenting and warning removal

substrate/primitives/application-crypto/src/bandersnatch.rs

@@ -53,11 +53,8 @@ impl RuntimePublic for Public {
 		false
 	}
 
-	fn generate_pop(&mut self, key_type: KeyTypeId) -> Option<Self::Signature> {
-		// let pub_key_as_bytes = self.to_raw_vec();
-		// let pop_context_tag: &[u8] = b"POP_";
-		// let pop_statement = [pop_context_tag, pub_key_as_bytes.as_slice()].concat();
-		// sp_io::crypto::bandersnatch_sign(key_type, self, pop_statement.as_slice()) There is no sign for bandersnatch..
+	/// Dummy implementation. Returns 'None'.
+	fn generate_pop(&mut self, _key_type: KeyTypeId) -> Option<Self::Signature> {
 		None
 	}
 

substrate/primitives/application-crypto/src/ecdsa.rs

@@ -21,8 +21,8 @@ use crate::{KeyTypeId, RuntimePublic};
 
 use alloc::vec::Vec;
 
+use sp_core::crypto::{ProofOfPossessionVerifier, POP_CONTEXT_TAG};
 pub use sp_core::ecdsa::*;
-use sp_core::crypto::ProofOfPossessionVerifier;
 
 mod app {
 	crate::app_crypto!(super, sp_core::testing::ECDSA);
@@ -51,8 +51,7 @@ impl RuntimePublic for Public {
 
 	fn generate_pop(&mut self, key_type: KeyTypeId) -> Option<Self::Signature> {
 		let pub_key_as_bytes = self.to_raw_vec();
-		let pop_context_tag: &[u8] = b"POP_";
-		let pop_statement = [pop_context_tag, pub_key_as_bytes.as_slice()].concat();
+		let pop_statement = [POP_CONTEXT_TAG, pub_key_as_bytes.as_slice()].concat();
 		sp_io::crypto::ecdsa_sign(key_type, self, pop_statement.as_slice())
 	}
 

substrate/primitives/application-crypto/src/ecdsa_bls381.rs

@@ -20,9 +20,12 @@
 use crate::{KeyTypeId, RuntimePublic};
 use alloc::vec::Vec;
 
-use sp_core::{bls381, ecdsa, ecdsa_bls381};
 pub use sp_core::paired_crypto::ecdsa_bls381::*;
-use sp_core::crypto::ProofOfPossessionVerifier;
+use sp_core::{
+	bls381,
+	crypto::{ProofOfPossessionVerifier, POP_CONTEXT_TAG},
+	ecdsa, ecdsa_bls381,
+};
 
 mod app {
 	crate::app_crypto!(super, sp_core::testing::ECDSA_BLS381);
@@ -88,39 +91,40 @@ impl RuntimePublic for Public {
 }
 
 /// Helper: Split public key bytes into ECDSA and BLS381 parts
-fn split_pub_key_bytes(pub_key_as_bytes: &[u8])
-	-> Option<([u8; ecdsa::PUBLIC_KEY_SERIALIZED_SIZE], [u8; bls381::PUBLIC_KEY_SERIALIZED_SIZE])> {
-    let ecdsa_pub_as_bytes = pub_key_as_bytes[..ecdsa::PUBLIC_KEY_SERIALIZED_SIZE]
-        .try_into()
-        .ok()?;
-    let bls381_pub_as_bytes = pub_key_as_bytes[ecdsa::PUBLIC_KEY_SERIALIZED_SIZE..]
-        .try_into()
-        .ok()?;
-    Some((ecdsa_pub_as_bytes, bls381_pub_as_bytes))
+fn split_pub_key_bytes(
+	pub_key_as_bytes: &[u8],
+) -> Option<([u8; ecdsa::PUBLIC_KEY_SERIALIZED_SIZE], [u8; bls381::PUBLIC_KEY_SERIALIZED_SIZE])> {
+	let ecdsa_pub_as_bytes =
+		pub_key_as_bytes[..ecdsa::PUBLIC_KEY_SERIALIZED_SIZE].try_into().ok()?;
+	let bls381_pub_as_bytes =
+		pub_key_as_bytes[ecdsa::PUBLIC_KEY_SERIALIZED_SIZE..].try_into().ok()?;
+	Some((ecdsa_pub_as_bytes, bls381_pub_as_bytes))
 }
 
 /// Helper: Generate ECDSA proof of possession
-fn generate_ecdsa_pop(ecdsa_pub_as_bytes: [u8; ecdsa::PUBLIC_KEY_SERIALIZED_SIZE]) -> Option<ecdsa::Signature> {
-    let pop_context_tag: &[u8] = b"POP_";
-    let ecdsa_statement = [pop_context_tag, ecdsa_pub_as_bytes.as_slice()].concat();
-    let ecdsa_pub = ecdsa::Public::from_raw(ecdsa_pub_as_bytes);
-    sp_io::crypto::ecdsa_sign(sp_core::testing::ECDSA, &ecdsa_pub, ecdsa_statement.as_slice())
+fn generate_ecdsa_pop(
+	ecdsa_pub_as_bytes: [u8; ecdsa::PUBLIC_KEY_SERIALIZED_SIZE],
+) -> Option<ecdsa::Signature> {
+	let ecdsa_statement = [POP_CONTEXT_TAG, ecdsa_pub_as_bytes.as_slice()].concat();
+	let ecdsa_pub = ecdsa::Public::from_raw(ecdsa_pub_as_bytes);
+	sp_io::crypto::ecdsa_sign(sp_core::testing::ECDSA, &ecdsa_pub, ecdsa_statement.as_slice())
 }
 
 /// Helper: Generate BLS381 proof of possession
-fn generate_bls381_pop(bls381_pub_as_bytes: [u8; bls381::PUBLIC_KEY_SERIALIZED_SIZE]) -> Option<bls381::Signature> {
-    let bls381_pub = bls381::Public::from_raw(bls381_pub_as_bytes);
-    sp_io::crypto::bls381_generate_pop(sp_core::testing::BLS381, &bls381_pub)
+fn generate_bls381_pop(
+	bls381_pub_as_bytes: [u8; bls381::PUBLIC_KEY_SERIALIZED_SIZE],
+) -> Option<bls381::Signature> {
+	let bls381_pub = bls381::Public::from_raw(bls381_pub_as_bytes);
+	sp_io::crypto::bls381_generate_pop(sp_core::testing::BLS381, &bls381_pub)
 }
 
 /// Helper: Combine ECDSA and BLS381 pops into a single raw pop
 fn combine_pop(
-    ecdsa_pop: &ecdsa::Signature,
-    bls381_pop: &bls381::Signature,
+	ecdsa_pop: &ecdsa::Signature,
+	bls381_pop: &bls381::Signature,
 ) -> Option<[u8; ecdsa_bls381::SIGNATURE_LEN]> {
-    let mut combined_pop_raw = [0u8; ecdsa_bls381::SIGNATURE_LEN];
-    combined_pop_raw[..ecdsa::SIGNATURE_SERIALIZED_SIZE].copy_from_slice(ecdsa_pop.as_ref());
-    combined_pop_raw[ecdsa::SIGNATURE_SERIALIZED_SIZE..].copy_from_slice(bls381_pop.as_ref());
-    Some(combined_pop_raw)
+	let mut combined_pop_raw = [0u8; ecdsa_bls381::SIGNATURE_LEN];
+	combined_pop_raw[..ecdsa::SIGNATURE_SERIALIZED_SIZE].copy_from_slice(ecdsa_pop.as_ref());
+	combined_pop_raw[ecdsa::SIGNATURE_SERIALIZED_SIZE..].copy_from_slice(bls381_pop.as_ref());
+	Some(combined_pop_raw)
 }
-

substrate/primitives/application-crypto/src/ed25519.rs

@@ -21,8 +21,8 @@ use crate::{KeyTypeId, RuntimePublic};
 
 use alloc::vec::Vec;
 
+use sp_core::crypto::{ProofOfPossessionVerifier, POP_CONTEXT_TAG};
 pub use sp_core::ed25519::*;
-use sp_core::crypto::ProofOfPossessionVerifier;
 
 mod app {
 	crate::app_crypto!(super, sp_core::testing::ED25519);
@@ -51,8 +51,7 @@ impl RuntimePublic for Public {
 
 	fn generate_pop(&mut self, key_type: KeyTypeId) -> Option<Self::Signature> {
 		let pub_key_as_bytes = self.to_raw_vec();
-		let pop_context_tag: &[u8] = b"POP_";
-		let pop_statement = [pop_context_tag, pub_key_as_bytes.as_slice()].concat();
+		let pop_statement = [POP_CONTEXT_TAG, pub_key_as_bytes.as_slice()].concat();
 		sp_io::crypto::ed25519_sign(key_type, self, pop_statement.as_slice())
 	}
 

substrate/primitives/application-crypto/src/lib.rs

@@ -24,7 +24,9 @@ extern crate alloc;
 
 pub use sp_core::crypto::{key_types, CryptoTypeId, DeriveJunction, KeyTypeId, Ss58Codec};
 #[doc(hidden)]
-pub use sp_core::crypto::{DeriveError, Pair, SecretStringError, ProofOfPossessionGenerator, ProofOfPossessionVerifier};
+pub use sp_core::crypto::{
+	DeriveError, Pair, ProofOfPossessionGenerator, ProofOfPossessionVerifier, SecretStringError,
+};
 #[doc(hidden)]
 pub use sp_core::{
 	self,
@@ -182,7 +184,10 @@ macro_rules! app_crypto_pair_common {
 				proof_of_possession: &Self::Signature,
 				allegedly_possessed_pubkey: &Self::Public,
 			) -> bool {
-				<$pair>::verify_proof_of_possession(&proof_of_possession.0, allegedly_possessed_pubkey.as_ref())
+				<$pair>::verify_proof_of_possession(
+					&proof_of_possession.0,
+					allegedly_possessed_pubkey.as_ref(),
+				)
 			}
 		}
 

substrate/primitives/application-crypto/src/sr25519.rs

@@ -21,8 +21,8 @@ use crate::{KeyTypeId, RuntimePublic};
 
 use alloc::vec::Vec;
 
+use sp_core::crypto::{ProofOfPossessionVerifier, POP_CONTEXT_TAG};
 pub use sp_core::sr25519::*;
-use sp_core::crypto::ProofOfPossessionVerifier;
 
 mod app {
 	crate::app_crypto!(super, sp_core::testing::SR25519);
@@ -51,8 +51,7 @@ impl RuntimePublic for Public {
 
 	fn generate_pop(&mut self, key_type: KeyTypeId) -> Option<Self::Signature> {
 		let pub_key_as_bytes = self.to_raw_vec();
-		let pop_context_tag: &[u8] = b"POP_";
-		let pop_statement = [pop_context_tag, pub_key_as_bytes.as_slice()].concat();
+		let pop_statement = [POP_CONTEXT_TAG, pub_key_as_bytes.as_slice()].concat();
 		sp_io::crypto::sr25519_sign(key_type, self, pop_statement.as_slice())
 	}
 

substrate/primitives/application-crypto/src/traits.rs

@@ -100,8 +100,14 @@ pub trait RuntimePublic: Sized {
 	/// Verify that the given signature matches the given message using this public key.
 	fn verify<M: AsRef<[u8]>>(&self, msg: &M, signature: &Self::Signature) -> bool;
 
+	/// Generate proof of possession of the corresponding public key
+	///
+	/// The private key will be requested from the keystore using the given key type.
+	///
+	/// Returns the proof of possession as a signature type or `None` if there is an error.
 	fn generate_pop(&mut self, key_type: KeyTypeId) -> Option<Self::Signature>;
 
+	/// Verify that the given pop is valid for the corresponding public key.
 	fn verify_pop(&self, pop: &Self::Signature) -> bool;
 
 	/// Returns `Self` as raw vec.
@@ -137,8 +143,14 @@ pub trait RuntimeAppPublic: Sized {
 	/// Verify that the given signature matches the given message using this public key.
 	fn verify<M: AsRef<[u8]>>(&self, msg: &M, signature: &Self::Signature) -> bool;
 
+	/// Generate proof of possession of the corresponding public key
+	///
+	/// The private key will be requested from the keystore using the given key type.
+	///
+	/// Returns the proof of possession as a signature type or `None` if there is an error.
 	fn generate_pop(&mut self) -> Option<Self::Signature>;
 
+	/// Verify that the given pop is valid for the corresponding public key.
 	fn verify_pop(&self, pop: &Self::Signature) -> bool;
 
 	/// Returns `Self` as raw vec.

substrate/primitives/core/src/crypto.rs

@@ -977,14 +977,13 @@ where
 	///   {{Theory}} and {{Applications}} of {{Cryptographic Techniques} (pp. 228–245). : Springer.
 	fn generate_proof_of_possession(&mut self) -> Self::Signature {
 		let pub_key_as_bytes = self.public().to_raw_vec();
-		let pop_context_tag: &[u8] = b"POP_";
-		let pop_statement = [pop_context_tag, pub_key_as_bytes.as_slice()].concat();
+		let pop_statement = [POP_CONTEXT_TAG, pub_key_as_bytes.as_slice()].concat();
 		self.sign(pop_statement.as_slice())
 	}
 }
 
 ///The context which attached to pop message to attest its purpose
-const POP_CONTEXT_TAG: &[u8; 4] = b"POP_";
+pub const POP_CONTEXT_TAG: &[u8; 4] = b"POP_";
 
 /// Pair which is able to generate proof of possession. While you don't need a keypair
 /// to verify a proof of possession (you only need a public key) we constrain on Pair
@@ -1008,6 +1007,8 @@ where
 	}
 }
 
+/// Marker trait to identify whether the scheme is aggregatable thus changing
+/// the implementation of the scheme parts such as Proof Of Possession or other specifics.
 pub trait NonAggregatable {}
 
 impl<T> ProofOfPossessionVerifier for T

substrate/primitives/core/src/ecdsa.rs

@@ -19,12 +19,10 @@
 
 use crate::crypto::{
 	CryptoType, CryptoTypeId, DeriveError, DeriveJunction, Pair as TraitPair,
-	ProofOfPossessionGenerator, ProofOfPossessionVerifier, PublicBytes, SecretStringError,
+	PublicBytes, SecretStringError,
 	SignatureBytes, NonAggregatable
 };
 
-use sp_crypto_pubkeycrypto_proc_macro::ProofOfPossession;
-
 #[cfg(not(feature = "std"))]
 use alloc::vec::Vec;
 #[cfg(not(feature = "std"))]

substrate/primitives/core/src/ed25519.rs

@@ -18,11 +18,10 @@
 //! Simple Ed25519 API.
 
 use crate::crypto::{
-	ByteArray, CryptoType, CryptoTypeId, DeriveError, DeriveJunction, NonAggregatable, Pair as TraitPair, ProofOfPossessionGenerator, ProofOfPossessionVerifier, PublicBytes, SecretStringError, SignatureBytes
+	ByteArray, CryptoType, CryptoTypeId, DeriveError, DeriveJunction, NonAggregatable, Pair as TraitPair, PublicBytes, SecretStringError, SignatureBytes
 };
 
 use ed25519_zebra::{SigningKey, VerificationKey};
-use sp_crypto_pubkeycrypto_proc_macro::ProofOfPossession;
 
 use alloc::vec::Vec;
 

substrate/primitives/core/src/paired_crypto.rs

@@ -140,8 +140,11 @@ pub mod ecdsa_bls381 {
 	/// An identifier used to match public keys against BLS12-381 keys
 	pub const CRYPTO_ID: CryptoTypeId = CryptoTypeId(*b"ecb8");
 
+	/// Identifier used for knowing aggregate public key size.
 	pub const PUBLIC_KEY_LEN: usize =
 		ecdsa::PUBLIC_KEY_SERIALIZED_SIZE + bls381::PUBLIC_KEY_SERIALIZED_SIZE;
+
+	/// Identifier used for knowing aggregate public key size.
 	pub const SIGNATURE_LEN: usize =
 		ecdsa::SIGNATURE_SERIALIZED_SIZE + bls381::SIGNATURE_SERIALIZED_SIZE;
 

substrate/primitives/core/src/sr25519.rs

@@ -23,10 +23,8 @@
 #[cfg(feature = "serde")]
 use crate::crypto::Ss58Codec;
 use crate::crypto::{
-	CryptoBytes, DeriveError, DeriveJunction, Pair as TraitPair, ProofOfPossessionGenerator,
-	ProofOfPossessionVerifier, SecretStringError, NonAggregatable
+	CryptoBytes, DeriveError, DeriveJunction, Pair as TraitPair, SecretStringError, NonAggregatable
 };
-use sp_crypto_pubkeycrypto_proc_macro::ProofOfPossession;
 
 use alloc::vec::Vec;
 #[cfg(feature = "full_crypto")]

substrate/primitives/io/src/lib.rs

@@ -86,7 +86,7 @@ use tracing;
 
 #[cfg(feature = "std")]
 use sp_core::{
-	crypto::{Pair, ProofOfPossessionGenerator},
+	crypto::Pair,
 	hexdisplay::HexDisplay,
 	offchain::{OffchainDbExt, OffchainWorkerExt, TransactionPoolExt},
 	storage::ChildInfo,
@@ -1219,6 +1219,10 @@ pub trait Crypto {
 			.expect("`bls381_generate` failed")
 	}
 
+	/// Generate a 'bls12-381' Proof Of Possession for the corresponding public key.
+	///
+	/// Returns the Proof Of Possession as an option of the ['bls381::Signature'] type
+	/// or 'None' if an error occurs.
 	#[cfg(feature = "bls-experimental")]
 	fn bls381_generate_pop(&mut self, id: KeyTypeId, pub_key: &bls381::Public) -> Option<bls381::Signature> {
 		self.extension::<KeystoreExt>()

substrate/primitives/keystore/src/lib.rs

@@ -322,6 +322,14 @@ pub trait Keystore: Send + Sync {
 		msg: &[u8],
 	) -> Result<Option<bls381::Signature>, Error>;
 
+	/// Generate a bls381 Proof of Possession for a given public key
+	///
+	/// Receives ['KeyTypeId'] and a ['bls381::Public'] key to be able to map
+	/// them to a private key that exists in the keystore
+	///
+	/// Returns an ['bls381::Signature'] or 'None' in case the given 'key_type'
+	/// and 'public' combination doesn't exist in the keystore.
+	/// An 'Err' will be returned if generating the proof of possession itself failed.
 	#[cfg(feature = "bls-experimental")]
 	fn bls381_generate_pop(
 		&self,

substrate/primitives/runtime/src/testing.rs

@@ -135,6 +135,14 @@ impl sp_application_crypto::RuntimeAppPublic for UintAuthorityId {
 		traits::Verify::verify(signature, msg.as_ref(), &self.0)
 	}
 
+	fn generate_pop(&mut self) -> Option<Self::Signature> {
+		None
+	}
+
+	fn verify_pop(&self, pop: &Self::Signature) -> bool {
+		false
+	}
+
 	fn to_raw_vec(&self) -> Vec<u8> {
 		AsRef::<[u8]>::as_ref(self).to_vec()
 	}