Skip to content

Closes #1103 #1249 - #1358

Merged
greatest0fallt1me merged 3 commits into
CalloraOrg:mainfrom
mansur-codes:feat/1103-1249-sweep-cap-settlement-docs
Oct 1, 2026
Merged

greatest0fallt1me merged 3 commits into
CalloraOrg:mainfrom
mansur-codes:feat/1103-1249-sweep-cap-settlement-docs

Conversation

@mansur-codes

Copy link
Copy Markdown
Contributor

fix(vault, settlement): cap timelocked sweep at surplus & document settlement caller matrix (#1103, #1249)

Closes #1103
Closes #1249

Description

This PR resolves Issue #1103 and Issue #1249 by capping timelocked vault sweep operations to unallocated surplus tokens and documenting the caller authorization matrix and security model for the settlement contract.


Key Changes

1. Timelocked Sweep Surplus Cap (Issue #1103)

  • Surplus Calculation: Updated propose_sweep and execute_sweep in CalloraVault to compute surplus as:
    surplus = on_ledger_token_balance - tracked_balance
  • Pre-Flight Validation:
    • propose_sweep rejects sweep amounts exceeding current surplus with VaultError::InsufficientBalance.
    • execute_sweep validates that surplus remains >= proposal.amount at execution time.
    • Failures leave DataKey::Balance, timelock proposals, and cooldown state completely unmodified.
  • Unit Tests: Added 4 unit tests in contracts/vault/src/test_value_conservation.rs:
    1. propose_sweep_fails_when_amount_exceeds_current_surplus
    2. execute_sweep_fails_when_surplus_drops_below_amount_after_proposal
    3. successful_sweep_leaves_balance_untouched
    4. withdrawal_between_proposal_and_execution_specifically

2. Settlement Caller Matrix & Security Docs (Issue #1249)

  • Access Control Matrix: Added a complete entrypoint authorization matrix detailing allowed callers and security rationale for all 30 public functions in docs/ACCESS_CONTROL.md.
  • Dual-Caller Security Notice: Documented the dual-caller access pattern for receive_payment and batch_receive_payment (accessible by both Vault and Admin), including operational guidance for operator key sizing and threshold protections.
  • Rustdoc Enhancements: Added rustdoc comments and markdown cross-references on require_authorized_caller and force_credit_developer in contracts/settlement/src/lib.rs.

Verification & Testing

  • cargo test -p callora-vault: All 158 tests passed (111 unit tests + 47 error stability tests).
  • cargo clippy --package callora-vault --all-targets -- -D warnings: Passed cleanly with zero warnings.
  • cargo fmt --package callora-vault --package callora-settlement -- --check: Passed with zero formatting diffs.

@drips-wave

drips-wave Bot commented Sep 30, 2026

Copy link
Copy Markdown

@mansur-codes 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

greatest0fallt1me and others added 2 commits October 1, 2026 15:12
# Conflicts:
#	contracts/distribute/src/lib.rs
#	contracts/distribute/tests/auth_snap.rs
#	contracts/errors/src/test.rs
#	contracts/validators/src/migrate.rs
#	contracts/vault/src/lib.rs
#	contracts/vault/src/test_value_conservation.rs
#	contracts/vault/src/views.rs
…ccept a vault rotation)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@greatest0fallt1me
greatest0fallt1me merged commit 2730f2d into CalloraOrg:main Oct 1, 2026
1 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify settlement caller authorization model Cap timelocked sweep execution at surplus above tracked balance

2 participants