StatisticsUtils

Utility helpers for retrieving statistics information.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils

stats = StatisticsUtils.get_escrow_statistics(ChainId.POLYGON_AMOY)

DailyEscrowData ¶

DailyEscrowData(
    timestamp,
    escrows_total,
    escrows_pending,
    escrows_solved,
    escrows_paid,
    escrows_cancelled,
)

Represents aggregated escrow metrics for a single day.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Day boundary timestamp.
`escrows_total`	`int`	Total number of escrows created on this day.
`escrows_pending`	`int`	Number of escrows in pending status.
`escrows_solved`	`int`	Number of escrows that were solved/completed.
`escrows_paid`	`int`	Number of escrows that were paid out.
`escrows_cancelled`	`int`	Number of escrows that were cancelled.

DailyHMTData ¶

DailyHMTData(
    timestamp,
    total_transaction_amount,
    total_transaction_count,
    daily_unique_senders,
    daily_unique_receivers,
)

Represents aggregated HMT transfer metrics for a single day.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Day boundary timestamp.
`total_transaction_amount`	`int`	Total amount transferred on this day.
`total_transaction_count`	`int`	Number of transfer transactions.
`daily_unique_senders`	`int`	Number of unique addresses sending tokens.
`daily_unique_receivers`	`int`	Number of unique addresses receiving tokens.

DailyPaymentData ¶

DailyPaymentData(timestamp, total_count)

Represents aggregated payment metrics for a single day.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Day boundary timestamp.
`total_count`	`int`	Number of payment transactions.

DailyWorkerData ¶

DailyWorkerData(timestamp, active_workers)

Represents aggregated worker metrics for a single day.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Day boundary timestamp.
`active_workers`	`int`	Number of active workers on this day.

EscrowStatistics ¶

EscrowStatistics(total_escrows, daily_escrows_data)

Aggregate escrow statistics data.

Attributes:

Name	Type	Description
`total_escrows`	`int`	Total number of escrows across all time.
`daily_escrows_data`	`List[DailyEscrowData]`	Daily breakdown of escrow metrics.

HMTHolder ¶

HMTHolder(address, balance)

Represents an HMT token holder.

Attributes:

Name	Type	Description
`address`	`str`	Ethereum address of the holder.
`balance`	`int`	Token balance in smallest unit.

HMTHoldersParam ¶

HMTHoldersParam(address=None, order_direction='asc')

Filter parameters for querying HMT token holders.

Attributes:

Name	Type	Description
`address`	`Optional[str]`	Optional holder address to filter by.
`order_direction`	`str`	Sort direction - either "asc" or "desc".

HMTStatistics ¶

HMTStatistics(
    total_transfer_amount,
    total_transfer_count,
    total_holders,
)

Aggregate HMT token statistics.

Attributes:

Name	Type	Description
`total_transfer_amount`	`int`	Total amount transferred across all time.
`total_transfer_count`	`int`	Total number of transfer transactions.
`total_holders`	`int`	Total number of token holders.

PaymentStatistics ¶

PaymentStatistics(daily_payments_data)

Aggregate payment statistics data.

Attributes:

Name	Type	Description
`daily_payments_data`	`List[DailyPaymentData]`	Daily breakdown of payment metrics.

StatisticsUtils ¶

Utility class providing statistical data retrieval functions.

This class offers static methods to fetch various statistics from the Human Protocol subgraph, including escrow metrics, worker activity, payment data, and HMT token statistics.

get_escrow_statistics `staticmethod` ¶

get_escrow_statistics(
    chain_id, filter=StatisticsFilter(), options=None
)

Retrieve escrow statistics for a given date range.

Fetches aggregate escrow data including total counts and daily breakdowns of escrow creation and status changes.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve statistics from.	required
`filter`	`StatisticsFilter`	Date range and pagination filter. Defaults to all-time data.	`StatisticsFilter()`
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`EscrowStatistics`	Escrow statistics including total count and daily data.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils
from human_protocol_sdk.filter import StatisticsFilter
import datetime

# Get all-time statistics
stats = StatisticsUtils.get_escrow_statistics(ChainId.POLYGON_AMOY)
print(f"Total escrows: {stats.total_escrows}")

# Get statistics for specific date range
stats = StatisticsUtils.get_escrow_statistics(
    ChainId.POLYGON_AMOY,
    StatisticsFilter(
        date_from=datetime.datetime(2023, 5, 8),
        date_to=datetime.datetime(2023, 6, 8),
    )
)
for day_data in stats.daily_escrows_data:
    print(f"{day_data.timestamp}: {day_data.escrows_total} escrows")

get_hmt_daily_data `staticmethod` ¶

get_hmt_daily_data(
    chain_id, filter=StatisticsFilter(), options=None
)

Retrieve daily HMT token transfer statistics for a given date range.

Fetches daily metrics about HMT token transfers including amounts, counts, and unique participants.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve statistics from.	required
`filter`	`StatisticsFilter`	Date range and pagination filter. Defaults to all-time data.	`StatisticsFilter()`
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`List[DailyHMTData]`	List of daily HMT transfer statistics.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils
from human_protocol_sdk.filter import StatisticsFilter
import datetime

daily_data = StatisticsUtils.get_hmt_daily_data(
    ChainId.POLYGON_AMOY,
    StatisticsFilter(
        date_from=datetime.datetime(2023, 5, 8),
        date_to=datetime.datetime(2023, 6, 8),
    )
)
for day in daily_data:
    print(f"{day.timestamp}:")
    print(f"  Transfers: {day.total_transaction_count}")
    print(f"  Amount: {day.total_transaction_amount}")
    print(f"  Unique senders: {day.daily_unique_senders}")

get_hmt_holders `staticmethod` ¶

get_hmt_holders(
    chain_id, param=HMTHoldersParam(), options=None
)

Retrieve HMT token holders with optional filters and ordering.

Fetches a list of addresses holding HMT tokens with their balances.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve holder data from.	required
`param`	`HMTHoldersParam`	Filter parameters and sort preferences.	`HMTHoldersParam()`
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`List[HMTHolder]`	List of token holders with addresses and balances.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils, HMTHoldersParam

# Get all holders sorted by balance ascending
holders = StatisticsUtils.get_hmt_holders(ChainId.POLYGON_AMOY)
for holder in holders:
    print(f"{holder.address}: {holder.balance}")

# Get specific holder
holders = StatisticsUtils.get_hmt_holders(
    ChainId.POLYGON_AMOY,
    HMTHoldersParam(
        address="0x123...",
        order_direction="desc",
    )
)

get_hmt_statistics `staticmethod` ¶

get_hmt_statistics(chain_id, options=None)

Retrieve aggregate HMT token statistics.

Fetches overall HMT token metrics including total transfers and holder counts.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve statistics from.	required
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`HMTStatistics`	Aggregate HMT token statistics.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils

stats = StatisticsUtils.get_hmt_statistics(ChainId.POLYGON_AMOY)
print(f"Total holders: {stats.total_holders}")
print(f"Total transfers: {stats.total_transfer_count}")
print(f"Total amount transferred: {stats.total_transfer_amount}")

get_payment_statistics `staticmethod` ¶

get_payment_statistics(
    chain_id, filter=StatisticsFilter(), options=None
)

Retrieve payment statistics for a given date range.

Fetches daily payment metrics including total amounts paid, transaction counts, and average payment per worker.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve statistics from.	required
`filter`	`StatisticsFilter`	Date range and pagination filter. Defaults to all-time data.	`StatisticsFilter()`
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`PaymentStatistics`	Payment statistics with daily breakdown.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils
from human_protocol_sdk.filter import StatisticsFilter
import datetime

stats = StatisticsUtils.get_payment_statistics(
    ChainId.POLYGON_AMOY,
    StatisticsFilter(
        date_from=datetime.datetime(2023, 5, 8),
        date_to=datetime.datetime(2023, 6, 8),
    )
)
for day_data in stats.daily_payments_data:
    print(f"{day_data.total_count}: {day_data.total_count} payments")

get_worker_statistics `staticmethod` ¶

get_worker_statistics(
    chain_id, filter=StatisticsFilter(), options=None
)

Retrieve worker activity statistics for a given date range.

Fetches daily worker activity metrics showing the number of active workers participating in escrows.

Parameters:

Name	Type	Description	Default
`chain_id`	`ChainId`	Network to retrieve statistics from.	required
`filter`	`StatisticsFilter`	Date range and pagination filter. Defaults to all-time data.	`StatisticsFilter()`
`options`	`Optional[SubgraphOptions]`	Optional configuration for subgraph requests.	`None`

Returns:

Type	Description
`WorkerStatistics`	Worker statistics with daily activity breakdown.

Raises:

Type	Description
`StatisticsUtilsError`	If the chain ID is invalid or network configuration is missing.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.statistics import StatisticsUtils
from human_protocol_sdk.filter import StatisticsFilter
import datetime

stats = StatisticsUtils.get_worker_statistics(
    ChainId.POLYGON_AMOY,
    StatisticsFilter(
        date_from=datetime.datetime(2023, 5, 8),
        date_to=datetime.datetime(2023, 6, 8),
    )
)
for day_data in stats.daily_workers_data:
    print(f"{day_data.timestamp}: {day_data.active_workers} workers")

StatisticsUtilsError ¶

Bases: Exception

Exception raised when errors occur during statistics operations.

WorkerStatistics ¶

WorkerStatistics(daily_workers_data)

Aggregate worker statistics data.

Attributes:

Name	Type	Description
`daily_workers_data`	`List[DailyWorkerData]`	Daily breakdown of worker metrics.

StatisticsUtils

DailyEscrowData ¶

DailyHMTData ¶

DailyPaymentData ¶

DailyWorkerData ¶

EscrowStatistics ¶

HMTHolder ¶

HMTHoldersParam ¶

HMTStatistics ¶

PaymentStatistics ¶

StatisticsUtils ¶

get_escrow_statistics staticmethod ¶

get_hmt_daily_data staticmethod ¶

get_hmt_holders staticmethod ¶

get_hmt_statistics staticmethod ¶

get_payment_statistics staticmethod ¶

get_worker_statistics staticmethod ¶

StatisticsUtilsError ¶

WorkerStatistics ¶

get_escrow_statistics `staticmethod` ¶

get_hmt_daily_data `staticmethod` ¶

get_hmt_holders `staticmethod` ¶

get_hmt_statistics `staticmethod` ¶

get_payment_statistics `staticmethod` ¶

get_worker_statistics `staticmethod` ¶