fix(contract): issues 816-819 — pause expiry getter, day-index cap, t…

[talktosam2003]

Close #816
Close #817
close #818
close #819

feat(contract): API expansion, day-index safety caps, SAC token validation, and typed errors (#816, #817, #818, #819)

Title

feat(contract): implement pause expiry API, merchant day cap, SAC token validation, and typed errors

---

📌 Summary & Context

This pull request resolves four contract-level stability, state integrity, and developer-experience issues (#816, #817, #818, and #819).

Together, these changes:

1. Expose missing on-chain pause metadata to off-chain keepers and clients.
2. Prevent unbounded storage growth for high-volume merchant analytics.
3. Fail early on invalid token inputs during subscription setup to prevent corrupt/unusable state.
4. Convert remaining string-panic paths into deterministic, typed ContractError variants for robust client-side handling.

---

🛠 Detailed Breakdown of Changes

1. Issue #816 — Pause Expiry Read API & Event Consistency

• Public View Function: Added pub fn get_pause_expiry(env: Env, user: Address) -> Option<u64> in lib.rs, which delegates directly to storage::get_pause_expiry. As a read-only view, it requires no authentication.
• State Representation:
  • pause() writes u64::MAX to represent an indefinite pause.
  • pause_until(expiry) writes the specific Unix timestamp.
  • The getter returns Some(u64) for both states and None when active.
• Auto-Resume Audit: Confirmed that both charge() and batch_charge() paths cleanly erase PauseExpiry from storage and emit subscription_auto_resumed events when charging past an expired pause window.

2. Issue #817 — Max Merchant Revenue Day-Index Size Cap

• Constant & Documentation: Defined MAX_MERCHANT_REVENUE_DAY_INDEX_SIZE = 365 in merchant_stats.rs. Included inline documentation explaining that a 1-year daily index bounds storage pressure and requires operators to utilize existing prune_merchant_revenue_days APIs.
• Append Guard: Enforced the index cap inside increment_revenue_with_daily. Attempting to append a new day beyond 365 returns ContractError::MerchantDayIndexFull (Error Code 41).
• Update Granularity: Updating an existing day’s revenue bucket (is_new_day == false) bypasses the check, ensuring operational continuity even when the index array is full.
• Error Definition: Registered MerchantDayIndexFull = 41 in errors.rs.

3. Issue #818 — Token Address & SAC Interface Validation

• Validation Pipeline: Implemented require_valid_token_address() in validation.rs featuring a two-layer validation strategy:
  1. Address Type Check: Performs an XDR byte-7 discriminant check to reject standard Account addresses upfront with ContractError::InvalidTokenAddress (Error Code 12).
  2. Interface Probe: Executes a lightweight token::Client::new(env, addr).decimals() host call to verify Stellar Asset Contract (SAC) compliance without blowing CPU limits.
• Subscription Protection: Wired the helper into subscribe_inner prior to state updates, guaranteeing no orphaned or corrupt Subscription storage rows are written if validation fails.

4. Issue #819 — Typed ContractError Conversion for Core Modules

• Panic Elimination: Removed all raw panic! and .expect() calls across admin.rs, fee.rs, grace.rs, upgrade.rs, and their wrapper sites in lib.rs and storage.rs.
• Error Register: Added NoPendingAdmin = 42 to errors.rs.
• Converted Sites Inventory:

Target File	Function Call Site	Legacy Error Mechanism	Converted ContractError
admin.rs	accept_admin	.expect("no pending admin")	ContractError::NoPendingAdmin (42)
storage.rs	get_admin	.expect("admin not set")	ContractError::NotInitialized (7)
grace.rs	propose_grace_period	assert!(…, "grace period too large")	ContractError::AmountExceedsMaximum (15)
lib.rs	set_min_interval	assert!(…, "min interval must be positive")	ContractError::IntervalMustBePositive (3)
lib.rs	set_initial_admin	panic!("admin already set")	ContractError::AlreadyInitialized (1)

---

🧪 Testing & Validation

All acceptance criteria have been verified against local cargo test suites.

Summary of Added/Updated Unit Tests

• Pause Expiry (Issue 020: Add get_pause_expiry read API and event consistency for pause_until auto-resume #816): 9 tests covering None output, timestamp verification, clearing on manual resume, clearing on single/batch auto-resume charges, event assertion checks, and premature charge prevention before expiry.
• Day Index Cap (Issue 021: Enforce a max MerchantRevenueDayIndex size with typed overflow error #817): 3 storage-seeded unit tests asserting cap-1 success, cap+1 failure returning error #41, and successful same-day revenue updates at max capacity.
• SAC Token Validation (Issue 022: Validate token contract address and SAC interface on subscribe #818): 4 tests verifying valid SAC subscriptions, multi-token setups, rejection of non-SAC contract addresses, and zero state mutation on failure.
• Typed Errors (Issue 023: Convert string panic/expect failures in admin, fee, grace, and upgrade modules to ContractError #819): 8 tests covering unproposed commits, invalid intervals (0), oversized grace periods, and two-step happy path executions. Deleted 8 obsolete string-panic snapshot files.

Execution Commands

# Run issue-specific test sub-suites
cargo test pause_until
cargo test merchant
cargo test token
cargo test admin fee grace upgrade

# Verify no remaining string panics on modified modules
rg 'panic!|expect\(' contract/src/admin.rs contract/src/fee.rs contract/src/grace.rs contract/src/upgrade.rs

[drips-wave]

@talktosam2003 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits