2.1 PoX Upgrade implementation and Consequences

[kantai]

The goal of this topic is to outline a plan and link together the related issues for implementing an upgrade to PoX at the network upgrade of Stacks 2.1. This is also a place for discussion of the impacts of this plan, receiving feedback on the plan, suggestions for additional changes.

High-level Approach

At the launch of Stacks 2.1, a new pox-2 contract will be published. The stacks-node consensus algorithm will use the new pox-2 contract for determining PoX reward sets and governing PoX locks. Existing calls to the original pox contract will be re-routed to pox-2.

The new PoX contract operates exclusively with PoX state that was created by itself. To do so, a particular reward cycle N is chosen as the “Last PoX 2.0” reward cycle, and then the first PoX 2.1 reward cycle is the subsequent cycle (N+1).

This defines three “periods” of PoX operation:

Period 1	Period 2	Period 3
2.0 Consensus Rules in Effect	2.1 Consensus Rules enacted, but first PoX 2.1 reward cycle has not begun	First 2.1 reward cycle has begun
This is the period of time before the 2.1 fork.	This is after the 2.1 fork, but before cycle (N+1).	This is after cycle (N+1) has begun. Original PoX contract state will no longer have any impact on reward sets, account lock status, etc.

• Every account that is locked by the original contract for cycle N and beyond is unlocked at the end of Cycle N.
• Every account that is locked (whether by 2.0 or 2.1) is eligible for a call to pox-2.lock-extend, which allows an account to re-lock for some subsequent number of reward cycles while still being locked.
  • This would also be true for delegate-lock-extend
• Calls to PoX 2 which would attempt to create state for a cycle before (N+1) will fail
• Calls to the original PoX contract which would attempt to create state for a cycle >= N+1 can either be made to fail or allowed to pass, but any state after N+1 is ignored. The first case is probably a better user experience. It would require interposing on contract-calls during period 2 and checking the reward cycles arguments: the relevant functions are stack-stx, delegate-stack-stx, stack-aggregation-commit, and reject-pox.

Consequences of this approach

• All accounts that want to participate in cycle N+1 would need to delegate/stack in a window of time during cycle N. Anyone that stacked for say 12 cycles starting at cycle N, would need to invoke stack-stx 11 cycles before they would have otherwise needed to.
• All accounts that have delegated and called allow-contract-caller would need to re-initialize those relationships.

Semantics

Behavior during "Period 2"

Original PoX Contract

stack-stx

• If called with a lock-period that extends into Period 3, this function will yield a runtime error, and not impart any state changes
• If called with an account that already has performed a locking operation via the PoX 2.1 contract, this function will yield a runtime error, and not impart any state changes. This is important to test: the current locking implementation assumes that the PoX contract itself handles ensuring that a lock request is valid, so this would need to change.
• Otherwise, this function works as normal — a user is able to lock and stack for reward cycles before (N+1)

stack-aggregation-commit

• If called with a reward-cycle >= N+1, this function will yield a runtime error, and not impart any state changes
• Otherwise, this function works as normal

delegate-stack-stx

• If called with a lock-period that extends into Period 3, this function will yield a runtime error, and not impart any state changes
• If called with a stacker that already has performed a locking operation via the PoX 2.1 contract, this function will yield a runtime error, and not impart any state changes
• Otherwise, this function works as normal — a user is able to lock and stack for reward cycles before (N+1)

reject-pox

• If the next cycle is >= N+1, this function will yield a runtime error and not impart any state changes
• Otherwise, this function works as normal

set-burnchain-parameters

This method will behave exactly as it did before. There will be no contract-call interposition to prevent it from being called

disallow-contract-caller

This method will behave exactly as it did before. There will be no contract-call interposition to prevent it from being called

allow-contract-caller

This method will behave exactly as it did before. There will be no contract-call interposition to prevent it from being called

revoke-delegate-stx

This method will behave exactly as it did before. There will be no contract-call interposition to prevent it from being called

delegate-stx

This method will behave exactly as it did before. There will be no contract-call interposition to prevent it from being called

PoX 2 Contract

stack-stx

• If called with a lock-period that includes any cycles in Period 2, this function will yield a runtime error and not impart any state changes
• Otherwise, this function works as normal — a user is able to lock and stack for reward cycles greater than or equal to (N+1)

stack-aggregation-commit

• If called with a reward-cycle < N + 1, this function will yield a runtime error and not impart any state changes
• Otherwise, this function works as normal

delegate-stack-stx

• If called with a lock-period that includes any cycles in Period 2, this function will yield a runtime error and not impart any state changes
• Otherwise, this function works as normal — a delegate is able to lock and stack for reward cycles greater than or equal to (N+1)

reject-pox

• If the next cycle is < N+1, this function will yield a runtime error and not impart any state changes
• Otherwise, this function works as normal

set-burnchain-parameters

This method will always behave the same

disallow-contract-caller

This method will always behave the same

allow-contract-caller

This method will always behave the same

revoke-delegate-stx

This method will always behave the same

delegate-stx

This method will always behave the same

lock-extend

• if the period of extension is exclusively reward cycles >= N + 1, then this function operates “normally”. It is able to insert state for the extended-into reward cycles in the 2.1 contract
• if the period of extension includes reward cycles < N + 1, the the function yields a runtime error

delegate-lock-extend

• if the period of extension is exclusively 2.1 reward cycles, then this function operates “normally”. It is able to insert state for the extended-into reward cycles in the 2.1 contract

stack-increase

• If the next reward cycle is < N + 1 , then this function yields a runtime error.
• Otherwise, this function behaves as normal

delegate-stack-increase

• If the next reward cycle is < N + 1 , then this function yields a runtime error.
• Otherwise, this function behaves as normal

Behavior During "Period 3"

Original PoX Contract

All contract-calls to the PoX contract are interposed on and re-routed to the PoX 2.1 contract.

This is done to reduce the tooling upgrades that would otherwise be required by the whole network and to allow contracts that already depended on PoX functionality to continue to operate without themselves needing to produce new contracts.

PoX 2.1 Contract

All behaviors for the PoX 2.1 contract in this period should now be the "normal" contract behavior.

Implementing "Mass Unlock" at Cycle N

The VM should implement the "mass unlock" at Cycle N lazily. Basically, if the account locking state was set by the original PoX contract, then perform the "account unlock" lazy update (it is already implemented lazily) as if the unlock height were the end of Cycle N. To do this check, the VM needs to be able to differentiate between account states set by the original PoX contract and the new PoX contract.

To do this, we should update the STXBalance struct from:

pub struct STXBalance {
    pub amount_unlocked: u128,
    pub amount_locked: u128,
    pub unlock_height: u64,
}

to

pub enum STXBalance {
    Unlocked { pub amount: u128 },
    LockedPoxOne {
        pub amount_unlocked: u128,
        pub amount_locked: u128,
        pub unlock_height: u64,
    },
    LockedPoxTwo {
        pub amount_unlocked: u128,
        pub amount_locked: u128,
        pub unlock_height: u64,
    },
}

Where serialization of Unlocked and LockedPoxOne use the current 40-byte serialization:

[amount_unlocked] [amount_locked] [unlocked_height]

and serialization of LockedPoxTwo uses a 41-byte serialization

[version byte] [amount_unlocked] [amount_locked] [unlocked_height]

When deserializing, if amount_locked = 0, it deserializes to Unlocked.

New Features and Behavior Updates

PoX Contract Functions

• Allow unlocking if a slot is not obtained: PoX Updates: stack-unlock #2534
• Extending existing locks without first requiring an unlock: PoX Updates: stack-extend and delegate-stack-extend #2532
• Updating an existing lock amount without requiring a minimum: PoX Updates: stack-increase #2533

New Native Functions

• Getter for address lock information
• Getter for whether an address is able to "early unlock"
• Getter for current cycle reward set information

All of these are captured in #2538

Behavior Updates

• Fix for auto-expiring contract-call allowances: pox contract: parameter in allow-contract-caller for upper limit does not work #2522

Plumbing for the 2.1 Changes

• Data migration for pox -> pox-v2: PoX Updates: Implement 2.1 data port from pox -> pox-v2 #2536
• Contract-call interposition: Stacks 2.1: Clarity contract-call interposition #2537

Anchor block selection

• Flash-block resistance: Stacks 2.1: Flash-block resistant PoX anchor selection calculation #2535

Discussion

pox-2 vs pox-extension approach trade-offs

There are two good options for how to upgrade the existing PoX contract:

1. Publish pox-2 contract - this would be a new contract, with existing PoX functions updated and new functions added. Function calls and transactions against the original pox contract would be re-routed by the Clarity VM to the new contract.
2. Publish pox-extension contract - this would be a new contract with exclusively new functionality. The contract would be implemented not in Clarity, but as a "simulated" contract, where the function calls are re-routed to a native implementation capable of operating on the original pox contract's data.

Outright replacing the existing PoX contract should be avoided -- one of the fundamental assumptions made by the Clarity VM is that a particular contract can only be published "once".

One way to think about the trade-offs with these approaches is looking at the potential benefits to each:

benefit?	pox-2 approach	extension approach
Can change existing behavior	yes	no
Doesn't require function interception	no	no
pox contract remains usable	no	yes
New functionality source published	yes	no

In both approaches, some kind of function interception is required: (a) the extension approach requires intercepting calls to pox-extension and replacing them with native implementations and (b) the pox-2 approach requires intercepting calls to pox and rerouting them to calls to pox-2. The main benefit to the extension approach is that the original pox contract remains directly callable. However, the pox-2 approach allows the new contract to behave more similarly to a normal Clarity contract and it allows existing behaviors to either be updated or fixed. Because of this, I think the pox-2 approach is the better strategy, however, suggestions and discussion are still appreciated here.

[jcnelson]

Thanks for taking the time to break this into issues @kantai!

Just reiterating something we talked about, we have a choice in whether or not to cause contract-calls into pox to fail or get redirected to methods in pox-v2. I think we've settled on the latter, but it's worth pointing out that we'll need to be very judicious in how the redirected methods in 2.1 work. Namely, any change to these methods risks breaking any smart contract that invokes them. This rules out making them all simply stop working as part of the 2.1 upgrade, but it also means that if at all possible, we should make it so changes to Stacking happen in new methods (this isn't always possible, of course -- for example, we can't fix #2522 this way).

[psq]

Maybe you could avoid the double negation on Doesn't require function interception, and flip it to say Require function interception, I had to do a double take, twice, to really understand what this meant...

[kantai]

Yes, I agree the phrasing is a little awkward -- I wanted the table to be setup such that a "yes" indicated a positive attribute and a "no" indicated a negative attribute for the design.

[jcnelson]

Thanks for the update, @kantai! I also favor of the pox-2 approach over the pox-extension approach. But, I don't think the pox-extension approach strictly requires a native implementation. I think we could write the pox-extension code mostly in Clarity, but give it some private getters and setters for reading and writing private data in .pox which have native implementations.

But that said, I still favor the pox-2 approach simply because it puts all of the PoX Clarity code in one place, and makes it so there is at most one active PoX entry point in the system (and moreover, it lives in a single contract).

[jcnelson]

We're considering at a "period 2" length of 2 reward cycles, or about 4 weeks. This will give Stackers and pool operators time to migrate to the new pox-2 contract. Any push-back on this?

[jcnelson]

A question for the stakeholders: how should the migration to pox-2 happen for smart contracts? There are two options:

• Re-route calls to stack-stx and other .pox methods to their equivalent methods of .pox-2
• Cause all calls to .pox to fail.

The first option keeps old .pox callers "working," but if the semantics of .pox-2 change, then the caller may in fact be broken by the re-routing. The second option breaks all old .pox callers, but at least it's a fail-fast outcome that can be solved by deploying a new version of the contract that calls .pox-2 instead (and gives the contract author the ability to alter their code to deal with any new behavioral changes in .pox-2). The second option may be less painful than it looks -- users have to upgrade their delegations anyway, and this effectively gives pool contract authors the ability to make any changes to their pools that they wish they could have made in the original pool code.

[jcnelson]

I've gotten no feedback since the above comment, but we're coming up to the point where we have to make a decision.

Right now, there are three non-trivial contracts that call into .pox (obtained from https://search-clarity.dev): the @yknl's XVerse pool, @friedger's pool tool, and @dantrevino and co.'s boombox contract. Would love to hear these folks' opinions on how to proceed.

Just looking at the code for these three contracts, I think contract-call interposition is still on the table. It doesn't look like anything would break if we did contract-call interposition today. None of the calls to stack (or delegate-stack) do any additional block height checks to prevent callers from stacking too early, so they should just work with continuous stacking. I don't think we anticipate changing the return types of any of the existing read-only methods (which are used quite often), so that's probably not an issue.

However, if we just keep the interfaces the same, it would be just as easy to re-deploy these (and future) contracts to just call into .pox-2.

[friedger]

For my existing contracts it does not matter. For the planned autonomous stacking pool, it might be more difficult to change the contract to pox-2 when required. I think we can let the pool expire and start a new one with pox-2.

[dantrevino]

For Boom, we set block-height limits on our Boombox implementations so we will not have pox-related contracts that span the migration period. It's easy enough for us to route around any changes. pox-2 ftw.