docs: complete rustdoc coverage for fees, mock-oracle, oracle and identity message APIs

contracts/analytics/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(clippy::new_without_default)]

contracts/bridge/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(

contracts/compliance_registry/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::needless_borrows_for_generic_args,

contracts/crowdfunding/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::arithmetic_side_effects,

contracts/database/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(clippy::new_without_default)]

contracts/dex/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(

contracts/factory/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use ink::prelude::string::String;

contracts/fees/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 
@@ -412,18 +413,27 @@ mod propchain_fees {
             Ok(())
         }
 
+        /// Returns the premium listing auction with the given id, if it exists.
         #[ink(message)]
         pub fn get_auction(&self, auction_id: u64) -> Option<PremiumAuction> {
             self.auctions.get(auction_id)
         }
 
+        /// Returns the total number of premium listing auctions created so far.
+        ///
+        /// Auction ids are assigned sequentially starting at 1, so this value is
+        /// also the highest allocated auction id.
         #[ink(message)]
         pub fn get_auction_count(&self) -> u64 {
             self.auction_count
         }
 
         // ========== Incentives and distribution ==========
 
+        /// Registers `account` as a fee validator eligible for reward distribution.
+        ///
+        /// Caller requirement: admin only (`FeeError::Unauthorized` otherwise).
+        /// Idempotent: registering an already-active validator is a no-op.
         #[ink(message)]
         pub fn add_validator(&mut self, account: AccountId) -> Result<(), FeeError> {
             self.ensure_admin()?;
@@ -435,6 +445,11 @@ mod propchain_fees {
             Ok(())
         }
 
+        /// Removes `account` from the fee validator set.
+        ///
+        /// Caller requirement: admin only (`FeeError::Unauthorized` otherwise).
+        /// Removing an address that was never registered succeeds silently.
+        /// Any pending rewards for the removed validator remain claimable.
         #[ink(message)]
         pub fn remove_validator(&mut self, account: AccountId) -> Result<(), FeeError> {
             self.ensure_admin()?;
@@ -443,6 +458,12 @@ mod propchain_fees {
             Ok(())
         }
 
+        /// Sets how collected fees are split between validators and the treasury.
+        ///
+        /// Both shares are expressed in basis points (1 bps = 0.01%, denominator
+        /// 10_000). The two shares must not sum to more than 10_000 bps, otherwise
+        /// `FeeError::InvalidConfig` is returned and nothing changes.
+        /// Caller requirement: admin only (`FeeError::Unauthorized` otherwise).
         #[ink(message)]
         pub fn set_distribution_rates(
             &mut self,
@@ -524,6 +545,11 @@ mod propchain_fees {
             Ok(amount)
         }
 
+        /// Returns the reward amount currently claimable by `account`.
+        ///
+        /// Balances accrue via `distribute_fees` (validator share) and are
+        /// claimed with `claim_rewards`; accounts with no pending rewards
+        /// report 0.
         #[ink(message)]
         pub fn pending_reward(&self, account: AccountId) -> u128 {
             self.pending_rewards.get(account).unwrap_or(0)
@@ -614,16 +640,30 @@ mod propchain_fees {
             rec
         }
 
+        /// Returns the admin account configured at deployment.
+        ///
+        /// The admin is the sole caller allowed to change fee parameters,
+        /// validator membership, and distribution rates.
         #[ink(message)]
         pub fn admin(&self) -> AccountId {
             self.admin
         }
 
+        /// Returns the fixed `FeeConfig` (base/min/max fee in planck units)
+        /// captured at construction time.
+        ///
+        /// This is the immutable baseline; live parameters are reflected in
+        /// `get_fee_report` instead.
         #[ink(message)]
         pub fn default_config(&self) -> FeeConfig {
             self.default_config.clone()
         }
 
+        /// Returns the current unallocated treasury balance available for
+        /// distribution.
+        ///
+        /// Funds enter via `record_fee_collected` and leave when the admin
+        /// calls `distribute_fees`.
         #[ink(message)]
         pub fn fee_treasury(&self) -> u128 {
             self.fee_treasury
@@ -695,6 +735,11 @@ mod propchain_fees {
     }
 
     impl DynamicFeeProvider for FeeManager {
+        /// Recommended fee for `operation` under the dynamic fee model.
+        ///
+        /// Delegates to `calculate_fee`, which applies the configured base fee
+        /// (bps), congestion multiplier, and the operation's max-fee cap (bps,
+        /// denominator 10_000 in both cases). Read-only; any caller may query it.
         #[ink(message)]
         fn get_recommended_fee(&self, operation: FeeOperation) -> u128 {
             self.calculate_fee(operation)

contracts/fractional/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::needless_borrows_for_generic_args,

contracts/gdpr/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::needless_borrows_for_generic_args,

contracts/governance/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::too_many_arguments,

contracts/identity/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(clippy::needless_borrows_for_generic_args)]
@@ -1661,6 +1662,11 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Revokes an account's verifier authorization.
+        ///
+        /// Admin only (`IdentityError::Unauthorized` otherwise). Marks the
+        /// verifier as unauthorized in the mapping; revoking an address that
+        /// was never authorized succeeds silently.
         #[ink(message)]
         pub fn remove_authorized_verifier(
             &mut self,
@@ -1673,6 +1679,11 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Adds a cross-chain id to the supported-chains list.
+        ///
+        /// Admin only (`IdentityError::Unauthorized` otherwise). Adding a
+        /// chain that is already listed is a no-op; the registry is seeded
+        /// with chains 1–5 at construction.
         #[ink(message)]
         pub fn add_supported_chain(&mut self, chain_id: ChainId) -> Result<(), IdentityError> {
             if self.env().caller() != self.admin {
@@ -1684,6 +1695,8 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Returns every chain id currently accepted for cross-chain
+        /// identity verification.
         #[ink(message)]
         pub fn get_supported_chains(&self) -> Vec<ChainId> {
             self.supported_chains.clone()
@@ -1755,6 +1768,12 @@ pub mod propchain_identity {
 
         // ===== Verification Provider Methods - Issue #283 =====
 
+        /// Registers an external KYC verification provider.
+        ///
+        /// Admin only (`IdentityError::Unauthorized` otherwise). The provider
+        /// starts active with the given name (fixed 64-byte field),
+        /// `ProviderType`, and the tiers it may verify; a `provider_registered`
+        /// audit entry is recorded.
         #[ink(message)]
         pub fn register_verification_provider(
             &mut self,
@@ -1790,6 +1809,11 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Deactivates a verification provider so it can no longer receive
+        /// or complete KYC requests.
+        ///
+        /// Admin only (`IdentityError::Unauthorized` for non-admins);
+        /// unknown providers fail with `IdentityError::IdentityNotFound`.
         #[ink(message)]
         pub fn deactivate_provider(&mut self, provider_id: AccountId) -> Result<(), IdentityError> {
             if self.env().caller() != self.admin {
@@ -1807,6 +1831,8 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Returns the registration record for a verification provider,
+        /// or `None` if the id was never registered.
         #[ink(message)]
         pub fn get_verification_provider(
             &self,
@@ -1817,6 +1843,13 @@ pub mod propchain_identity {
 
         // ===== KYC Tier Verification - Issue #282 & #283 =====
 
+        /// Opens a KYC verification request with a provider for the caller.
+        ///
+        /// The provider must exist (`IdentityError::IdentityNotFound`) and be
+        /// active, and must support `requested_tier` (both failures return
+        /// `IdentityError::VerificationFailed`). Returns a sequential request
+        /// id starting at 1; the request starts in `Pending` status and an
+        /// audit entry is recorded.
         #[ink(message)]
         pub fn request_kyc_verification(
             &mut self,
@@ -1870,6 +1903,14 @@ pub mod propchain_identity {
             Ok(request_id)
         }
 
+        /// Completes a KYC verification request (approve or reject).
+        ///
+        /// Callable only by the provider the request was filed with
+        /// (`IdentityError::Unauthorized` otherwise); unknown request ids fail
+        /// with `IdentityError::IdentityNotFound` and non-pending requests
+        /// with `IdentityError::VerificationFailed`. On approval the
+        /// applicant's KYC tier is set to the requested tier; `result_metadata`
+        /// is stored verbatim on the request.
         #[ink(message)]
         pub fn complete_kyc_verification(
             &mut self,
@@ -1964,16 +2005,23 @@ pub mod propchain_identity {
             Ok(())
         }
 
+        /// Returns the KYC tier granted to `account`, or `None` if the
+        /// account has never been verified.
         #[ink(message)]
         pub fn get_user_kyc_tier(&self, account: AccountId) -> Option<KycTier> {
             self.user_kyc_tiers.get(&account)
         }
 
+        /// Returns the privilege limits configured for `tier` (max
+        /// transaction value, daily transaction count, trading permission),
+        /// or `None` if the tier is not configured.
         #[ink(message)]
         pub fn get_kyc_tier_privileges(&self, tier: KycTier) -> Option<KycTierPrivileges> {
             self.kyc_tier_privileges.get(&tier)
         }
 
+        /// Returns the full KYC verification request with the given id,
+        /// or `None` if it does not exist.
         #[ink(message)]
         pub fn get_provider_verification_request(
             &self,
@@ -1982,6 +2030,14 @@ pub mod propchain_identity {
             self.provider_verification_requests.get(&request_id)
         }
 
+        /// Checks whether `account`'s KYC tier permits a transaction of
+        /// `transaction_value`.
+        ///
+        /// Accounts without a tier are treated as `Tier0Unverified`. Returns
+        /// `Ok(true)` when the value is within the tier's max transaction
+        /// value and the daily limit is not exhausted, `Ok(false)` when a
+        /// limit is exceeded, and `IdentityError::IdentityNotFound` if the
+        /// tier has no configured privileges.
         #[ink(message)]
         pub fn check_tier_privileges(
             &self,

contracts/insurance/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::arithmetic_side_effects,

contracts/ipfs-metadata/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 

contracts/lending/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std, no_main)]
 #![allow(
     clippy::arithmetic_side_effects,

contracts/lib/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(clippy::needless_borrows_for_generic_args)]

contracts/metadata/src/lib.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::clone_on_copy)] // fires inside ink! generated storage code
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(unexpected_cfgs)]
 #![allow(clippy::new_without_default)]