Improve Access and Timelock examples

[ericnordelo]

Summary by CodeRabbit

• New Features

  • Added a dedicated admin role for managing timelock self-administration settings.
  • Clarified governance behavior so role administration can continue after root renunciation when roles are re-parented appropriately.

• Documentation

  • Expanded guidance on treasury custody, delayed transfers, and irreversible upgrade behavior.
  • Improved explanations of renounce flow ordering and long-term governance expectations.

• Tests

  • Updated governance tests to validate role management still works after root renunciation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ec7b28de-846e-44a9-a806-9c41f94e6a78

📥 Commits

Reviewing files that changed from the base of the PR and between bb2405c and 09b0bcb.

📒 Files selected for processing (5)

• contracts/access/examples/access_control/reward_treasury.move
• contracts/access/examples/access_control/tests/reward_treasury_tests.move
• contracts/access/examples/delayed_transfer/timelocked_treasury.move
• contracts/timelock/examples/timelock/example_dual_governance.move
• contracts/timelock/examples/timelock/example_upgrade_vault.move

---

📝 Walkthrough

Walkthrough

Documentation comments were revised across the access control, delayed transfer, and timelock example modules to clarify root-role renounce semantics, custody-change policies, and upgrade vault invariants. A test for root-role renouncement was updated to reparent role administration beforehand and verify post-renounce role management. The dual governance example introduces a new AdminRole witness type used for MAIN timelock self-administration, replacing ProposerRole in that slot.

Changes

Access control and timelock example documentation and governance updates

Layer / File(s)	Summary
Root-role renounce documentation and test update contracts/access/examples/access_control/reward_treasury.move, contracts/access/examples/access_control/tests/reward_treasury_tests.move	Documentation clarifies that renouncing the root role freezes any administered roles unless re-parented first; the renounce test now reparents GuardianRole/DistributorRole administration before scheduling renounce and asserts post-renounce role grant/revoke behavior.
Delayed-transfer custody policy documentation contracts/access/examples/delayed_transfer/timelocked_treasury.move	Module documentation is rewritten to describe wrap-at-creation custody, the three custody-change flows, and unrestricted withdraw_wrapped operations, removing the fixed min_delay reference.
AdminRole self-administration for MAIN timelock contracts/timelock/examples/timelock/example_dual_governance.move	Adds a new AdminRole struct and updates init to register it in AccessControl and use it as the MAIN timelock's self-administration slot instead of ProposerRole.
Upgrade vault one-way door documentation contracts/timelock/examples/timelock/example_upgrade_vault.move	Adds documentation describing the permanence of UpgradeCap wrapping and the need to explicitly cancel superseded scheduled upgrades.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• OpenZeppelin/contracts-sui#337: Targets the same root-role renounce/role-admin behavior in AccessControl, including renounce_role logic and root-role handling.
• OpenZeppelin/contracts-sui#339: Tracks the same root-admin/renounce flow semantics, including admin scheduling and post-renounce role-management behavior updated in the test.
• OpenZeppelin/contracts-sui#409: Directly tied to the example_dual_governance.move changes adding AdminRole and rewiring MAIN timelock self-administration.

Suggested reviewers: immrsd, bidzyyys, 0xNeshi

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No pull request description was provided, so the required template sections and checklist are missing.	Add the template sections, including Resolves #???, a change summary, and the Tests/Documentation/Changelog checklist.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change to access and timelock examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/improve-examples-for-ac-and-timelock

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.59%. Comparing base (bb2405c) to head (09b0bcb).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #437   +/-   ##
=======================================
  Coverage   96.59%   96.59%           
=======================================
  Files          34       34           
  Lines        3405     3405           
  Branches      794      794           
=======================================
  Hits         3289     3289           
  Misses         70       70           
  Partials       46       46           

Flag	Coverage Δ
contracts/access	65.46% <ø> (ø)
contracts/allowance	52.40% <ø> (ø)
contracts/finance	26.07% <ø> (ø)
contracts/timelock	54.57% <ø> (ø)
contracts/utils	44.09% <ø> (ø)
math/core	86.89% <ø> (ø)
math/fixed_point	63.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

[bidzyyys]

lgtm