feat(payment-distributor): implement two-step admin role rotation

[Stephan-Thomas]

Description

Implemented a secure two-step admin role rotation flow for the payment-distributor contract.

The new flow prevents accidental permanent admin lockout by separating admin transfer into two steps:

• transfer_admin allows the current admin to nominate a PendingAdmin.
• accept_admin allows the nominated address to accept the role and become the new admin.

This change also adds pending-admin storage helpers, emits an AdminTransferred event when the transfer is completed, and introduces authorization tests covering both successful and unauthorized flows.

Closes #380

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an existing issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 UI/UX improvement
• ♻️ Code refactoring
• ✅ Test addition or update
• 🔧 Configuration change

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

The payment-distributor test suite was updated to verify the complete two-step admin transfer flow and authorization requirements.

How to Test

1. Run the payment distributor test suite:
   cargo test -p payment-distributor
2. Verify that the current admin can call transfer_admin and that the nominated address is stored as the pending admin.
3. Verify that only the pending admin can call accept_admin, after which the admin role is transferred, the pending admin is cleared, and the AdminTransferred event is emitted.
4. Verify that unauthorized callers of transfer_admin and accept_admin fail with Error::Unauthorized.
5. Verify chained admin transfers and event emission through the relevant unit tests.

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• E2E tests added/updated (if applicable)
• Manual testing completed

Screenshots (if applicable)

Not applicable — this change affects the Soroban contract logic and test suite rather than a user interface.

Additional Notes

The admin transfer now follows a two-step ownership rotation pattern to reduce the risk of permanently losing administrative access due to an incorrect or unintended address.

PendingAdmin is stored separately from the active Admin and is only promoted after the nominated address explicitly calls accept_admin.

The completed transfer emits an AdminTransferred event containing the previous and new admin addresses.

For Reviewers

Please focus on:

• Code quality and readability
• Test coverage
• Security implications
• Performance impact
• Breaking changes

In particular, review the authorization checks around transfer_admin and accept_admin, the pending-admin storage lifecycle, chained transfers, and the AdminTransferred event emission.

[drips-wave]

@Stephan-Thomas 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