feat: Add ScheduleCommitFinalize to program-api only

[snawaz]

I splitted #847 and this PR contains the program-API only so that related PRs (in this repo as well as in DLP and SDK repo) can be merged in the correct order starting with magicblock-labs/ephemeral-rollups-sdk#108.

Summary by CodeRabbit

• New Features

  • Added commit finalization operations with optional undelegation, expanding commit lifecycle controls.
  • Introduced a scheduling instruction to initiate commit finalization with configurable undelegation requests.

• Chores

  • Updated an internal test dependency reference.

[github-actions]

Manual Deploy Available

You can trigger a manual deploy of this PR branch to testnet:

Deploy to Testnet 🚀

Alternative: Comment /deploy on this PR to trigger deployment directly.

⚠️ Note: Manual deploy requires authorization. Only authorized users can trigger deployments.

Comment updated automatically when the PR is synchronized.

[snawaz]

• feat: Add ScheduleCommitFinalize along with CommitFinalizeTask #847
• feat: Add ScheduleCommitFinalize to program-api only #989 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added commit-finalization support and scheduling wiring: two new MagicBaseIntentArgs variants (CommitFinalize(CommitTypeArgs) and CommitFinalizeAndUndelegate(CommitAndUndelegateArgs)), two new optional fields on MagicIntentBundleArgs (commit_finalize and commit_finalize_and_undelegate), and an updated From<MagicBaseIntentArgs> for MagicIntentBundleArgs mapping those variants. Introduced ScheduleCommitFinalize { request_undelegation: bool } to MagicBlockInstruction and added dispatcher and MagicBaseIntent::try_from_args match arms for these variants (currently unimplemented todo!() placeholders). Updated test-integration ephemeral-rollups-sdk git rev.

Suggested reviewers

• thlorenz
• GabrielePicco
• bmuddha

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch snawaz/commit-finalize-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@magicblock-magic-program-api/src/args.rs`:
- Around line 93-99: MagicIntentBundleArgs currently exposes four optional
commit fields (commit, commit_and_undelegate, commit_finalize,
commit_finalize_and_undelegate) but MagicIntentBundle::try_from_args only
processes commit and commit_and_undelegate, silently dropping the finalize
variants and allowing invalid simultaneous construction (see
test_ix_commit_local.rs); fix by replacing the four Option fields with a single
enum (e.g., CommitIntent with variants Commit, CommitAndUndelegate,
CommitFinalize, CommitFinalizeAndUndelegate) to enforce mutual exclusion at the
type level, update MagicIntentBundle::try_from_args to match on that enum and
implement proper routing/validation for each variant (including account overlap
checks), or if finalize variants are not used, remove commit_finalize and
commit_finalize_and_undelegate from MagicIntentBundleArgs and tests; ensure
tests (test_ix_commit_local.rs) are updated to construct valid bundles and that
runtime validation rejects conflicting inputs.

In `@magicblock-magic-program-api/src/instruction.rs`:
- Around line 182-196: Doc comment for ScheduleCommitFinalize is contradictory
about whether this is a single-step commit or the first of two; update the
comment to clearly state that ScheduleCommitFinalize only schedules the commit
(first step) and that a subsequent AcceptScheduleCommits call completes the
scheduling. Replace the boolean flag design: instead of ScheduleCommitFinalize {
request_undelegation: bool } introduce two distinct variants (e.g.,
ScheduleCommitFinalize and ScheduleCommitFinalizeAndUndelegate) or have
ScheduleCommitFinalize carry the full CommitAndUndelegateArgs payload so the
undelegate base-actions (as represented by UndelegateTypeArgs::WithBaseActions
and MagicBaseIntentArgs::CommitFinalizeAndUndelegate) are preserved; update uses
of ScheduleCommitFinalize accordingly to match the args-layer shape.

[coderabbitai]

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@magicblock-magic-program-api/src/args.rs`:
- Around line 88-89: The new CommitFinalize and CommitFinalizeAndUndelegate
variants (and the corresponding fields on MagicIntentBundleArgs) are never
consumed by MagicIntentBundle::try_from_args (in
programs/magicblock/src/magic_scheduled_base_intent.rs), so intents will be
silently dropped and multiple commit fields can be set at once; update
MagicIntentBundle::try_from_args to map and handle CommitFinalize and
CommitFinalizeAndUndelegate the same way it handles Commit and
CommitAndUndelegate (or route them into ScheduleIntentBundle processing), and
add validation in MagicIntentBundleArgs parsing (or use a mutually-exclusive
enum) to enforce that only one of the four commit variants is provided and to
extend existing account-overlap checks to cover finalize variants; after changes
run rg -n 'commit_finalize' to confirm consumption.

In `@magicblock-magic-program-api/src/instruction.rs`:
- Around line 182-196: Docstring is contradictory and the bool flag is
under-expressive: update the ScheduleCommitFinalize variant's documentation to
state this is the first step of a two-step flow requiring
MagicBlockInstruction::AcceptScheduleCommits to complete scheduling (remove the
"single DLP instruction" claim), and replace the request_undelegation: bool with
a richer payload (either split into two unit variants ScheduleCommitFinalize and
ScheduleCommitFinalizeAndUndelegate to mirror
ScheduleCommit/ScheduleCommitAndUndelegate, or change ScheduleCommitFinalize to
carry CommitAndUndelegateArgs) so you don't discard UndelegateTypeArgs
(including WithBaseActions { base_actions: Vec<BaseActionArgs }); update any
matching match arms and MagicBaseIntentArgs handling (including
CommitFinalizeAndUndelegate) to use the chosen approach.

[GabrielePicco]

LGTM!

[taco-paco]

LGTM

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@programs/magicblock/src/magic_scheduled_base_intent.rs`:
- Around line 410-411: In MagicBaseIntent::try_from_args, replace the todo!()
panics for the MagicBaseIntentArgs::CommitFinalize(_) and
MagicBaseIntentArgs::CommitFinalizeAndUndelegate(_) match arms with a
recoverable error return (e.g., an Err containing an appropriate
InstructionError/variant indicating an unsupported or invalid instruction) so
the public function does not panic; locate the match on MagicBaseIntentArgs in
try_from_args and return a descriptive InstructionError for those two variants
until full implementations are added.

In `@programs/magicblock/src/magicblock_processor.rs`:
- Around line 66-68: The ScheduleCommitFinalize match arm currently calls
todo!() which will panic; replace it with a safe error return so the dispatcher
returns a deterministic ProgramResult error (e.g., return
Err(ProgramError::InvalidInstructionData) or a suitable ProgramError::Custom)
instead of panicking; update the ScheduleCommitFinalize arm in the main
instruction dispatcher in magicblock_processor.rs to return that ProgramResult
error and include a brief message or custom code if you have a project-specific
error enum.

---

Duplicate comments:
In `@magicblock-magic-program-api/src/args.rs`:
- Around line 88-117: MagicIntentBundleArgs populates commit_finalize and
commit_finalize_and_undelegate in the From<MagicBaseIntentArgs> impl, but
MagicIntentBundle::try_from_args currently only reads args.commit and
args.commit_and_undelegate and therefore silently drops finalize data; update
MagicIntentBundle::try_from_args to also check args.commit_finalize and
args.commit_finalize_and_undelegate and map them into the resulting
MagicIntentBundle (or equivalent internal fields) so finalize intents created
via ScheduleBaseIntent/ScheduleIntentBundle are preserved; ensure you reference
and set the same field names (commit_finalize, commit_finalize_and_undelegate)
on the output bundle and preserve any existing validation/conversion logic used
for commit and commit_and_undelegate.

In `@magicblock-magic-program-api/src/instruction.rs`:
- Around line 182-196: Docs and API disagree: ScheduleCommitFinalize is
documented as "committed and finalized in a single DLP instruction" but is
actually the first step requiring MagicBlockInstruction::AcceptScheduleCommits,
and the boolean field request_undelegation breaks the prior two-variant pattern
and cannot represent UndelegateTypeArgs::WithBaseActions. Fix by updating the
doc comment for ScheduleCommitFinalize to state it only schedules the commit
(first part) and requires AcceptScheduleCommits to complete, and replace the
request_undelegation: bool with a richer enum/option (e.g.,
Option<UndelegateTypeArgs> or a new UndelegateRequest enum) so the variant can
carry UndelegateTypeArgs::WithBaseActions payloads while preserving the previous
ScheduleCommit / ScheduleCommitAndUndelegate semantics.