Implement Revenue Threshold Filtering

docs/concentration-reporting-integrity.md

@@ -0,0 +1,32 @@
+# Concentration Reporting Integrity
+
+This document outlines the architecture, assumptions, and validation rules for the Concentration Reporting Integrity feature in the Revora smart contracts.
+
+## Overview
+The concentration reporting feature provides a verifiable and tamper-resistant mechanism for issuers to define, report, and optionally enforce maximum holder concentration limits (in basis points) on their offerings. 
+
+## Key Integrity Guarantees
+
+### 1. Verification and Audit Trail
+Every successful call to `report_concentration` unconditionally emits an `EVENT_CONCENTRATION_REPORTED` (`"conc_rep"`) event. This creates an immutable, on-chain timeline of concentration metrics that indexers and off-chain clients can use to independently verify historical concentration levels.
+
+### 2. Bounds Validation
+All concentration-related values are strictly enforced against a maximum logical bound of `10,000` basis points (100%).
+- `set_concentration_limit`: The `max_bps` parameter must be `<= 10,000`.
+- `report_concentration`: The `concentration_bps` parameter must be `<= 10,000`.
+Any value exceeding this limit results in a `RevoraError::InvalidShareBps`.
+
+### 3. Emergency Controls (Security & Pausing)
+Both `set_concentration_limit` and `report_concentration` incorporate the global pause check (`require_not_paused()`). This ensures that in the event of a security emergency, administrators can freeze all state-mutating actions related to offering concentration, preventing malicious issuers from altering definitions or bypassing automated enforcement.
+
+### 4. Authorization Boundaries
+Only the current authenticated issuer of an offering can set limits or report concentrations. This is enforced via `issuer.require_auth()` and validated against the `OfferingIssuer` storage key.
+
+## Failure Modes and Handling
+1. **Unregistered Offering / Unauthorized Caller:** `set_concentration_limit` and `report_concentration` will fail (`LimitReached` / `OfferingNotFound`) if the token is not recognized as an offering or if the caller does not match the securely stored `current_issuer`.
+2. **Invalid Metrics:** Exceeding `10,000` bps safely panics the transaction via `RevoraError::InvalidShareBps` before state modification.
+3. **Globally Paused State:** Any attempt to manipulate concentration limits while the contract is globally paused will abort the transaction.
+4. **Limit Breaches:** If enforcement is active (`enforce = true`), reporting revenue will fail automatically if the stored concentration exceeds `max_bps`. An explicitly captured warning event (`"conc_warn"`) is emitted immediately when a limit is exceeded via `report_concentration`.
+
+## Conclusion
+This robust validation and event-logging framework ensures that all claims regarding offering concentration are cryptographically auditable, tamper-resistant against out-of-bounds manipulation, and inherently secure under emergency control mechanisms.

docs/revenue-threshold-filtering.md

@@ -0,0 +1,47 @@
+# Revenue Threshold Filtering
+
+The Revenue Threshold Filtering feature ensures that revenue reports below a specified minimum amount do not trigger on-chain distribution logic. This protects the protocol from "dust" reports that are computationally expensive to process relative to the value distributed.
+
+## Objective
+
+Prevent inefficient distributions by enforcing a per-offering minimum revenue requirement.
+
+## Implementation Details
+
+### Core Logic
+
+The filtering occurs in both the `report_revenue` and `do_deposit_revenue` functions in `src/lib.rs`. 
+
+#### Reporting Filtering
+In `report_revenue`, if the `amount` is strictly less than the `MinRevenueThreshold`:
+- An `EVENT_REV_BELOW_THRESHOLD` (`rev_below`) is emitted for off-chain tracking.
+- The function returns early with `Ok(())`.
+- No state changes occur (no update to `RevenueReports`, `AuditSummary`, or `RevenueIndex`).
+
+#### Funding Filtering
+In `do_deposit_revenue`, if the `amount` is strictly less than the `MinRevenueThreshold`:
+- The transaction fails with `RevoraError::InvalidAmount`.
+- This ensures that issuers cannot fund dust periods, protecting holders from inefficient claim operations.
+
+### Configuration
+
+Issuers can set their threshold using:
+- `set_min_revenue_threshold(issuer, namespace, token, min_amount)`
+- Setting `min_amount` to `0` effectively disables filtering.
+
+## Security Assumptions
+
+- **Issuer & Admin Control**: The offering issuer and the platform admin are authorized to set or change the threshold. This is enforced via `caller.require_auth()` and an internal check against the current issuer and platform admin addresses.
+- **Integrity**: Boundary conditions (exactly matching threshold) are permitted to pass, ensuring no legitimate "at-limit" reports are blocked.
+
+## Failure & Abuse Scenarios
+
+- **Unauthorized Modification**: Attempting to set a threshold by a non-issuer will result in a panic or host error.
+- **Dust Flooding**: While filtering prevents on-chain distribution, multiple "below-threshold" reports still consume some network resources to emit events. Systemic protection against event-only spam should be handled by charging Soroban's standard resource fees.
+
+## Boundary Conditions
+
+- `amount == threshold`: Allowed.
+- `amount < threshold`: Filtered.
+- `threshold == 0`: All non-negative reports allowed.
+- `amount < 0`: Rejected by initial validation before threshold check.

package.json

@@ -0,0 +1,10 @@
+{
+  "name": "revora-contracts",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "$HOME/.cargo/bin/cargo build",
+    "test": "$HOME/.cargo/bin/cargo test",
+    "release": "$HOME/.cargo/bin/cargo build --release"
+  }
+}