feat/transfer-restriction-matrix

[Wetshakat]

closed #470

---

Title

feat: enforce per-category transfer restriction matrix (Reg D / Reg S)

Description

Securities-law restrictions often cap aggregate holders per category (e.g., maximum 99 Reg D accredited investors). This PR introduces a per-category counter and transfer restriction matrix to safely enforce aggregate caps directly at the protocol level.

The implementation enforces the cap dynamically and relies on strict 0 <-> >0 state transitions to maintain perfectly synchronized slot counts.

Key Features

• Configurable Restriction Matrix: Added TransferRestrictions configuration and the set_transfer_restrictions method to let issuers define max holder limits per category (e.g., RegD, RegS).
• Attestation Transfers: Introduced transfer_with_attestation to allow issuers/agents to transfer shares and explicitly assign the regulatory category of the recipient.
• Dynamic Slot Tracking:
  • category_holder_count seamlessly increments when a user's balance shifts from 0 to >0.
  • Automatically frees up the category slot (decrements count) when a holder drops to 0 shares.
• Cap Enforcement: Rejects incoming transactions natively with CategoryCapReached once the specified threshold is hit.

Security and Edge Cases Addressed

• Zero-Oscillation Resilience: Prevents double-increment or double-decrement tracking bugs by ensuring holder counts only update during explicit threshold breaches (old_share == 0 && new_share > 0 and vice-versa).
• Self-Transfer Protection: Explicitly added a short-circuit bypass for from == to scenarios in transfer_with_attestation to completely prevent a potential double-spend vector where shares could be artificially inflated.
• Category Overwrites: If a user with a >0 balance updates their category affiliation, the state logic safely subtracts them from their old regulatory bucket before enforcing the cap and attributing them to the new one.

Testing Strategy (≥95% Coverage)

• test_transfer_restrictions: Validates the core logic. Asserts correct cap enforcement limits and correctly frees up slots when an existing user's shares are dropped to 0.
• test_oscillating_across_zero: Ensures that transfers bypassing zero logic behave predictably, maintaining absolute correctness for holder counts across aggressive balance updates.

[drips-wave]

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