StakingUtils

Utility helpers for staking-related queries.

StakerData ¶

StakerData(
    id,
    address,
    staked_amount,
    locked_amount,
    withdrawn_amount,
    slashed_amount,
    locked_until_timestamp,
    last_deposit_timestamp,
)

Represents staker information retrieved from the subgraph.

Attributes:

Name	Type	Description
`id`	`str`	Unique staker identifier.
`address`	`str`	Staker's Ethereum address.
`staked_amount`	`int`	Total amount staked in token's smallest unit.
`locked_amount`	`int`	Amount currently locked.
`withdrawn_amount`	`int`	Total amount withdrawn.
`slashed_amount`	`int`	Total amount slashed.
`locked_until_timestamp`	`int`	Time in milliseconds until locked amount is released.
`last_deposit_timestamp`	`int`	Last deposit time in milliseconds.

StakingUtils ¶

Utility class providing staking-related query and data retrieval functions.

This class offers static methods to fetch staker data from the Human Protocol subgraph, including individual staker details and filtered lists.

get_staker `staticmethod` ¶

get_staker(chain_id, address, options=None)

Retrieve a single staker by their address.

Fetches detailed staking information for a specific address from the subgraph.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network where the staker is registered.	required
`address`	`str`	Ethereum address of the staker.	required
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`Optional[StakerData]`	Staker data if found, otherwise `None`.

Raises:

Type	Description
`StakingUtilsError`	If the chain ID is not supported.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.staking import StakingUtils

staker = StakingUtils.get_staker(
    ChainId.POLYGON_AMOY,
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
)
if staker:
    print(f"Staked: {staker.staked_amount}")
    print(f"Locked: {staker.locked_amount}")

get_stakers `staticmethod` ¶

get_stakers(filter, options=None)

Retrieve a list of stakers matching the provided filter criteria.

Queries the subgraph for stakers that match the specified parameters including amount ranges, ordering, and pagination.

Parameters:

Name	Type	Description	Default
`filter`	`StakersFilter`	Filter parameters including chain ID, amount ranges (staked, locked, withdrawn, slashed), ordering, and pagination options.	required
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`List[StakerData]`	A list of staker records matching the filter criteria. Returns an empty list if no matches are found.

Raises:

Type	Description
`StakingUtilsError`	If the chain ID is not supported.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.staking import StakingUtils
from human_protocol_sdk.filter import StakersFilter
from web3 import Web3

stakers = StakingUtils.get_stakers(
    StakersFilter(
        chain_id=ChainId.POLYGON_AMOY,
        min_staked_amount=Web3.to_wei(100, "ether"),
    )
)
for staker in stakers:
    print(f"{staker.address}: {staker.staked_amount}")

StakingUtilsError ¶

Bases: Exception

Exception raised when staking utility operations fail.