feat: Implement payroll execution idempotency and replay protection

[OG-wura]

Close #165

Implement Payroll Execution Idempotency & Replay Protection

Summary

Adds contract-level protections that prevent duplicate payroll execution for the same company, payroll period, commitment batch, and treasury authorization context. Payroll execution is now safe under retries, delayed confirmations, client crashes, and malicious replay attempts.

Changes

contracts/payment_executor/src/lib.rs

• DataKey::BatchExecution(BytesN<32>) — tracks whether a specific batch fingerprint has been executed
• DataKey::BatchExecutionRecords(BytesN<32>) — caches Vec<PaymentRecord> for idempotent returns
• compute_batch_fingerprint() — SHA-256 hash of (company_id, period, employees, amounts, nullifiers) using soroban_sdk::Bytes + env.crypto().sha256()
• execute_batch_payroll() — computes fingerprint upfront; if batch already executed, returns cached records without re-execution (safe idempotent retry); emits BatchExecuted event on first execution
• Tests: test_execute_batch_idempotent_retry, test_different_batches_have_distinct_identities

contracts/payroll/src/lib.rs

• DataKey::NonceFingerprint(BytesN<32>) — stores SHA-256 batch fingerprint alongside consumed nonce
• compute_batch_fingerprint() — SHA-256 hash of (total_spend, employees, amounts, proof prefixes)
• batch_process_payroll() — idempotent nonce check:
  • Same nonce + same fingerprint → returns existing run_id (safe retry)
  • Same nonce + different fingerprint → panics with "Conflicting replay detected: nonce already used with a different batch payload" (malicious replay)
• prepare_payroll_run() — same idempotent/replay logic applied to the prepare path
• Tests (6 new):
  • test_idempotent_retry_same_batch_returns_same_run_id — retry returns same run_id
  • test_conflicting_replay_with_modified_payload_is_rejected — different payload rejected
  • test_prepare_payroll_run_idempotent_retry — prepare path idempotent
  • test_prepare_payroll_run_rejects_conflicting_replay — prepare path replay rejected
  • test_distinct_nonces_with_same_payload_are_distinct_runs — different nonces = different runs
  • test_cross_company_same_nonce_does_not_collide — same nonce on different contract instances is independent

contracts/payroll/src/libmain.rs

• Added NonceFingerprint(BytesN<32>) DataKey variant for consistency

docs/security/replay-protection.md (new)

Comprehensive documentation covering:

• All protection layers (per-proof nullifier, per-employee period guard, batch nonce, payload fingerprint, batch execution identity)
• Canonical execution identity definition
• Safe retry vs malicious replay flow diagrams
• Integrator guidance (nonce selection, error handling, retry strategy with exponential backoff)
• Cross-company collision safety explanation
• Storage key design reference
• Testing checklist

docs/events.md

• Added BatchExecuted event to schema reference

Execution Identity Design

The canonical execution identity is a SHA-256 fingerprint computed from:

SHA-256(
    expected_total_spend (16 bytes BE)
    + for each employee i:
        employee_address (32 bytes XDR)
        + amount (16 bytes BE)
        + proof_hash (first 32 bytes)
)

Two batches with identical parameters always produce the same fingerprint; any change produces a different one.

Acceptance Criteria

Criteria	Status
Re-submitting exact same completed payroll does not duplicate state	✅
Replaying with modified payload data is rejected	✅
Execution identity cannot collide across companies	✅
Tests cover success, retry, duplicate rejection, malicious replay	✅
Contract errors are explicit enough for SDK mapping	✅
Documentation explains client-side retry behavior	✅

Testing

cargo test -p payment_executor   # 2 new idempotency tests
cargo test -p payroll            # 6 new idempotency/replay tests

[drips-wave]

@OG-wura 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

[edehvictor]

@OG-wura, kindly resolve conflicts.