fix: audit scope counts, redeploy guide, and pause guards (#487, #488, #491, #492)

[Joeloo1]

Summary

This PR addresses and resolves four distinct issues across documentation, operational upgrade procedures, and contract security/pause behavior:

1. Audit Scope Line Counts Correction (Closes SECURITY.md audit scope line counts are significantly understated #487)
2. Upgrade Guide Option C Deployment Overwrite Handling (Closes Upgrade guide Option C suggests deploy.sh which refuses to run if deployment file exists #488)
3. Emergency Pause Enforcement on enroll_checked (Closes enroll_checked is pub and bypasses require_not_paused, allowing enrollment during emergency pause #491)
4. Allow revoke_delegation During Emergency Pause (Closes revoke_delegation is blocked during pause, preventing learners from revoking malicious delegates #492)

---

Detailed Changes

1. Update Audit Scope in SECURITY.md (Closes #487)

• Problem: The Audit Scope section in SECURITY.md significantly understated the line counts (roughly half of actual values) and omitted several contract source files (such as events.rs in credential-nft and progress-tracker).
• Solution: Recalculated exact line counts across all source files in each contract:
  • learn-token (lib.rs, storage.rs, events.rs): ~5,230 lines (actual: 5,227)
  • credential-nft (lib.rs, mint.rs, verify.rs, metadata.rs, xcall.rs, events.rs): ~2,660 lines (actual: 2,663)
  • progress-tracker (lib.rs, types.rs, rewards.rs, events.rs): ~5,050 lines (actual: 5,049)
  • shared (constants.rs, lib.rs): ~100 lines (actual: 96)
  • Total: ~13,040 lines (actual: 13,035)

2. Document Deployment File Backup/Removal for Option C (Closes #488)

• Problem: In docs/upgrade-guide.md, Option C (and Nuclear Redeployment) instructed running ./scripts/deploy.sh <network>. However, scripts/deploy.sh contains an intentional safety guard (lines 62–66) that aborts if deployments-<network>.json already exists, causing operators to hit an unexpected error without guidance during time-sensitive recovery.
• Solution:
  • Added a note explaining the deploy.sh guard and its safety rationale.
  • Added explicit commands to back up (mv deployments-testnet.json deployments-testnet.backup.$(date +%s).json) or remove the deployment file before re-running deploy.sh.
  • Updated the "Complete Redeployment (Nuclear Option)" procedure to include the same prerequisite step.

3. Ensure enroll_checked Respects Contract Pause State (Closes #491)

• Problem: enroll_checked is a public entrypoint on progress-tracker. Direct callers bypassing enroll must not be able to mutate contract state when the contract is paused.
• Solution:
  • Verified and ensured Self::require_not_paused(&env) executes at the very beginning of enroll_checked in contracts/progress-tracker/src/lib.rs.
  • Added unit test test_enroll_checked_panics_when_paused (#[should_panic(expected = "contract is paused")]) in contracts/progress-tracker/src/lib.rs.
  • Added integration test assertions in tests/integration/emergency_pause_flow.rs verifying that try_enroll_checked reverts during pause and succeeds upon unpause.

4. Allow revoke_delegation During Emergency Pause (Closes #492)

• Problem: revoke_delegation previously called Self::require_not_paused(&env). When a contract is emergency-paused (e.g. if a delegate is compromised), learners were unable to revoke their delegation to prevent malicious actions once unpaused. Safety-reducing operations should be frozen, but safety-enhancing/risk-reducing operations (revoking access) should remain accessible.
• Solution:
  • Removed Self::require_not_paused(&env) from revoke_delegation in contracts/progress-tracker/src/lib.rs.
  • Kept Self::require_not_paused(&env) in delegate_progress so new delegations remain blocked during pause.
  • Added unit test test_revoke_delegation_succeeds_when_paused in contracts/progress-tracker/src/lib.rs and in tests/unit/progress_tests.rs.
  • Added unit test test_delegate_progress_panics_when_paused in contracts/progress-tracker/src/lib.rs verifying delegate_progress remains strictly blocked during pause.

---

Verification & Testing

• cargo check --workspace --all-targets passed cleanly with 0 errors.
• cargo test -p progress-tracker test_enroll_checked_panics_when_paused -> PASSED
• cargo test -p progress-tracker test_delegate_progress_panics_when_paused -> PASSED
• cargo test -p progress-tracker test_revoke_delegation_succeeds_when_paused -> PASSED
• cargo test --test progress_tests (107 tests) -> ALL 107 PASSED
• cargo test --test emergency_pause_flow (4 tests) -> ALL 4 PASSED

[drips-wave]

@Joeloo1 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