GITBOOK-54: fetchSignerCycleMembership: map covers protocol bond stakers; flag stale pox-5 comment

Author: werner-stacks

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignercyclemembership.md

@@ -1,6 +1,6 @@
 # fetchSignerCycleMembership
 
-Reads which signer-manager a staker is assigned to in one reward cycle, and the micro-STX counted for that assignment. Wraps the pox-5 read-only `get-signer-cycle-membership`, which reads the `staker-signer-cycle-memberships` map.
+Reads which signer-manager a staker stakes to in one reward cycle, and the micro-STX staked to it. Covers STX-only stakers and protocol bond stakers alike. Wraps the pox-5 read-only `get-signer-cycle-membership`, which reads the `staker-signer-cycle-memberships` map.
 
 ***
 
@@ -19,6 +19,8 @@ async function signerFor(staker: string) {
 #### Notes
 
 * pox-5 writes an entry for every cycle of a position, for STX-only staking and for protocol bonds: `stake`, `stake-update`, `register-for-bond` and `update-bond-registration` all add it ([add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1739-L1745), called at [L803](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L803-L805), [L907](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L907), [L1056](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1056) and [L1146](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1146)).
+* For a protocol bond staker, `amountUstx` is the STX locked with the bond ([register-for-bond](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L751-L755)). For an STX-only staker, it is the STX staked.
+* The comment above the map in pox-5.clar ([L228](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L228)) reads "Only used for stx-only staking". The comment is out of date: the map holds protocol bond stakers too, and pox-5 reads it to find a bond staker's signer-manager when it reduces bond shares ([L1364-L1367](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1364-L1367)).
 * Pass `signer` as `signerManager` to the staker reward reads such as [fetchEarnedStakerRewards](fetchearnedstakerrewards.md).
 * Resolves to `undefined` when the staker has no entry for the cycle ([get-signer-cycle-membership](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3134-L3142)).
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.
@@ -45,10 +47,10 @@ function fetchSignerCycleMembership(
 
 Resolves to the membership, or `undefined` when there is none.
 
-| Field        | Type     | Meaning                                                             |
-| ------------ | -------- | ------------------------------------------------------------------- |
-| `amountUstx` | `bigint` | micro-STX the staker delegated to the signer-manager for this cycle |
-| `signer`     | `string` | Contract principal of the signer-manager                            |
+| Field        | Type     | Meaning                                                          |
+| ------------ | -------- | ---------------------------------------------------------------- |
+| `amountUstx` | `bigint` | micro-STX the staker staked to the signer-manager for this cycle |
+| `signer`     | `string` | Contract principal of the signer-manager                         |
 
 ***
 
@@ -58,7 +60,7 @@ Resolves to the membership, or `undefined` when there is none.
 
 * **Type**: `string`
 
-Stacks address of the staker.
+Stacks address of the staker, STX-only or protocol bond.
 
 #### opts.rewardCycle (required)
 

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignerpendingstakedustx.md

@@ -21,7 +21,7 @@ if (signerManager) {
 #### Notes
 
 * Counts STX-only staking only. STX locked with a protocol bond adds 0 here ([add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1683-L1686)).
-* The value is tracked whether or not the signer-manager is in the signer set. The signer-manager's reward shares in the STX-only staking tranche ([fetchSignerSharesStakedForCycle](fetchsignersharesstakedforcycle.md)) are set from it only once its total delegation reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1713)). The contract comment says not to use this value for reward calculations ([signer-pending-staked-ustx-per-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L203-L215)).
+* The value is tracked whether or not the signer-manager is in the signer set. The signer-manager's reward shares in the STX-only staking tranche ([fetchSignerSharesStakedForCycle](fetchsignersharesstakedforcycle.md)) are set from it only once the total STX staked to it reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1713)). The contract comment says not to use this value for reward calculations ([signer-pending-staked-ustx-per-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L203-L215)).
 * Returns `0n` when the contract has no entry for the inputs.
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.
 

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignersetcontainsforcycle.md

@@ -17,7 +17,7 @@ async function inNextSignerSet(signer: string) {
 
 #### Notes
 
-* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when its total delegation for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when it falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
+* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when the total STX staked to it for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when that total falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
 * Returns `true` when the signer-manager has a node in the cycle's list ([signer-set-contains-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3436-L3444)).
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.
 

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignersetfirstitem.md

@@ -21,7 +21,7 @@ while (signer) {
 
 #### Notes
 
-* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when its total delegation for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when it falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
+* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when the total STX staked to it for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when that total falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
 * Resolves to `undefined` when the cycle's signer set is empty ([get-signer-set-first-item-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3396-L3398)).
 * Walking the set with [fetchSignerSetNextItem](fetchsignersetnextitem.md) costs one read per signer-manager.
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignersetitem.md

@@ -19,7 +19,7 @@ async function neighbors(signer: string) {
 
 #### Notes
 
-* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when its total delegation for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when it falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
+* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when the total STX staked to it for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when that total falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
 * Resolves to `undefined` when `signer` is not in the cycle's signer set ([get-signer-set-item-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3400-L3408)).
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.
 

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignersetlastitem.md

@@ -22,7 +22,7 @@ while (signer) {
 
 #### Notes
 
-* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when its total delegation for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when it falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
+* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when the total STX staked to it for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when that total falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
 * Resolves to `undefined` when the cycle's signer set is empty ([get-signer-set-last-item-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3392-L3394)).
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.
 

docs/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignersetnextitem.md

@@ -21,7 +21,7 @@ while (signer) {
 
 #### Notes
 
-* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when its total delegation for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when it falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
+* pox-5 stores each reward cycle's signer set as a doubly linked list of signer-manager principals ([signer-set maps](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3367-L3390)). A signer-manager is appended at the tail when the total STX staked to it for the cycle reaches 50,000 STX (`SIGNER_SET_MIN_USTX`, 50,000,000,000 micro-STX) and is unlinked when that total falls below ([SIGNER\_SET\_MIN\_USTX](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L82), [add-staker-to-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1705-L1717), [remove-staker-from-signer-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1546-L1551)).
 * Resolves to `undefined` at the tail of the list and when `signer` is not in the set ([get-signer-set-next-item-for-cycle](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3410-L3421)). Use [fetchSignerSetContainsForCycle](fetchsignersetcontainsforcycle.md) to tell the two apart.
 * A non-2xx response throws an `Error` whose message starts with `Error calling read-only function.` and includes the status code and URL. If the node reports that the call failed, the `Error` message is the node's `cause`.