Rwa initial lockup

[ozgunozerk]

Fixes #743

PR Checklist

• Tests
• Documentation

Summary by CodeRabbit

Release Notes

New Features

• Added Initial Lockup Period compliance module for managing token vesting with configurable lockup periods and migration presets.
• Added Time Transfer Limits compliance module for enforcing time-windowed transfer caps with identity-based volume tracking.
• Included example implementations and comprehensive test coverage for both modules.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: faa2e275-3ee7-43d4-be9f-b8339329f3ab

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Adds two comprehensive RWA compliance modules to the Stellar contracts system: an initial lockup period mechanism for time-locked token vesting with preset state migration, and a time-windowed transfer limit system for identity-aggregated rate limiting. Both modules include trait definitions, persistent storage layers, contract wrappers, and extensive test coverage integrated into the compliance framework.

Changes

RWA Compliance Modules

Layer / File(s)	Summary
Initial Lockup Period trait API and events packages/tokens/src/rwa/compliance/modules/initial_lockup_period/mod.rs	Defines InitialLockupPeriod trait with entrypoints to configure per-token lockup periods, preset wallet lock state for migrations, and mark completion of the preset phase. Includes LockupPeriodSet, LockupStatePreset, and PresetCompleted contract events.
Initial Lockup Period storage and state management packages/tokens/src/rwa/compliance/modules/initial_lockup_period/storage.rs	Persistent storage for lock entries (LockedTokens, LockedDetails), query helpers for lockup periods/balances/unlock status, state mutations with overflow/bounds validation, and hook handlers (on_transfer, on_created, on_destroyed) with lazy lock consumption and safe arithmetic.
Initial Lockup Period contract wrapper examples/rwa/compliance-initial-lockup-period/Cargo.toml, examples/rwa/compliance-initial-lockup-period/src/contract.rs, examples/rwa/compliance-initial-lockup-period/src/lib.rs	InitialLockupPeriodContract implements AccessControl for manager-gated configuration, InitialLockupPeriod trait delegation, and ComplianceModule for hook integration. Admin-only compliance address setter wires token-scoped enforcement.
Initial Lockup Period tests examples/rwa/compliance-initial-lockup-period/src/test.rs	24 test functions covering lockup persistence, lock creation on mint, transfer blocking/release based on ledger sequence, expired lock consumption, preset state validation/panic cases, completion flag toggle, module naming, authorization checks, and compliance address round-trip.
Time Transfers Limits trait API and events packages/tokens/src/rwa/compliance/modules/time_transfers_limits/mod.rs	Defines TimeTransfersLimits trait with identity registry setup, per-token limit set/batch-set/remove/batch-remove, and query methods for configured limits and per-identity counters. Includes MAX_LIMITS constant, TimeTransferLimitSet/TimeTransferLimitRemoved contract events.
Time Transfers Limits storage and enforcement packages/tokens/src/rwa/compliance/modules/time_transfers_limits/storage.rs	Persistent storage for time-window transfer caps (TransferLimit) and per-identity counters with deadlines, query helpers with TTL extension, can_transfer validation against caps, on_transfer recording with counter increment/overflow panic, and limit management with bounds enforcement.
Time Transfers Limits contract wrapper examples/rwa/compliance-time-transfers-limits/Cargo.toml, examples/rwa/compliance-time-transfers-limits/src/contract.rs, examples/rwa/compliance-time-transfers-limits/src/lib.rs	TimeTransfersLimitsContract implements AccessControl for manager-gated limit configuration/removal (including batch variants), ComplianceModule for hook integration requiring compliance address auth, and admin-only compliance address setter.
Time Transfers Limits tests examples/rwa/compliance-time-transfers-limits/src/test.rs	Mock IRS contract for identity resolution, plus 20+ test functions covering limit persistence/overwrite, bound enforcement, removal validation, identity-aggregated counters across wallets, cap enforcement, window expiry/restart, authorization, and per-token isolation.
Module system integration packages/tokens/src/rwa/compliance/modules/mod.rs	Exports initial_lockup_period and time_transfers_limits modules; extends ComplianceModuleError with five new variants: InsufficientUnlockedBalance (399), LockedAmountExceedsBalance (400), TransferLimitExceeded (401), LimitBoundExceeded (402), LimitNotFound (403).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• OpenZeppelin/stellar-contracts#723: Main PR's contract wrappers implement set_compliance_address which depends on PR #723's compliance-module restructuring of token-scoped interfaces.
• OpenZeppelin/stellar-contracts#737: Both PRs extend ComplianceModuleError enum that the new modules rely on for error reporting.
• OpenZeppelin/stellar-contracts#726: Main PR's set_compliance_address signature matches the function-signature change introduced by PR #726.

Suggested reviewers

• brozorec

Poem

🐰 Two shiny modules hop into the fray,
Lockup periods and limits save the day!
Time-windowed transfers, preset states galore,
Compliance just opened a brand new door! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is incomplete and lacks substantial detail about the changes, despite referencing issue #743 and checking the Tests and Documentation boxes.	Expand the description to explain what the initial lockup module does, how it works, and summarize key implementation details beyond the checklist.
Out of Scope Changes check	⚠️ Warning	The PR includes changes to the time_transfers_limits module which is unrelated to the initial lockup feature specified in issue #743.	Remove changes to time_transfers_limits module or clarify their relationship to the initial lockup feature in issue #743.
Title check	❓ Inconclusive	The title 'Rwa initial lockup' is vague and uses generic phrasing that doesn't clearly summarize the main changes in the changeset.	Use a more descriptive title that clarifies the specific changes, such as 'Add InitialLockupPeriod compliance module' or 'Implement initial lockup period compliance for RWA tokens'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully implements the initial lockup module compliance feature requested in issue #743, including core functionality, storage, tests, and documentation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rwa-initial-lockup

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 98.90511% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.64%. Comparing base (62016c7) to head (bfecd3d).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...ompliance/modules/initial_lockup_period/storage.rs	98.12%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #748      +/-   ##
==========================================
+ Coverage   96.62%   96.64%   +0.02%     
==========================================
  Files          71       72       +1     
  Lines        7468     7610     +142     
==========================================
+ Hits         7216     7355     +139     
- Misses        252      255       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[brozorec]

Great job 👌

There are couple of LOCs that are missing test coverage, if you can add those test cases before merging would be great.