[Stacks 2.1] Support PoX-2 for account STX balance `locked` state

[zone117x]

The API currently uses the Stacks 2.0 stx_lock_event event to store and retrieve "locked" and "unlock_height" data when responding to account balance requests. This was implemented in https://github.com/hirosystems/stacks-blockchain-api/pull/324 -- the account balance response is currently:

interface StxBalance {
  balance: string;
  total_sent: string;
  total_received: string;
  total_fees_sent: string;
  total_miner_rewards_received: string;
  /* [PoX] The transaction where the lock event occurred. Empty if no tokens are locked. */
  lock_tx_id: string;
  /* [PoX] The amount of locked STX, as string quoted micro-STX. Zero if no tokens are locked. */
  locked: string;
  /* [PoX] The STX chain block height of when the lock event occurred. Zero if no tokens are locked. */
  lock_height: number;
  /* [PoX] The burnchain block height of when the lock event occurred. Zero if no tokens are locked. */
  burnchain_lock_height: number;
  /* [PoX] The burnchain block height of when the tokens unlock. Zero if no tokens are locked. */
  burnchain_unlock_height: number;
}

PoX v2 introduces several new features, some already merged:

• https://github.com/stacks-network/stacks-blockchain/pull/2755

Some WIP:

• https://github.com/stacks-network/stacks-blockchain/issues/2534
• https://github.com/stacks-network/stacks-blockchain/issues/2533
• https://github.com/stacks-network/stacks-blockchain/issues/2556

It doesn't look like there are any new events (similar to stx_lock_event) for these new PoX operations -- can/will the various new operations just emit another stx_lock_event event. If so, does it make sense for the API use the same event to query for the latest locked state when returning stx balance data?

[kantai]

Yes, these new operations can emit events.

Would the most useful thing be to emit something like a StxBalanceUpdate event that just emitted the new state of the balance. Something like:

{
  /* The current available balance, as string quoted micro-STX */
  balance: string,
  /* [PoX] The amount of locked STX, as string quoted micro-STX. Zero if no tokens are locked. */
  locked: string,
  /* [PoX] The burnchain block height of when the tokens unlock. Zero if no tokens are locked. */
  burnchain_unlock_height: number,
}

And then this could be emitted in every transaction that modified the balance. That way things like stack-extend, stack-increase, and stack-unlock (which will probably be automatic, so it would end up being associated with a fake transaction, like the boot contract instantiation or the epoch 2.05/2.10 transitions) could all be handled without special casing their events.

Do you think that would work?

[zone117x]

@kantai yes, I think that should work. There's also the Rosetta operations to take into consideration (see https://github.com/hirosystems/stacks-blockchain-api/issues/1278), but I think those should still be possible with your suggested new event.