fetchSignerCycleMembership

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.

---

Usage

import { fetchPoxInfo, fetchSignerCycleMembership } from '@stacks/bitcoin-staking';

async function signerFor(staker: string) {
  const { rewardCycleId: rewardCycle } = await fetchPoxInfo({ network: 'mainnet' });
  const membership = await fetchSignerCycleMembership({ staker, rewardCycle, network: 'mainnet' });
  return membership?.signer; // signer-manager contract principal, or undefined
}

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, called at L803, L907, L1056 and L1146).

• For a protocol bond staker, amountUstx is the STX locked with the bond (register-for-bond). For an STX-only staker, it is the STX staked.

• The comment above the map in 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).

• Pass signer as signerManager to the staker reward reads such as fetchEarnedStakerRewards.

• Resolves to undefined when the staker has no entry for the cycle (get-signer-cycle-membership).

• 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.

Reference Link

---

Signature

function fetchSignerCycleMembership(
  opts: { staker: string; rewardCycle: number } & NetworkClientParam
): Promise<{ amountUstx: bigint; signer: string } | undefined>;

opts is a NetworkClientParam plus staker and rewardCycle.

---

Returns

Promise<{ amountUstx: bigint; signer: string } | undefined>

Resolves to the membership, or undefined when there is none.

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

---

Parameters

opts.staker (required)

• Type: string

Stacks address of the staker, STX-only or protocol bond.

opts.rewardCycle (required)

• Type: number

Reward cycle to read.

opts.network (optional)

• Type: StacksNetworkName | StacksNetwork

The network to query: a name such as 'mainnet' or 'testnet', or a StacksNetwork object. Defaults to 'mainnet'.

opts.client (optional)

• Type: { baseUrl?: string; fetch?: FetchFn }

Overrides the API base URL or the fetch function, for example to query your own node. Fields you set replace the network's defaults.