Pox-4 User Test Cases

[saralab]

Source
cc: @setzeus @MarvinJanssen @friedger

Current Testnet will transition to epoch-2.5 [ Nakamoto Instantiation] , with this the new pox-4 contract will be activated on Testnet.
This is a list of all the use cases and scenarios that will be available as part of the upcoming pox-3 --> pox-4 update on Testnet.
We will continue to update these as we work towards the epoch-3.0 Activation next.

Name	Role	Contract-Call
Solo Stacker	Solo stacker that has enough STX to stack by him or herself for X amount of reward cycles. Solo Stackers either need to spin up their own Signer OR rely on a Delegate	PoX-4: stack-stx PoX-4: stack-increase PoX-4: stack-extend
Pool Stacker	Pool stacker that does not have enough STX to solo stack & must therefore delegate to a pool operator (known as a delegate).	PoX-4: disallow-contract-caller PoX-4: allow-contract-caller PoX-4: revoke-delegate-stx PoX-4: delegate-stx
Pool Delegate	Pool delegate / operator that stacks on behalf of other stackers (specifically ‘pool stacker’)	PoX-4: stack-aggregation-commit-indexed PoX-4: stack-aggregation-increase PoX-4: delegate-stack-stx PoX-4: delegate-stack-increase PoX-4: delegate-stack-extend
Signer	Known as a Signer, this is technically a node that has multiple signing responsibilities such as: signing for blocks, voting on an aggregated public key	Signers-Voting: vote-for-aggregate-public-key PoX-4: set-signer-key-authorization

---

1. Solo Stacker

• Solo stacker can stack stx by themselves

  • Solo stacker cannot stack without the minimum required stx
  • Solo stacker cannot post-date stacking (aka they MUST start next cycle)
  • Cannot be called by anyone except for tx-sender | contract-caller
  • Solo stacker cannot be already stacking
  • Solo stacker cannot stack without a verified signer-key
  • Solo stacker cannot stack without a SIP-18 compliant signature
  • Solo stacker cannot stack for 0 cycles
  • Solo stacker cannot stack for > 12 cycles
  • Solo stacker cannot submit an invalid pox-addr-ver

• Solo stacker can stack-extend

  • Solo stacker cannot extend without already being stacked
  • Solo stacker must extend for at least 1 cycle
  • Solo stacker must cannot extend for more than 12 cycles
  • Solo stacker must not be delegated
  • Solo stacker cannot stack without a verified signer-key
  • Solo stacker cannot stack without a SIP-18 compliant signature

• Solo stacker can stack-increase

  • Solo stacker cannot increase by more than their unlocked amount
  • Solo stacker must already be stacking
  • Solo stacker cannot already be delegated

2. Pool Stacker

• Pool stacker can set pool delegate permission (allow-contract-caller)
  • Pool stacker cannot set permission on someone else’s behalf based on tx-sender
• Pool stacker can remove pool delegate permission (disallow-contract-caller)
  • Pool stacker cannot remove permission on someone else’s behalf based on tx-sender
  • Revoke fails if stacker is not currently delegated
  • Allowed contract cannot remove permission
  • Other contract cannot remove permission
• Pool stacker can delegate-stx
  • Pool stacker cannot submit an invalid pox-addr-version
  • Pool stacker cannot delegate to two pool operators at once
  • Allowed contract can delegate for the stacker
  • Other callers cannot delegate for the stacker based on tx-sender
  • Other contract cannot delegate for the stacker based on tx-sender
• Pool stacker can revoke delegate status (revoke-delegate-stx)
  • Pool stacker cannot revoke delegate status on behalf of anyone else based on tx-sender
  • Pool stacker, if actively stacked, cannot revoke delegate status for the current reward cycle revoke only changes delegation state, not stacking state
  • Allowed contract can revoke delegate status for the stacker
  • Other contract cannot revoke delegate status for the stacker

3. Pool Delegate

• Pool delegate can successfully provide a stacking lock for a pool stacker (delegate-stack-stx)
  • Pool delegate cannot delegate-stack-stx to an un-delegated solo stacker
  • Pool delegate cannot delegate-stack-stx for the current cycle
  • Pool delegate cannot delegate-stack-stx without explicit permission (check-caller-allowed) it can, assuming delegation
  • Pool delegate cannot delegate-stack-stx on behalf of a delegator that delegated to another pool
  • Pool delegate cannot delegate-stack-stx more STX than what delegator has explicitly allowed
  • Pool delegate cannot change the pox-addr provided by delegator
  • Pool delegate cannot delegate-stack-stx if already stacking
  • Pool delegate can only delegate-stack-stx for the next cycle
  • Allowed contract can delegate-stack-stx, needs to be called by delegated-to tx-sender
  • Other contract cannot delegate-stack-stx, needs to be called by delegated-to tx-sender
  • Pool delegate cannot delegate-stack-stx if the delegation expires before the next cycle ends
  • delegate-stack-stx fails if the delegator has insufficient balance
  • Pool delegate cannot delegate-stack 0 stx
  • Pool delegate cannot submit an invalid pox-addr-ver
  • Pool delegate cannot delegate-stack-stx for 0 cycles
  • Pool delegate cannot delegate-stack-stx for > 12 cycles
• Pool delegate can successfully delegate-stack-extend

[moodmosaic]

Related: #4548, #4550.

[setzeus]

There are multiple pox-4 efforts happening across multiple people & frameworks guided by the original planning document found here. There is significant overlap between these as we aim to surface any hiding edge-case, so in order to gauge progress, it's worth reviewing each effort below:

• Integrated Rust Scenario Tests: Integrated/Scenario Tests In Rust #4586
• Stateful Property-Based Tests: [pox-4] Pool Stacking stateful property-based tests #4550
• Manual Tests: @janniks
• Clarinet Unit Tests: @hugocaillard

There are also a handful of Rust unit tests that can be found spread across the pox_4_test.rs, signers_tests.rs & signers_voting_tests.rs files found in the boot contract directory.