From cd7a1001f5a519527051c6b000c957fd064a99c9 Mon Sep 17 00:00:00 2001 From: Mike Godenzi Date: Fri, 27 Jan 2023 14:53:14 +0100 Subject: [PATCH 1/4] chore(documentation): added more inline code documentation --- pallets/acurast/common/src/attestation.rs | 2 ++ .../acurast/common/src/attestation/error.rs | 18 ++++++++++++++++++ pallets/acurast/common/src/types.rs | 1 + pallets/acurast/src/lib.rs | 5 ++++- pallets/acurast/src/traits.rs | 3 +++ pallets/acurast/src/utils.rs | 5 +++++ pallets/fee-manager/src/lib.rs | 2 ++ pallets/marketplace/src/lib.rs | 7 +++++++ pallets/marketplace/src/payments.rs | 6 ++++++ pallets/marketplace/src/utils.rs | 2 ++ 10 files changed, 50 insertions(+), 1 deletion(-) diff --git a/pallets/acurast/common/src/attestation.rs b/pallets/acurast/common/src/attestation.rs index 7032d528..c83a45c8 100644 --- a/pallets/acurast/common/src/attestation.rs +++ b/pallets/acurast/common/src/attestation.rs @@ -33,6 +33,7 @@ fn parse_cert_payload(serialized: &[u8]) -> Result<&[u8], ParseError> { pub type CertificateId = (Vec, Vec); +/// Createds 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>>, ) -> Result, ValidationError> { diff --git a/pallets/acurast/common/src/attestation/error.rs b/pallets/acurast/common/src/attestation/error.rs index bcf800ed..e19192cb 100644 --- a/pallets/acurast/common/src/attestation/error.rs +++ b/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. /// diff --git a/pallets/acurast/common/src/types.rs b/pallets/acurast/common/src/types.rs index 66430ad7..9baadba5 100644 --- a/pallets/acurast/common/src/types.rs +++ b/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, diff --git a/pallets/acurast/src/lib.rs b/pallets/acurast/src/lib.rs index 5abc27d2..fc4e5c77 100644 --- a/pallets/acurast/src/lib.rs +++ b/pallets/acurast/src/lib.rs @@ -291,7 +291,10 @@ pub mod pallet { Ok(().into()) } - #[pallet::weight(< T as Config >::WeightInfo::register())] + /// Updates the certificate recovation list by adding or removing a revocked certificate serial number. Attestations signed + /// by a revocked certificate will not be considered valid anymore. The `RevocationListUpdateBarrier` configured in [Config] can be used to + /// customize who can execute this action. + #[pallet::weight(::WeightInfo::register())] #[pallet::call_index(6)] pub fn update_certificate_revocation_list( origin: OriginFor, diff --git a/pallets/acurast/src/traits.rs b/pallets/acurast/src/traits.rs index 02dd22d0..2a118568 100644 --- a/pallets/acurast/src/traits.rs +++ b/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 { fn can_update_revocation_list( origin: &T::AccountId, @@ -23,6 +24,7 @@ impl RevocationListUpdateBarrier for () { } } +/// Allows to customize the kind of key attestations that are accepted. pub trait KeyAttestationBarrier { 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 { fn register_hook( who: &::AccountId, diff --git a/pallets/acurast/src/utils.rs b/pallets/acurast/src/utils.rs index 493fead0..7d031c88 100644 --- a/pallets/acurast/src/utils.rs +++ b/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( source: &T::AccountId, attestation_chain: &AttestationChain, @@ -55,6 +56,7 @@ pub fn validate_and_extract_attestation( }) } +/// Ensures that the provided account id has a valid (not expired and not revoked) key attestation. pub fn ensure_source_verified(source: &T::AccountId) -> Result<(), Error> { let attestation = >::get(source).ok_or(Error::::FulfillSourceNotVerified)?; @@ -63,6 +65,7 @@ pub fn ensure_source_verified(source: &T::AccountId) -> Result<(), Er Ok(()) } +/// Ensures the attestation is not expired. pub(crate) fn ensure_not_expired(attestation: &Attestation) -> Result<(), Error> { let now: u64 = T::UnixTime::now() .as_millis() @@ -90,6 +93,7 @@ pub(crate) fn ensure_not_expired(attestation: &Attestation) -> Result Ok(()) } +/// Ensures the attestation is not signed by a revoked certificate. pub(crate) fn ensure_not_revoked(attestation: &Attestation) -> Result<(), Error> { let ids = &attestation.cert_ids; for id in ids { @@ -100,6 +104,7 @@ pub(crate) fn ensure_not_revoked(attestation: &Attestation) -> Result Ok(()) } +/// Ensures the provided public key correponds to the provided account id. fn ensure_valid_public_key_for_source( source: &T::AccountId, public_key: &PublicKey, diff --git a/pallets/fee-manager/src/lib.rs b/pallets/fee-manager/src/lib.rs index 5d631cad..64df758c 100644 --- a/pallets/fee-manager/src/lib.rs +++ b/pallets/fee-manager/src/lib.rs @@ -57,6 +57,7 @@ pub mod pallet { #[pallet::call] impl, I: 'static> Pallet { + /// 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, fee: Percent) -> DispatchResult { @@ -72,6 +73,7 @@ pub mod pallet { } impl, I: 'static> Pallet { + /// Sets the fee percentage in storage. pub fn set_fee_percentage(fee: Percent) -> (u16, u64) { let new_version = >::mutate(|version| { version.add_assign(1); diff --git a/pallets/marketplace/src/lib.rs b/pallets/marketplace/src/lib.rs index cbd3b4b2..edccadd5 100644 --- a/pallets/marketplace/src/lib.rs +++ b/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 Pallet { + /// Checks if a Processor - Job match is possible and returns the job reward. fn process_matching<'a>( matching: impl IntoIterator>, ) -> Result, DispatchError> { @@ -804,6 +807,7 @@ pub mod pallet { >::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, ) -> Result> { @@ -871,6 +876,7 @@ pub mod pallet { .ok_or(Error::::CalculationOverflow)?) } + /// Calculates the fee per job execution. fn fee_per_execution( registration: &JobRegistrationFor, pricing: &PricingVariantFor, @@ -890,6 +896,7 @@ pub mod pallet { .ok_or(Error::::CalculationOverflow)?) } + /// Returns the current timestamp. fn now() -> Result { Ok(::UnixTime::now() .as_millis() diff --git a/pallets/marketplace/src/payments.rs b/pallets/marketplace/src/payments.rs index aa08db16..cfde8178 100644 --- a/pallets/marketplace/src/payments.rs +++ b/pallets/marketplace/src/payments.rs @@ -10,6 +10,7 @@ use frame_support::{ Never, PalletId, Parameter, }; +/// Asset barrier that allows to customize the what asset can be used as reward. pub trait AssetBarrier { fn can_use_asset(asset: &Asset) -> bool; } @@ -22,13 +23,17 @@ impl AssetBarrier for () { pub type RewardFor = <::RewardManager as RewardManager>::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; + /// Returns the reward amount. fn try_get_amount(&self) -> Result; } @@ -50,6 +55,7 @@ impl Reward for () { } } +/// Trait used to manage lock up and payments of rewards. pub trait RewardManager { type Reward: Parameter + Member + Reward; diff --git a/pallets/marketplace/src/utils.rs b/pallets/marketplace/src/utils.rs index 3309ec03..c2ced8d4 100644 --- a/pallets/marketplace/src/utils.rs +++ b/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( consumer: &T::AccountId, allowed_consumers: &Option>, @@ -16,6 +17,7 @@ pub(crate) fn is_consumer_whitelisted( .unwrap_or(true) } +/// Checks if a source/processor is whitelisted pub fn is_source_whitelisted( source: &T::AccountId, registration: &JobRegistrationFor, From 7aa138219fea8cc610d6623b5f8528a7eb417e99 Mon Sep 17 00:00:00 2001 From: Mike Godenzi Date: Fri, 27 Jan 2023 15:01:54 +0100 Subject: [PATCH 2/4] Update pallets/acurast/common/src/attestation.rs Co-authored-by: Rodrigo Quelhas <22591718+RomarQ@users.noreply.github.com> --- pallets/acurast/common/src/attestation.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pallets/acurast/common/src/attestation.rs b/pallets/acurast/common/src/attestation.rs index c83a45c8..6d790591 100644 --- a/pallets/acurast/common/src/attestation.rs +++ b/pallets/acurast/common/src/attestation.rs @@ -33,7 +33,7 @@ fn parse_cert_payload(serialized: &[u8]) -> Result<&[u8], ParseError> { pub type CertificateId = (Vec, Vec); -/// Createds a unique id for a certificate. +/// Creates a unique id for a certificate. pub fn unique_id( issuer: &Name, serial_number: &asn1::BigUint, From f382676a013267887ce2302d2c753d8b7ff59288 Mon Sep 17 00:00:00 2001 From: Mike Godenzi Date: Fri, 27 Jan 2023 15:02:11 +0100 Subject: [PATCH 3/4] Update pallets/acurast/src/lib.rs Co-authored-by: Rodrigo Quelhas <22591718+RomarQ@users.noreply.github.com> --- pallets/acurast/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pallets/acurast/src/lib.rs b/pallets/acurast/src/lib.rs index fc4e5c77..f93d8fb8 100644 --- a/pallets/acurast/src/lib.rs +++ b/pallets/acurast/src/lib.rs @@ -291,8 +291,8 @@ pub mod pallet { Ok(().into()) } - /// Updates the certificate recovation list by adding or removing a revocked certificate serial number. Attestations signed - /// by a revocked certificate will not be considered valid anymore. The `RevocationListUpdateBarrier` configured in [Config] can be used to + /// 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(::WeightInfo::register())] #[pallet::call_index(6)] From 12edea69c2885b7110212e7e58f7fe780eff9caf Mon Sep 17 00:00:00 2001 From: Mike Godenzi Date: Fri, 27 Jan 2023 15:02:22 +0100 Subject: [PATCH 4/4] Update pallets/marketplace/src/payments.rs Co-authored-by: Rodrigo Quelhas <22591718+RomarQ@users.noreply.github.com> --- pallets/marketplace/src/payments.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pallets/marketplace/src/payments.rs b/pallets/marketplace/src/payments.rs index cfde8178..5e773a7b 100644 --- a/pallets/marketplace/src/payments.rs +++ b/pallets/marketplace/src/payments.rs @@ -10,7 +10,7 @@ use frame_support::{ Never, PalletId, Parameter, }; -/// Asset barrier that allows to customize the what asset can be used as reward. +/// Asset barrier that allows to customize which asset can be used as reward. pub trait AssetBarrier { fn can_use_asset(asset: &Asset) -> bool; }