chore(documentation): added more inline code documentation

pallets/acurast/common/src/attestation.rs

@@ -33,6 +33,7 @@ fn parse_cert_payload(serialized: &[u8]) -> Result<&[u8], ParseError> {
 
 pub type CertificateId = (Vec<u8>, Vec<u8>);
 
+/// Creates a unique id for a certificate.
 pub fn unique_id(
     issuer: &Name,
     serial_number: &asn1::BigUint,
@@ -46,6 +47,7 @@ pub fn unique_id(
 /// [See docs](https://source.android.com/docs/security/keystore/attestation#tbscertificate-sequence)
 pub const KEY_ATTESTATION_OID: ObjectIdentifier = oid!(1, 3, 6, 1, 4, 1, 11129, 2, 1, 17);
 
+/// Extracts and parses the attestation from the extension field of a X.509 certificate.
 pub fn extract_attestation<'a>(
     extensions: Option<SequenceOf<'a, Extension<'a>>>,
 ) -> Result<KeyDescription<'a>, ValidationError> {

pallets/acurast/common/src/attestation/error.rs

@@ -8,23 +8,41 @@ use scale_info::TypeInfo;
 #[derive(RuntimeDebug, Encode, Decode, TypeInfo, Clone, PartialEq, Eq)]
 
 pub enum ValidationError {
+    /// Error occured while parsing the key description
     ParseKeyDescription,
+    /// The certificate chain is too short
     ChainTooShort,
+    /// The certificate chain is too long
     ChainTooLong,
+    /// Generic decode error
     DecodeError,
+    /// Generic parse error
     ParseError,
+    /// The root certificate is not trusted
     UntrustedRoot,
+    /// Missing extension field in certificate
     ExtensionMissing,
+    /// Error occured when parsing the extension field
     ParseExtension,
+    /// Attestation version is not supported
     UnsupportedAttestationVersion,
+    /// Error occured while parsing the P256 public key
     ParseP256PublicKey,
+    /// Error occured while parsing the P384 public key
     ParseP384PublicKey,
+    /// ECDSA Algorithm missing
     MissingECDSAAlgorithmTyp,
+    /// Public key missing
     MissingPublicKey,
+    /// Signature has an invalid encoding
     InvalidSignatureEncoding,
+    /// Signature is invalid
     InvalidSignature,
+    /// Signature Algorithm is not supported
     UnsupportedSignatureAlgorithm,
+    /// Public Key Algorithm is not supported
     UnsupportedPublicKeyAlgorithm,
+    /// Issuer is invalid
     InvalidIssuer,
     /// Specified signature algorithms do not match.
     ///

pallets/acurast/common/src/types.rs

@@ -181,6 +181,7 @@ impl Schedule {
     }
 }
 
+/// Implements the [Iterator] trait so that scheduled jobs in a [Schedule] can be iterated.
 pub struct ScheduleIter {
     delayed_start_time: u64,
     delayed_end_time: u64,

pallets/acurast/src/lib.rs

@@ -291,7 +291,10 @@ pub mod pallet {
             Ok(().into())
         }
 
-        #[pallet::weight(< T as Config >::WeightInfo::register())]
+        /// Updates the certificate revocation list by adding or removing a revoked certificate serial number. Attestations signed
+        /// by a revoked certificate will not be considered valid anymore. The `RevocationListUpdateBarrier` configured in [Config] can be used to
+        /// customize who can execute this action.
+        #[pallet::weight(<T as Config>::WeightInfo::register())]
         #[pallet::call_index(6)]
         pub fn update_certificate_revocation_list(
             origin: OriginFor<T>,

pallets/acurast/src/traits.rs

@@ -7,6 +7,7 @@ use crate::{
     Script,
 };
 
+/// Allows to customize who can perform an update to the certificate revocation list.
 pub trait RevocationListUpdateBarrier<T: Config> {
     fn can_update_revocation_list(
         origin: &T::AccountId,
@@ -23,6 +24,7 @@ impl<T: Config> RevocationListUpdateBarrier<T> for () {
     }
 }
 
+/// Allows to customize the kind of key attestations that are accepted.
 pub trait KeyAttestationBarrier<T: Config> {
     fn accept_attestation_for_origin(origin: &T::AccountId, attestation: &Attestation) -> bool;
 }
@@ -41,6 +43,7 @@ pub trait WeightInfo {
     fn update_certificate_revocation_list() -> Weight;
 }
 
+/// Allows to hook additional logic for various job related extrinsics.
 pub trait JobHooks<T: Config> {
     fn register_hook(
         who: &<T as frame_system::Config>::AccountId,

pallets/acurast/src/utils.rs

@@ -11,6 +11,7 @@ use crate::{
     SerialNumber, StoredAttestation, StoredRevokedCertificate, ValidatingCertIds,
 };
 
+/// Validates and returns an [Attestation] from the provided chain.
 pub fn validate_and_extract_attestation<T: Config>(
     source: &T::AccountId,
     attestation_chain: &AttestationChain,
@@ -55,6 +56,7 @@ pub fn validate_and_extract_attestation<T: Config>(
     })
 }
 
+/// Ensures that the provided account id has a valid (not expired and not revoked) key attestation.
 pub fn ensure_source_verified<T: Config>(source: &T::AccountId) -> Result<(), Error<T>> {
     let attestation =
         <StoredAttestation<T>>::get(source).ok_or(Error::<T>::FulfillSourceNotVerified)?;
@@ -63,6 +65,7 @@ pub fn ensure_source_verified<T: Config>(source: &T::AccountId) -> Result<(), Er
     Ok(())
 }
 
+/// Ensures the attestation is not expired.
 pub(crate) fn ensure_not_expired<T: Config>(attestation: &Attestation) -> Result<(), Error<T>> {
     let now: u64 = T::UnixTime::now()
         .as_millis()
@@ -90,6 +93,7 @@ pub(crate) fn ensure_not_expired<T: Config>(attestation: &Attestation) -> Result
     Ok(())
 }
 
+/// Ensures the attestation is not signed by a revoked certificate.
 pub(crate) fn ensure_not_revoked<T: Config>(attestation: &Attestation) -> Result<(), Error<T>> {
     let ids = &attestation.cert_ids;
     for id in ids {
@@ -100,6 +104,7 @@ pub(crate) fn ensure_not_revoked<T: Config>(attestation: &Attestation) -> Result
     Ok(())
 }
 
+/// Ensures the provided public key correponds to the provided account id.
 fn ensure_valid_public_key_for_source<T: Config>(
     source: &T::AccountId,
     public_key: &PublicKey,

pallets/fee-manager/src/lib.rs

@@ -57,6 +57,7 @@ pub mod pallet {
 
     #[pallet::call]
     impl<T: Config<I>, I: 'static> Pallet<T, I> {
+        /// Updates the fee percentage. Can only be called by a privileged/root account.
         #[pallet::call_index(0)]
         #[pallet::weight(Weight::from_ref_time(10_000).saturating_add(T::DbWeight::get().reads_writes(1, 2)))]
         pub fn update_fee_percentage(origin: OriginFor<T>, fee: Percent) -> DispatchResult {
@@ -72,6 +73,7 @@ pub mod pallet {
 }
 
 impl<T: Config<I>, I: 'static> Pallet<T, I> {
+    /// Sets the fee percentage in storage.
     pub fn set_fee_percentage(fee: Percent) -> (u16, u64) {
         let new_version = <Version<T, I>>::mutate(|version| {
             version.add_assign(1);

pallets/marketplace/src/lib.rs

@@ -301,6 +301,7 @@ pub mod pallet {
             Ok(().into())
         }
 
+        /// Proposes processors to match with a job. The match fails if it conflicts with the processor's schedule.
         #[pallet::call_index(2)]
         #[pallet::weight(< T as Config >::WeightInfo::propose_matching())]
         pub fn propose_matching(
@@ -321,6 +322,7 @@ pub mod pallet {
             Ok(().into())
         }
 
+        /// Acknowledges a matched job. It fails if the origin is not the account that was matched for the job.
         #[pallet::call_index(3)]
         #[pallet::weight(< T as Config >::WeightInfo::acknowledge_match())]
         pub fn acknowledge_match(
@@ -573,6 +575,7 @@ pub mod pallet {
     }
 
     impl<T: Config> Pallet<T> {
+        /// Checks if a Processor - Job match is possible and returns the job reward.
         fn process_matching<'a>(
             matching: impl IntoIterator<Item = &'a Match<T::AccountId>>,
         ) -> Result<RewardFor<T>, DispatchError> {
@@ -804,6 +807,7 @@ pub mod pallet {
             <StoredMatches<T>>::iter_prefix_values(&source).any(|_| true)
         }
 
+        /// Checks of a new job schedule fits with the existing schedule for a processor.
         fn fits_schedule(
             source: &T::AccountId,
             schedule: &Schedule,
@@ -852,6 +856,7 @@ pub mod pallet {
             Ok(().into())
         }
 
+        /// Calculates the total reward amount.
         fn total_reward_amount(
             registration: &JobRegistrationFor<T>,
         ) -> Result<T::AssetAmount, Error<T>> {
@@ -871,6 +876,7 @@ pub mod pallet {
                 .ok_or(Error::<T>::CalculationOverflow)?)
         }
 
+        /// Calculates the fee per job execution.
         fn fee_per_execution(
             registration: &JobRegistrationFor<T>,
             pricing: &PricingVariantFor<T>,
@@ -890,6 +896,7 @@ pub mod pallet {
                 .ok_or(Error::<T>::CalculationOverflow)?)
         }
 
+        /// Returns the current timestamp.
         fn now() -> Result<u64, DispatchError> {
             Ok(<T as pallet_acurast::Config>::UnixTime::now()
                 .as_millis()

pallets/marketplace/src/payments.rs

@@ -10,6 +10,7 @@ use frame_support::{
     Never, PalletId, Parameter,
 };
 
+/// Asset barrier that allows to customize which asset can be used as reward.
 pub trait AssetBarrier<Asset> {
     fn can_use_asset(asset: &Asset) -> bool;
 }
@@ -22,13 +23,17 @@ impl<Asset> AssetBarrier<Asset> for () {
 
 pub type RewardFor<T> = <<T as Config>::RewardManager as RewardManager<T>>::Reward;
 
+/// Trait representing the reward for the execution of a job.
 pub trait Reward {
     type AssetId;
     type AssetAmount;
     type Error;
 
+    /// Creates new reward with given amount.
     fn with_amount(&mut self, amount: Self::AssetAmount) -> Result<&Self, Self::Error>;
+    /// Returns the reward asset id.
     fn try_get_asset_id(&self) -> Result<Self::AssetId, Self::Error>;
+    /// Returns the reward amount.
     fn try_get_amount(&self) -> Result<Self::AssetAmount, Self::Error>;
 }
 
@@ -50,6 +55,7 @@ impl Reward for () {
     }
 }
 
+/// Trait used to manage lock up and payments of rewards.
 pub trait RewardManager<T: frame_system::Config> {
     type Reward: Parameter + Member + Reward;
 

pallets/marketplace/src/utils.rs

@@ -2,6 +2,7 @@ use crate::Config;
 use pallet_acurast::JobRegistrationFor;
 use sp_std::prelude::*;
 
+/// Checks if a consumer is whitelisted/
 pub(crate) fn is_consumer_whitelisted<T: Config>(
     consumer: &T::AccountId,
     allowed_consumers: &Option<Vec<T::AccountId>>,
@@ -16,6 +17,7 @@ pub(crate) fn is_consumer_whitelisted<T: Config>(
         .unwrap_or(true)
 }
 
+/// Checks if a source/processor is whitelisted
 pub fn is_source_whitelisted<T: Config>(
     source: &T::AccountId,
     registration: &JobRegistrationFor<T>,