fetchEarned

Reads the sBTC rewards, in sats, that a signer-manager can claim for one tranche of one reward cycle. Wraps the pox-5 read-only get-earned.

---

Usage

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

const { rewardCycleId: rewardCycle } = await fetchPoxInfo({ network: 'mainnet' });
// Any signer-manager in this cycle's signer set
const signerManager = await fetchSignerSetFirstItem({ rewardCycle, network: 'mainnet' });

if (signerManager) {
  // STX-only staking tranche. Add bondIndex to read a protocol bond.
  const value = await fetchEarned({ signerManager, rewardCycle, network: 'mainnet' });
}

Notes

• get-earned returns shares * (rewardsPerToken - rewardsPerTokenSettled) / 10^18 + unclaimed for the signer-manager's share of the tranche (get-earned, compute-earned-rewards). claim-rewards settles with the same formula, so this is the amount it pays for this tranche at the current chain state (settle-rewards).

• The amount is sBTC in sats for both tranches. pox-5 pays it to the signer-manager contract in sBTC (claim-rewards).

• The value grows when calculate-rewards raises the tranche's rewards-per-token accumulator. fetchLastRewardComputeHeight tells you whether the current distribution cycle has been calculated.

• claim-rewards sums the STX-only staking tranche and the bonds passed to it, and reverts with ERR_NO_CLAIMABLE_REWARDS (u32) when the sum is 0 (claim-rewards). Read this before buildClaimRewards to skip an empty claim or to bound a post condition. The amount can change between the read and the broadcast.

• The amount belongs to the signer-manager. For one staker's part, use fetchEarnedStakerRewards.

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

Reference Link

---

Signature

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

opts is a NetworkClientParam plus signerManager, rewardCycle and bondIndex.

---

Returns

Promise<EarnedRewards>

Resolves to an EarnedRewards: a bigint amount of sBTC in sats.

---

Parameters

opts.signerManager (required)

• Type: string

Contract principal of the signer-manager, in the form <address>.<contract-name>. pox-5 keys signer state by this principal.

opts.rewardCycle (required)

• Type: number

Reward cycle to read.

opts.bondIndex (optional)

• Type: number

Protocol bond index. Set it to read that bond in the protocol bond tranche. Omit it to read the STX-only staking tranche.

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.