Repository navigation
Open
Description
Goal
Add an on-chain way for an owner program to request that a v2 delegated account be returned, with a timeout recovery path if the validator does not respond.
This work is separate from validator-requested Undelegate because Challenge clusters can have live commitments, challenges, locked stake, and state buffers when the timeout expires.
Why
An owner program currently has no v2 request object or bounded recovery path when the current validator does not complete undelegation.
The legacy timeout rules cannot be copied directly because they do not account for the fraud-proof state machine.
Scope
- First define how a final validator commitment is signaled after an owner request and how an active Challenge commitment is settled if the request times out.
- Add a v2
UndelegationRequestPDA keyed by the delegated account. - Authorize requests through owner-program CPI using the delegated PDA as a signer. On-curve accounts need a separate authorization design and are not included initially.
- Reject a new request while a commitment or challenge is already active.
- Use the existing protocol timeout of 9,000 slots.
- Make repeated requests idempotent and never extend an existing deadline.
- Record the request in
DelegationStateso unrelated new commitments cannot start. - Let the validator satisfy the request through the normal final commit, finalization, and v2
Undelegatepath. - Close the request only after the account has been returned successfully.
- Add a permissionless timeout exit that returns the current finalized base-layer state without accepting unfinalized validator state.
- Define deterministic handling for any final commitment that is still active when timeout becomes available, including operator locks, challenger stake, buffers, and rent.
- Keep Direct and Challenge behavior explicit and keep all legacy behavior unchanged.
Related work
- Implement Undelegate for v2 #266 implements the shared v2
Undelegatepath. - Streamline the MagicBlock Protocol v2 delegation account lifecycle #203 tracks the broader delegation and undelegation account lifecycle.
- Implement CloseTerminalAccounts #227 tracks cleanup of terminal fraud-proof accounts.
Outcome
An owner program can request undelegation and has a documented, bounded recovery path that cannot silently accept unfinalized validator state.
Activity
[-]Add owner-requested undelegation and timeout recovery to the primary protocol[/-][+]Add owner-requested undelegation and timeout recovery to v2[/+]