Delegation state

[agraebe]

It would be great if there would be an API endpoint that would take an STX address (of a delegator) and return what accounts delegated how much (and until what block). The solution right now is to get the delegation state map from the stacking contract. It requires clarity value generation and is too involved.

This is the second time that this has come up (two different stacking integrators) and there is a high likelihood it'll become part of the main integration process. Delegators would need this for the lockup calls - they need to understand what amount to lock up and the best way is to use the lowest value of the two: delegated-amount, account-balance. If the amount is unknown, users could delegate less than their balance and the delegator wouldn't have a good way to know the appropriate amount.

[zone117x]

IIUC, the API does not have this data. It would require the stacks-node to emit new event data on delegation state changes. @kantai what do you think?

[kantai]

Yeah, I think this would need to emit a new event. It would be useful in preparation for Stacks 2.1 to enumerate the set of events that the explorer might want from the new PoX contract. Emitting delegation events, for example, would be pretty easy to do.

[agraebe]

I like the idea of a list for new events - maybe we could start a discussion in the blockchain repo and ask others to contribute @zone117x?

[zone117x]

Sure I opened an issue https://github.com/blockstack/stacks-blockchain/issues/2769

[sabbyanandan]

Depends on https://github.com/stacks-network/stacks-blockchain/issues/2554.

[friedger]

The issue is unblocked through https://github.com/stacks-network/stacks-blockchain/issues/3465

It looks like there is already some code for this: https://github.com/hirosystems/stacks-blockchain-api/blob/0799538be4467bbad3bd024dfb62c1780ba15538/src/event-stream/pox2-event-parsing.ts#L288

[markmhendrickson]

@zone117x @rafaelcr any chance this enhancement is easy to pull across the finish line, given the code available above in @friedger's comment?

The enhancement is mission-critical for a some new functionality pursued by Stacking pools that they'd like to roll out this week in light of PoX2.

[zone117x]

Some info from the discord discussion with @friedger and other stakeholders:

As a pool admin I would like to know the stx address of all pool members.

We decided on an endpoint that takes a pool/delegate address and returns a list of pool members (stackers) like the following:

[
  {
    "stacker": "<stacker principal 1>",
    "pox_addr": "<stacker pox address 1>",
    "amount_stx": "1234",
    "burnchain_unlock_height": 9999
  },
  {
    "stacker": "<stacker principal 2>",
    "pox_addr": "<stacker pox address 2>",
    "amount_stx": "4567",
    "burnchain_unlock_height": 8888
  },
  ... // 2000 or so additional entries (unless we paginate responses)
]

It sounds like the current typical pool member list is around 2k. We need to test how much load this puts on postgres on the API in order to determine if responses need to be paginated, or if the entire set can be returned.

Note that the stacks-node does not currently emit events for revoke-delegate operations, see https://github.com/stacks-network/stacks-blockchain/issues/3529. This means the API endpoint will not take revoked stackers into consideration until the above issue is resolved. According to pool operators, this won't be a problem for now:

revoke-delegation is not an issue because we can query the delegation info for the user if we want to be sure. Or we just fire a stacking and get an error

Implementation detail: There's no lower-bound on the age of these pox2 lock events. So the sql query would need to look at all pox2 delegate-stx event records. The unlock-burn-height property of the event is optional, but when specified it should be used to exclude entries where the current tip burn height is newer, e.g. if (tip_height > unlock_burn_height) then ignore.

[zone117x]

Latest requests from stakeholders:

• Ability to query for recent/latest delegations, e.g. with a query param ?after_block=<block_height>
• Use the following terminology for the endpoint: GET /extended/beta/stacking/{pool_principal}/delegations

[friedger]

:shipit: