PTBVMDocs

The obligation gate

The hot-potato check that reverts the whole plan if an obligation is left open.

The obligation gate is a hot-potato mechanism. A step can open an obligation and a later step must close it in the same plan. If it is left open when the plan ends, the whole transaction reverts, including the step that opened it.

How it is expressed

On a step, set obligation: "open" or obligation: "close", with an obligationTag that pairs the open with its close. The pattern is: open the obligation, use the borrowed value across other programs, settle it before the plan ends.

plan.step({ program: LENDER, /* ... */ obligation: "open",  obligationTag: 1 });
plan.step({ program: OTHER,  /* ... */ });
plan.step({ program: LENDER, /* ... */ obligation: "close", obligationTag: 1 });
openflag = 1use valueother stepssettleflag = 0gateflag == 0?yes → commitno → revert allSkip the settle step and the flag stays 1: the whole plan, open and all, reverts.
Obligation gate lifecycle. A step opens an obligation (a hot potato), later steps use the borrowed value, and a paired step must settle it. At the end of the plan an assertion checks the flag: settled commits, still-open reverts the entire transaction including the open.

What atomicity buys you

  • No half-executed plans. You never land the borrow without the repay, or the swap without the deposit.
  • One consistent slot. Every step reads the same chain state at the same slot.
  • Free rollback.Atomicity is native to Solana; PTBVM simply propagates any step's failure to the whole transaction.