Merge main into PR 1045

Author: nanaf6203-bit

AUDIT_LOG.md

@@ -1,5 +1,5 @@
 # 🛡️ Automated Security & Mutation Audit Log
-Generated on: Mon Aug 24 03:07:26 UTC 2026
+Generated on: Tue Aug 25 03:02:28 UTC 2026
 ---
 ## 📦 Dependency License & Advisory Checks (cargo-deny)
 ```text

Cargo.lock

@@ -7,7 +7,7 @@ use ink::prelude::string::String;
 use ink::prelude::vec::Vec;
 
 #[ink::contract]
-mod propchain_analytics {
+pub mod propchain_analytics {
     use super::*;
 
     /// Market metrics representing aggregated property data.

contracts/analytics/src/lib.rs

@@ -31,7 +31,7 @@ use ink::prelude::vec::Vec;
 use ink::storage::Mapping;
 
 #[ink::contract]
-mod propchain_database {
+pub mod propchain_database {
     use super::*;
 
     // Data types extracted to types.rs (Issue #101)
@@ -575,5 +575,7 @@ mod propchain_database {
     // UNIT TESTS
     // ========================================================================
 
-    // Unit tests extracted to tests.rs (Issue #101)
+    // Include unit tests (extracted to tests.rs per Issue #101)
+    #[cfg(test)]
+    include!("tests.rs");
 }

contracts/database/src/lib.rs

@@ -17,7 +17,7 @@ use propchain_traits::{DynamicFeeProvider, FeeOperation};
 // every test after every include isn't worth the structural churn, so
 // suppress the lint here.
 #[allow(clippy::items_after_test_module)]
-mod propchain_fees {
+pub mod propchain_fees {
     use super::*;
 
     /// Basis points denominator (10000 = 100%)
@@ -413,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()?;
@@ -436,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()?;
@@ -444,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,
@@ -525,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)
@@ -615,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
@@ -696,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/fees/src/lib.rs

@@ -1662,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,
@@ -1674,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 {
@@ -1685,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()
@@ -1756,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,
@@ -1791,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 {
@@ -1808,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,
@@ -1818,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,
@@ -1871,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,
@@ -1965,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,
@@ -1983,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,