Incorrect cycle start

[aryzing]

The /v2/pox and the /extended/v2/pox/cycles/:cycle_number endpoints are counting cycles differently.

When does a cycle start? With the prepare phase or after the prepare phase?

[janniks]

This can be a bit confusing, yes.
Basically, theres two (and a half) ways of counting cycles.

We try to consider what the node responds in RPC calls as canonical. That would be defined by the pox contract (and is the most simple way of calculating). In simple terms it's the modulo of cycle (total) length (also accounting for first Stacks block height). In this way of counting, we always start with the reward phase (we could imagine the first cycle didn't have a prepare phase -- not sure if that's exactly true, but how I think about it).
In this way of thinking we also consider a cycle's prepare phase still inside the previous cycle. That also means we have information on the upcoming cycle before the current cycle has ended (which is why the API endpoint can respond with info even though the node still shows the current_cycle as one earlier).

So, to answer the question more clearly: a cycle starts with the reward phase (and after RP blocks we switch from reward-phase to prepare-phase, this prepare phase "prepares" the next cycle; at that point we have the PoX reward-set information of the next cycle).

where

• RP is pox-reward-cycle-length - pox-prepare-cycle-length

---

Hope that makes sense -- A bit more info here: https://garden.janniks.com/PoX-Behavior

[aryzing]

Thanks @janniks for the explanation 🙌. Two words though: too complicated 😅 .

A cycle's start, what a cycle is, and when the reward phase takes place should be precisely defined and uniformly reported by all API endpoints. It's also ok for different endpoints to report different things, but then those things need different names. Given how fundamental a "cycle" is, I believe it would help alleviate some of the confusion if a "cycle" meant the same thing in all places.

That would be defined by the pox contract

That's a great link, thank you 🙏

[janniks]

Yes, I agree.

The node (mostly pox endpoint) is the closest thing we have to a definition. I think the ecosystem is getting pretty consistent, but in the code it can be tricky. Even how developers show the cycles in a UI can change how they are perceived.. The important bits are: there's cycles and you have until prepare-length blocks before a cycle starts to make your stacking txs count for that cycle.

For the node, the pox endpoints use the terms "phase" and "cycle" avoid confusion, but due to backwards compatibility multiple fields looks very similar.