Merge pull request #1066 from abdoolyaro/docs/957-960-ink-message-doc-comments

docs: add doc comments to all ink! messages in sanctions, version-reg…

Author: nanaf6203-bit

contracts/fractional/src/lib.rs

@@ -348,16 +348,41 @@ pub mod fractional {
     }
 
     impl Fractional {
+        /// Records the last-known price per share for `token_id`.
+        ///
+        /// Not payable. Open to any caller -- this message performs no
+        /// access-control or ownership check, and unconditionally
+        /// overwrites any previously stored price. Never fails; there is no
+        /// `Result` return. The stored value feeds `redeem_shares`'s payout
+        /// calculation and is used as the fallback price in
+        /// `aggregate_portfolio` when a caller does not supply its own
+        /// price for a token.
         #[ink(message)]
         pub fn set_last_price(&mut self, token_id: u64, price_per_share: u128) {
             self.last_prices.insert(token_id, &price_per_share);
         }
 
+        /// Returns the last-known price per share for `token_id`, as most
+        /// recently set by `set_last_price`.
+        ///
+        /// Open to any caller. Returns `None` if no price has ever been set
+        /// for `token_id`.
         #[ink(message)]
         pub fn get_last_price(&self, token_id: u64) -> Option<u128> {
             self.last_prices.get(token_id)
         }
 
+        /// Computes the total value of a caller-supplied list of holdings, a
+        /// read-only convenience calculation that does not touch this
+        /// contract's own balance records.
+        ///
+        /// Open to any caller. For each `PortfolioItem`, uses
+        /// `item.price_per_share` if it is nonzero, otherwise falls back to
+        /// this contract's stored `last_prices` for `item.token_id` (`0` if
+        /// none is stored). Returns the summed `total_value` along with a
+        /// per-item `(token_id, shares, price_used)` breakdown in
+        /// `positions`, in the same order as the input `items`. All
+        /// arithmetic saturates rather than overflowing. Never fails.
         #[ink(message)]
         pub fn aggregate_portfolio(&self, items: Vec<PortfolioItem>) -> PortfolioAggregation {
             let mut total: u128 = 0;
@@ -378,6 +403,15 @@ pub mod fractional {
             }
         }
 
+        /// Summarizes caller-supplied dividend and proceeds records into
+        /// total dividends, total proceeds, and a transaction count.
+        ///
+        /// Open to any caller. This is a pure calculation over the `dividends`
+        /// and `proceeds` arguments; it does not read or write any of this
+        /// contract's own storage, so it reflects only what the caller
+        /// passes in, not this contract's actual transaction history.
+        /// `transactions` is the combined length of both input lists. All
+        /// arithmetic saturates rather than overflowing. Never fails.
         #[ink(message)]
         pub fn summarize_tax(
             &self,

contracts/prediction-market/src/lib.rs

@@ -243,13 +243,37 @@ pub mod propchain_prediction_market {
             }
         }
 
+        /// Sets the oracle account address for this contract. Admin-only.
+        ///
+        /// Not payable. Note: this address is currently informational only
+        /// for the manual-resolution markets (`create_market` /
+        /// `resolve_market`), which are resolved directly by the admin, not
+        /// by checking this value. It is used as the required caller for
+        /// `submit_oracle_data` on oracle-driven markets.
+        ///
+        /// # Errors
+        /// - `Error::Unauthorized` if the caller is not the contract admin.
         #[ink(message)]
         pub fn set_oracle(&mut self, oracle: AccountId) -> Result<(), Error> {
             self.ensure_admin()?;
             self.oracle_address = Some(oracle);
             Ok(())
         }
 
+        /// Creates a new manual-resolution prediction market for a property
+        /// metric and returns its `market_id`. Admin-only.
+        ///
+        /// Not payable. The market starts `Active` with zero stakes on both
+        /// sides. Once `resolution_time` (a block timestamp) has passed, the
+        /// admin resolves the market with `resolve_market`, comparing the
+        /// submitted value against `target_value`. Emits `MarketCreated`.
+        ///
+        /// This is the manual-resolution counterpart to
+        /// `create_oracle_market`; the two market kinds are tracked in
+        /// separate id spaces and are not interchangeable in other messages.
+        ///
+        /// # Errors
+        /// - `Error::Unauthorized` if the caller is not the contract admin.
         #[ink(message)]
         pub fn create_market(
             &mut self,
@@ -286,6 +310,23 @@ pub mod propchain_prediction_market {
             Ok(market_id)
         }
 
+        /// Stakes the transferred value on `direction` (Long or Short) for a
+        /// manual-resolution market. Payable; the transferred value is the
+        /// stake amount.
+        ///
+        /// Open to any caller. Repeated calls for the same `market_id` by the
+        /// same caller add to their existing stake, provided the direction
+        /// matches; this contract does not support hedging both directions
+        /// on the same market from one account. Emits `PredictionStaked`.
+        ///
+        /// # Errors
+        /// - `Error::InvalidAmount` if no value was transferred, or if the
+        ///   caller already holds a stake on this market in the opposite
+        ///   direction.
+        /// - `Error::MarketNotFound` if `market_id` does not exist.
+        /// - `Error::MarketNotActive` if the market is not `Active`, or if
+        ///   its `resolution_time` has already passed (staking closes at
+        ///   resolution time, before `resolve_market` is even called).
         #[ink(message, payable)]
         pub fn stake_prediction(
             &mut self,
@@ -343,6 +384,29 @@ pub mod propchain_prediction_market {
             Ok(())
         }
 
+        /// Resolves a manual-resolution market by admin-submitted
+        /// `resolved_value`, deciding the winning direction. Admin-only.
+        ///
+        /// Not payable. `Long` wins if `resolved_value >= target_value`,
+        /// otherwise `Short` wins. Can only be called once per market, and
+        /// only after `resolution_time` has passed. Emits `MarketResolved`.
+        ///
+        /// # Screening / trust note
+        /// This value is currently supplied directly by the admin account,
+        /// not verified against `oracle_address` or any external data feed.
+        /// Oracle-driven settlement for this market type is tracked
+        /// separately; today's guarantee is only that the admin attests to
+        /// `resolved_value`. Oracle-driven markets created via
+        /// `create_oracle_market` are resolved differently, via
+        /// `submit_oracle_data`.
+        ///
+        /// # Errors
+        /// - `Error::Unauthorized` if the caller is not the contract admin.
+        /// - `Error::MarketNotFound` if `market_id` does not exist.
+        /// - `Error::MarketAlreadyResolved` if the market is not `Active`
+        ///   (already resolved or cancelled).
+        /// - `Error::MarketNotReadyForResolution` if `resolution_time` has
+        ///   not yet passed.
         #[ink(message)]
         pub fn resolve_market(
             &mut self,
@@ -380,6 +444,31 @@ pub mod propchain_prediction_market {
             Ok(())
         }
 
+        /// Claims the caller's payout from a resolved manual-resolution
+        /// market, transferring it to the caller. Not payable.
+        ///
+        /// Open to any caller who holds a stake on `market_id`. A winning
+        /// stake's payout is
+        /// `stake + stake * losing_pool / winning_pool`, minus a protocol
+        /// fee of `fee_bips` (in basis points, set at construction). A
+        /// losing stake cannot claim and instead records unsuccessful-
+        /// prediction reputation for the caller (see `get_user_reputation`);
+        /// a winning claim records successful-prediction reputation. Each
+        /// stake can be claimed at most once. Guarded against reentrancy.
+        /// Emits `RewardClaimed` on success.
+        ///
+        /// # Errors
+        /// - `Error::MarketNotFound` if `market_id` does not exist.
+        /// - `Error::MarketNotActive` if the market has not been resolved
+        ///   yet.
+        /// - `Error::StakeNotFound` if the caller has no stake on this
+        ///   market.
+        /// - `Error::RewardAlreadyClaimed` if the caller already claimed
+        ///   this stake.
+        /// - `Error::LoserCannotClaim` if the caller's stake was on the
+        ///   losing direction.
+        /// - `Error::TransferFailed` if the payout transfer fails.
+        /// - `Error::ReentrantCall` if called reentrantly.
         #[ink(message)]
         pub fn claim_reward(&mut self, market_id: u64) -> Result<(), Error> {
             non_reentrant!(self, {
@@ -438,6 +527,15 @@ pub mod propchain_prediction_market {
             })
         }
 
+        /// Returns `user`'s prediction reputation: total predictions made,
+        /// how many resolved in the user's favor, and an accuracy score out
+        /// of 10000 (e.g. `7500` = 75%).
+        ///
+        /// Open to any caller. Reputation is only updated by
+        /// `claim_reward` (manual-resolution markets), not by
+        /// `claim_winnings` (oracle markets). A user who has never claimed a
+        /// manual-resolution reward gets a zeroed-out `UserReputation`
+        /// rather than an error.
         #[ink(message)]
         pub fn get_user_reputation(&self, user: AccountId) -> UserReputation {
             self.reputations.get(&user).unwrap_or(UserReputation {
@@ -447,11 +545,28 @@ pub mod propchain_prediction_market {
             })
         }
 
+        /// Returns the manual-resolution market info for `market_id`, if it
+        /// exists.
+        ///
+        /// Open to any caller. Returns `None` if `market_id` was never
+        /// created via `create_market`. For oracle-driven markets, use
+        /// `get_oracle_market` instead -- the two id spaces are separate.
         #[ink(message)]
         pub fn get_market(&self, market_id: u64) -> Option<PredictionMarketInfo> {
             self.markets.get(&market_id)
         }
 
+        /// Records a backtest-accuracy attestation for a market and emits
+        /// `BacktestValidated`. Admin-only. Not payable.
+        ///
+        /// This message does not verify `historical_accuracy` or
+        /// `model_version` against anything (no proof check, no stored
+        /// mapping) -- it only accepts the admin's submitted values and
+        /// emits the event for off-chain consumption. It does not affect
+        /// market resolution, staking, or payouts.
+        ///
+        /// # Errors
+        /// - `Error::Unauthorized` if the caller is not the contract admin.
         #[ink(message)]
         pub fn submit_backtest_data(
             &mut self,

contracts/sanctions/lib.rs

@@ -260,13 +260,28 @@ pub mod sanctions_screening {
             Ok(())
         }
 
+        /// Returns the sanctioned-entity record for `entity_id`, if one exists.
+        ///
+        /// Open to any caller. Returns `None` if `entity_id` has never been
+        /// registered. The returned record may have `active == false` if the
+        /// entity was later removed via `remove_sanctioned_entity`; callers that
+        /// care about current sanction status should check `active` themselves.
         #[ink(message)]
         pub fn get_sanctioned_entity(&self, entity_id: u64) -> Option<SanctionedEntity> {
             self.sanctioned_entities.get(entity_id)
         }
 
         // ── Admin: Manage sanctioned properties ─────────────────────────────
 
+        /// Adds a property to the sanctions list, keyed by caller-supplied
+        /// `property_id`. Admin-only.
+        ///
+        /// Unlike `add_sanctioned_entity`, `property_id` is not auto-assigned;
+        /// calling this again with the same `property_id` overwrites the
+        /// existing record. Emits `PropertySanctioned`.
+        ///
+        /// # Errors
+        /// - `Error::NotAuthorized` if the caller is not the contract admin.
         #[ink(message)]
         pub fn add_sanctioned_property(
             &mut self,
@@ -294,6 +309,16 @@ pub mod sanctions_screening {
             Ok(())
         }
 
+        /// Deactivates a sanctioned property. Admin-only.
+        ///
+        /// Sets the property's `active` flag to `false`. The record is kept
+        /// (not deleted) so it remains queryable via `get_sanctioned_property`.
+        /// Emits `PropertyCleared`.
+        ///
+        /// # Errors
+        /// - `Error::NotAuthorized` if the caller is not the contract admin.
+        /// - `Error::PropertyNotFound` if no property is registered under
+        ///   `property_id`.
         #[ink(message)]
         pub fn clear_sanctioned_property(&mut self, property_id: u64) -> Result<()> {
             self.ensure_admin()?;
@@ -310,13 +335,49 @@ pub mod sanctions_screening {
             Ok(())
         }
 
+        /// Returns the sanctioned-property record for `property_id`, if one
+        /// exists.
+        ///
+        /// Open to any caller. Returns `None` if `property_id` was never listed.
+        /// The returned record may have `active == false` if it was later
+        /// cleared via `clear_sanctioned_property`; callers that care about
+        /// current sanction status should check `active` themselves.
         #[ink(message)]
         pub fn get_sanctioned_property(&self, property_id: u64) -> Option<SanctionedProperty> {
             self.sanctioned_properties.get(property_id)
         }
 
         // ── Screening ───────────────────────────────────────────────────────
 
+        /// Screens a property (and, optionally, an associated entity) against
+        /// the sanctions lists, and records the outcome. Admin-only.
+        ///
+        /// Checks are evaluated in order and the first match wins:
+        /// 1. If `property_id` is itself an active sanctioned property, the
+        ///    screening fails (`passed = false`) with that property's
+        ///    `sanction_level`, regardless of `entity_id`.
+        /// 2. Otherwise, if `entity_id` is `Some` and refers to an active
+        ///    sanctioned entity whose `jurisdiction_code` matches the one
+        ///    passed in, the screening fails with that entity's
+        ///    `sanction_level`.
+        /// 3. Otherwise the screening passes with `SanctionLevel::None`. This
+        ///    includes the case where `jurisdiction_code` does not match any
+        ///    known jurisdiction: an unrecognized jurisdiction is not itself
+        ///    grounds for failure.
+        ///
+        /// Every call stores a new `ScreeningResult` (auto-incrementing
+        /// `screening_id`), appends it to the property's screening history
+        /// (see `get_property_screenings`), and emits `ScreeningsPerformed`.
+        ///
+        /// # Screening guarantee
+        /// This lookup runs in time proportional to whether `property_id` and
+        /// `entity_id` are present in storage (a `Mapping::get` per check), not
+        /// in constant time.
+        ///
+        /// # Errors
+        /// - `Error::NotAuthorized` if the caller is not the contract admin.
+        /// - `Error::ThresholdExceeded` if the internal screening-id counter
+        ///   has been exhausted (`u64::MAX` screenings recorded).
         #[ink(message)]
         pub fn screen_property(
             &mut self,
@@ -421,11 +482,23 @@ pub mod sanctions_screening {
             self.property_screenings.insert(property_id, &existing);
         }
 
+        /// Returns a single screening result by its `screening_id`, if one
+        /// exists.
+        ///
+        /// Open to any caller. Returns `None` if `screening_id` was never
+        /// recorded (every `screen_property` call produces exactly one).
         #[ink(message)]
         pub fn get_screening_result(&self, screening_id: u64) -> Option<ScreeningResult> {
             self.screening_results.get(screening_id)
         }
 
+        /// Returns the full screening history for a property, in the order
+        /// the screenings were performed.
+        ///
+        /// Open to any caller. Returns an empty `Vec` if `property_id` has
+        /// never been screened. Any screening id recorded against the property
+        /// that can no longer be resolved to a stored result is silently
+        /// skipped rather than causing an error.
         #[ink(message)]
         pub fn get_property_screenings(&self, property_id: u64) -> Vec<ScreeningResult> {
             match self.property_screenings.get(property_id) {
@@ -442,16 +515,40 @@ pub mod sanctions_screening {
             }
         }
 
+        /// Returns whether `property_id` has ever been screened, i.e. whether
+        /// `screen_property` has been called for it at least once.
+        ///
+        /// Open to any caller. This does not indicate pass/fail status, only
+        /// that a screening history exists; use `get_property_screenings` or
+        /// `get_screening_result` to inspect outcomes.
         #[ink(message)]
         pub fn is_property_screened(&self, property_id: u64) -> bool {
             self.property_screenings.get(property_id).is_some()
         }
 
+        /// Returns the account currently authorized to call the admin-only
+        /// messages on this contract (`add_sanctioned_entity`,
+        /// `remove_sanctioned_entity`, `add_sanctioned_property`,
+        /// `clear_sanctioned_property`, `screen_property`,
+        /// `set_screening_threshold`, and `set_max_sanctioned_entities`).
+        ///
+        /// Open to any caller. There is no message to transfer admin rights;
+        /// the admin is fixed to the account that called the constructor.
         #[ink(message)]
         pub fn admin(&self) -> AccountId {
             self.admin
         }
 
+        /// Updates the screening-threshold configuration value (in days).
+        /// Admin-only.
+        ///
+        /// Note: this value is stored and returned by `screening_threshold`,
+        /// but is not currently read anywhere else in this contract, including
+        /// `screen_property` -- there is no re-screening cadence or expiry
+        /// enforced from it today. Emits `SanctionThresholdUpdated`.
+        ///
+        /// # Errors
+        /// - `Error::NotAuthorized` if the caller is not the contract admin.
         #[ink(message)]
         pub fn set_screening_threshold(&mut self, days: u32) -> Result<()> {
             self.ensure_admin()?;
@@ -463,6 +560,11 @@ pub mod sanctions_screening {
             Ok(())
         }
 
+        /// Returns the current screening-threshold configuration value (in
+        /// days), as last set by `set_screening_threshold` or the default of
+        /// 90 set in the constructor.
+        ///
+        /// Open to any caller.
         #[ink(message)]
         pub fn screening_threshold(&self) -> u32 {
             self.screening_threshold_days