Merge pull request #443 from raizo07/test/bills-archive-batch-gas-regressions

test: add gas regression suite for bill archive and batch ops

Author: Baskarayelu

benchmarks/README.md

@@ -62,6 +62,12 @@ Each benchmark outputs JSON with the following structure:
 }
 ```
 
+For CI parsing, gas suites may also emit lines prefixed with:
+- `GAS_BENCH_RESULT `: machine-readable benchmark result with baseline/threshold metadata
+- `cpu regression ...` / `mem regression ...`: assertion failures when thresholds are exceeded
+
+This keeps `--nocapture` logs easy to scrape in CI while preserving normal Rust test output.
+
 ## Remittance Split Schedule Operations
 
 The remittance split contract includes comprehensive benchmarks for schedule lifecycle operations:
@@ -91,6 +97,20 @@ All benchmarks include security validations:
 3. **Input Validation**: Tests with valid parameters to ensure proper validation
 4. **Edge Cases**: Covers boundary conditions and error scenarios
 
+## Bill Payments Archive and Batch Suite
+
+`bill_payments/tests/gas_bench.rs` includes dedicated regression coverage for:
+- `archive_paid_bills/120_paid_1_unpaid_preserved`
+- `restore_bill/single_archived_owner_restore`
+- `bulk_cleanup_bills/mixed_age_20_of_30_deleted`
+- `batch_pay_bills/mixed_batch_50_partial_success`
+
+Security assumptions validated in these benches:
+- Archive and cleanup are maintenance operations over paid/archived data only
+- Restore is owner-only
+- Batch pay preserves owner isolation and deterministic partial success
+- Oversized batches are rejected (`BatchTooLarge`)
+
 ## Regression Detection
 
 The system automatically detects regressions by comparing current measurements against baselines:

benchmarks/baseline.json

@@ -102,6 +102,38 @@
     "cpu": 1251484,
     "mem": 250040,
     "description": "Query schedules in worst-case scenario with 50 schedules"
+  },
+  {
+    "contract": "bill_payments",
+    "method": "archive_paid_bills",
+    "scenario": "120_paid_1_unpaid_preserved",
+    "cpu": 640000,
+    "mem": 150000,
+    "description": "Archive 120 paid bills while preserving one unpaid bill"
+  },
+  {
+    "contract": "bill_payments",
+    "method": "restore_bill",
+    "scenario": "single_archived_owner_restore",
+    "cpu": 90000,
+    "mem": 20000,
+    "description": "Restore one archived bill with owner-only authorization checks"
+  },
+  {
+    "contract": "bill_payments",
+    "method": "bulk_cleanup_bills",
+    "scenario": "mixed_age_20_of_30_deleted",
+    "cpu": 250000,
+    "mem": 70000,
+    "description": "Cleanup deletes only older archived entries in a mixed-age archive set"
+  },
+  {
+    "contract": "bill_payments",
+    "method": "batch_pay_bills",
+    "scenario": "mixed_batch_50_partial_success",
+    "cpu": 900000,
+    "mem": 140000,
+    "description": "Batch pay with valid, already-paid, unauthorized, and missing bill IDs"
   }
   ,
   {

benchmarks/thresholds.json

@@ -37,6 +37,26 @@
       "mem_percent": 10,
       "description": "Higher CPU threshold for aggregation operations"
     },
+    "archive_paid_bills": {
+      "cpu_percent": 15,
+      "mem_percent": 12,
+      "description": "Archive scans bill storage and writes archive records"
+    },
+    "restore_bill": {
+      "cpu_percent": 12,
+      "mem_percent": 10,
+      "description": "Single-record restore with owner authorization checks"
+    },
+    "bulk_cleanup_bills": {
+      "cpu_percent": 15,
+      "mem_percent": 12,
+      "description": "Cleanup iterates archived records and removes matched entries"
+    },
+    "batch_pay_bills": {
+      "cpu_percent": 15,
+      "mem_percent": 12,
+      "description": "Mixed batch processing with per-item validation and partial success"
+    },
     "get_all_goals": {
       "cpu_percent": 12,
       "mem_percent": 12,

bill_payments/src/lib.rs

@@ -1085,6 +1085,14 @@ impl BillPayments {
         Ok(())
     }
 
+    /// @notice Archive paid bills with `paid_at < before_timestamp`.
+    /// @dev Permissionless maintenance operation. Caller must authenticate, but does not need to
+    /// own each archived bill. Only paid bills with a historical payment timestamp are moved from
+    /// active storage into archival storage.
+    /// @param caller Authenticated caller executing archive maintenance.
+    /// @param before_timestamp Exclusive upper bound for `paid_at`.
+    /// @return Number of bills archived in this call.
+    /// @security Unpaid bills are never archived; owner data is preserved on archived records.
     pub fn archive_paid_bills(
         env: Env,
         caller: Address,
@@ -1216,6 +1224,12 @@ impl BillPayments {
         Ok(())
     }
 
+    /// @notice Permanently delete archived bills with `archived_at < before_timestamp`.
+    /// @dev Permissionless maintenance operation for archive compaction.
+    /// @param caller Authenticated caller executing cleanup.
+    /// @param before_timestamp Exclusive upper bound for `archived_at`.
+    /// @return Number of archived records removed.
+    /// @security Only archived data is touched; active bills are unaffected.
     pub fn bulk_cleanup_bills(
         env: Env,
         caller: Address,
@@ -1258,25 +1272,16 @@ impl BillPayments {
         Ok(deleted_count)
     }
 
-    /// Pay multiple bills in a single batch.
+    /// @notice Pay multiple bills in one call.
     ///
-    /// # Semantics: Partial Success
-    /// This function implements deterministic partial result reporting. If a bill in the batch
-    /// is invalid (e.g., not found, unauthorized, or already paid), it will be skipped,
-    /// and an error event will be emitted. Other valid bills in the same batch will still be processed.
+    /// @dev Partial-success semantics are deterministic: invalid bill IDs are skipped and reported,
+    /// while valid IDs continue processing.
     ///
-    /// # Arguments
-    /// * `env` - The Soroban environment
-    /// * `caller` - Address of the bill owner (must authorize)
-    /// * `bill_ids` - Vector of bill IDs to pay
-    ///
-    /// # Returns
-    /// The number of successfully paid bills.
-    ///
-    /// # Events
-    /// - `paid`: Emitted for each successful payment.
-    /// - `bill_pay_failed`: Emitted for each failed payment with (bill_id, error_code).
-    /// - `batch_pay_summary`: Emitted at the end with (success_count, failure_count).
+    /// @param caller Authenticated owner attempting the batch payment.
+    /// @param bill_ids Candidate bill IDs to process.
+    /// @return Number of successfully paid bills.
+    /// @security Cross-owner payments are rejected per item; oversized batches are rejected
+    /// before iteration.
     pub fn batch_pay_bills(env: Env, caller: Address, bill_ids: Vec<u32>) -> Result<u32, Error> {
         caller.require_auth();
         Self::require_not_paused(&env, pause_functions::PAY_BILL)?;