StakingClient

Client for staking actions on HUMAN Protocol.

Internally selects network config based on the Web3 chain id.

Example

from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri
from human_protocol_sdk.staking import StakingClient

w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key("YOUR_PRIVATE_KEY")
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
    SignAndSendRawMiddlewareBuilder.build("YOUR_PRIVATE_KEY"),
    "SignAndSendRawMiddlewareBuilder",
    layer=0,
)
staking_client = StakingClient(w3)

StakingClient ¶

StakingClient(w3)

Client for interacting with the staking smart contract.

This client provides methods to stake, unstake, withdraw, and slash HMT tokens, as well as query staker information on the Human Protocol network.

Attributes:

Name	Type	Description
`w3`	`Web3`	Web3 instance configured for the target network.
`network`	`dict`	Network configuration for the current chain.
`hmtoken_contract`	`Contract`	Contract instance for the HMT token.
`factory_contract`	`Contract`	Contract instance for the escrow factory.
`staking_contract`	`Contract`	Contract instance for the staking contract.

Initialize a StakingClient instance.

Parameters:

Name	Type	Description	Default
`w3`	`Web3`	Web3 instance configured for the target network. Must have a valid provider and chain ID.	required

Raises:

Type	Description
`StakingClientError`	If chain ID is invalid, network configuration is missing, or network configuration is empty.

Example

from eth_typing import URI
from web3 import Web3
from web3.providers.auto import load_provider_from_uri
from human_protocol_sdk.staking import StakingClient

w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
staking_client = StakingClient(w3)

approve_stake ¶

approve_stake(amount, tx_options=None)

Approve HMT tokens for staking.

Grants the staking contract permission to transfer HMT tokens from the caller's account. This must be called before staking.

Parameters:

Name	Type	Description	Default
`amount`	`int`	Amount of HMT tokens to approve in token's smallest unit (must be greater than 0).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`StakingClientError`	If the amount is not positive or the transaction fails.

Example

from web3 import Web3

amount = Web3.to_wei(100, "ether")
staking_client.approve_stake(amount)

get_staker_info ¶

get_staker_info(staker_address)

Retrieve comprehensive staking information for a staker.

Fetches on-chain staking data including staked amount, locked amount, lock expiration, and withdrawable amount.

Parameters:

Name	Type	Description	Default
`staker_address`	`str`	Ethereum address of the staker.	required

Returns:

Type	Description
`dict`	Staker info with keys: `stakedAmount` (int): Total staked amount. `lockedAmount` (int): Currently locked amount. `lockedUntil` (int): Block number until tokens are locked (0 if unlocked). `withdrawableAmount` (int): Amount available for withdrawal.

Raises:

Type	Description
`StakingClientError`	If the staker address is invalid or the query fails.

Example

staking_info = staking_client.get_staker_info("0xYourStakerAddress")
print(f"Staked: {staking_info['stakedAmount']}")
print(f"Locked: {staking_info['lockedAmount']}")
print(f"Withdrawable: {staking_info['withdrawableAmount']}")

slash ¶

slash(
    slasher, staker, escrow_address, amount, tx_options=None
)

Slash a staker's stake for a given escrow.

Penalizes a staker by reducing their staked amount and distributing rewards to the slasher for detecting misbehavior or violations.

Parameters:

Name	Type	Description	Default
`slasher`	`str`	Address of the entity performing the slash (receives rewards).	required
`staker`	`str`	Address of the staker to be slashed.	required
`escrow_address`	`str`	Address of the escrow associated with the violation.	required
`amount`	`int`	Amount to slash in token's smallest unit (must be greater than 0 and within staker's allocation to the escrow).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`StakingClientError`	If the amount is invalid, escrow address is invalid, or the transaction fails.

Example

staking_client.slash(
    "0xSlasherAddress",
    "0xStakerAddress",
    "0xEscrowAddress",
    Web3.to_wei(10, "ether"),
)

stake ¶

stake(amount, tx_options=None)

Stake HMT tokens.

Deposits HMT tokens into the staking contract. The tokens must be approved first using approve_stake().

Parameters:

Name	Type	Description	Default
`amount`	`int`	Amount of HMT tokens to stake in token's smallest unit (must be greater than 0 and within approved/balance limits).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`StakingClientError`	If the amount is invalid or the transaction fails.

Example

from eth_typing import URI
from web3 import Web3
from web3.middleware import SignAndSendRawMiddlewareBuilder
from web3.providers.auto import load_provider_from_uri
from human_protocol_sdk.staking import StakingClient

w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
gas_payer = w3.eth.account.from_key("YOUR_PRIVATE_KEY")
w3.eth.default_account = gas_payer.address
w3.middleware_onion.inject(
    SignAndSendRawMiddlewareBuilder.build("YOUR_PRIVATE_KEY"),
    "SignAndSendRawMiddlewareBuilder",
    layer=0,
)

staking_client = StakingClient(w3)
amount = Web3.to_wei(5, "ether")
staking_client.approve_stake(amount)
staking_client.stake(amount)

unstake ¶

unstake(amount, tx_options=None)

Unstake HMT tokens.

Initiates the unstaking process for the specified amount. The tokens will be locked for a period before they can be withdrawn.

Parameters:

Name	Type	Description	Default
`amount`	`int`	Amount of HMT tokens to unstake in token's smallest unit (must be greater than 0 and less than or equal to unlocked staked amount).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`StakingClientError`	If the amount is invalid or the transaction fails.

Example

amount = Web3.to_wei(5, "ether")
staking_client.unstake(amount)

withdraw ¶

withdraw(tx_options=None)

Withdraw unlocked unstaked HMT tokens.

Withdraws all available unstaked tokens that have completed the unlocking period and transfers them back to the caller's account.

Parameters:

Name	Type	Description	Default
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`StakingClientError`	If the transaction fails or no tokens are available to withdraw.

Example

staking_client.withdraw()

StakingClientError ¶

Bases: Exception

Exception raised when errors occur during staking operations.