fetchSignerSharesStakedForCycle

Calls the pox-5 get-signer-shares-staked-for-cycle read-only and returns the total shares staked with one signer-manager in one reward cycle: sats for a protocol bond, micro-STX for STX-only staking.

---

Usage

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

const { rewardCycleId } = await fetchPoxInfo({ network: 'mainnet' });
const signerManager = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-signer-manager'; // your signer-manager

// STX-only staking: micro-STX
const ustx = await fetchSignerSharesStakedForCycle({ signerManager, rewardCycle: rewardCycleId });

// Protocol bond 1: sats
const sats = await fetchSignerSharesStakedForCycle({
  signerManager,
  rewardCycle: rewardCycleId,
  bondIndex: 1,
});

Notes

• Reads the signer-shares-staked-for-cycle map through get-signer-shares-staked-for-cycle. Returns 0n when there is no entry.

• With bondIndex the value is sats; without it the value is micro-STX. The SDK sends bondIndex as (some u<bondIndex>), or none when you omit it.

• The micro-STX figure counts STX-only staking only, not STX locked in protocol bonds. pox-5 writes it only while the signer-manager has at least 50,000,000,000 micro-STX (50,000 STX, SIGNER_SET_MIN_USTX) staked to it in that cycle (L1705-L1713) and resets it to 0 when that total drops below 50,000 STX (L1546-L1558).

• For one staker's part of this total, use fetchStakerSharesStakedForCycle.

• Throws an Error if the node returns a non-2xx status (the message starts with Error calling read-only function.) or answers okay: false (the message is the node's cause).

Reference Link

---

Signature

function fetchSignerSharesStakedForCycle(
  opts: {
    signerManager: string;
    rewardCycle: number;
    bondIndex?: number;
  } & NetworkClientParam
): Promise<bigint>;

opts is a NetworkClientParam plus the fields below.

---

Returns

Promise<bigint>

The signer-manager's shares for the cycle: sats when bondIndex is set, micro-STX when it is omitted.

---

Parameters

opts.signerManager (required)

• Type: string

Contract principal of the signer-manager.

opts.rewardCycle (required)

• Type: number

Reward cycle to read.

opts.bondIndex (optional)

• Type: number

Protocol bond index. Set it to read the bond's sats shares; omit it to read micro-STX shares from STX-only staking.

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.