Skip to content

The new styling applies starting with version 5.2.0. For earlier versions, visit legacy-sdk.humanprotocol.org.

EscrowUtils

Utility helpers for escrow-related queries.

Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils, EscrowFilter, Status

print(
    EscrowUtils.get_escrows(
        EscrowFilter(
            networks=[ChainId.POLYGON_AMOY],
            status=Status.Pending,
            date_from=datetime.datetime(2023, 5, 8),
            date_to=datetime.datetime(2023, 6, 8),
        )
    )
)

CancellationRefund 

CancellationRefund(
    id,
    escrow_address,
    receiver,
    amount,
    block,
    timestamp,
    tx_hash,
)

Represents a cancellation refund event.

Attributes:

Name Type Description
id str

Unique refund identifier.
escrow_address str

Address of the escrow associated with the refund.
receiver str

Address receiving the refund.
amount int

Refunded amount in token's smallest unit.
block int

Block number where the refund was processed.
timestamp int

Refund timestamp in milliseconds.
tx_hash str

Transaction hash of the refund.

EscrowData 

EscrowData(
    chain_id,
    id,
    address,
    amount_paid,
    balance,
    count,
    factory_address,
    launcher,
    job_requester_id,
    status,
    token,
    total_funded_amount,
    created_at,
    cancellation_requested_at=None,
    final_results_url=None,
    final_results_hash=None,
    intermediate_results_url=None,
    intermediate_results_hash=None,
    manifest_hash=None,
    manifest=None,
    recording_oracle=None,
    reputation_oracle=None,
    exchange_oracle=None,
    recording_oracle_fee=None,
    reputation_oracle_fee=None,
    exchange_oracle_fee=None,
)

Represents escrow data retrieved from the subgraph.

Attributes:

Name Type Description
id str

Unique escrow identifier.
address str

Escrow contract address.
amount_paid int

Total amount paid out.
balance int

Remaining balance in the escrow.
count int

Number of payouts executed.
factory_address str

Address of the factory that created this escrow.
final_results_url Optional[str]

URL for final results file.
final_results_hash Optional[str]

Hash of final results file.
intermediate_results_url Optional[str]

URL for intermediate results file.
intermediate_results_hash Optional[str]

Hash of intermediate results file.
launcher str

Address of the job launcher.
job_requester_id Optional[str]

Off-chain job requester identifier.
manifest_hash Optional[str]

Hash of the manifest file.
manifest Optional[str]

Manifest data (URL or JSON string).
recording_oracle Optional[str]

Address of the recording oracle.
reputation_oracle Optional[str]

Address of the reputation oracle.
exchange_oracle Optional[str]

Address of the exchange oracle.
recording_oracle_fee Optional[int]

Recording oracle fee percentage.
reputation_oracle_fee Optional[int]

Reputation oracle fee percentage.
exchange_oracle_fee Optional[int]

Exchange oracle fee percentage.
status str

Current escrow status.
token str

Address of the payment token.
total_funded_amount int

Total amount funded to the escrow.
created_at int

Creation timestamp in milliseconds.
cancellation_requested_at Optional[int]

Cancellation request timestamp in milliseconds.
chain_id ChainId

Chain where the escrow is deployed.

EscrowUtils

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

This class offers static methods to fetch escrow data, status events, payouts, and cancellation refunds from the Human Protocol subgraph.

get_cancellation_refund staticmethod 

get_cancellation_refund(
    chain_id, escrow_address, options=None
)

Retrieve the cancellation refund for a specific escrow.

Fetches the cancellation refund event associated with a given escrow address. Each escrow can have at most one cancellation refund.

Parameters:

Name Type Description Default
chain_id ChainId

Network where the escrow has been deployed.

 required
escrow_address str

Address of the escrow contract.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests.

 None

Returns:

Type Description
CancellationRefund

Cancellation refund data if found, otherwise None.

Raises:

Type Description
EscrowClientError

If an unsupported chain ID or invalid escrow address is provided.
Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils

refund = EscrowUtils.get_cancellation_refund(
    ChainId.POLYGON_AMOY,
    "0x1234567890123456789012345678901234567890",
)

get_cancellation_refunds staticmethod 

get_cancellation_refunds(filter, options=None)

Fetch cancellation refund events from the subgraph.

Retrieves cancellation refund transactions for escrows based on the provided filter criteria including escrow address, receiver, and date range.

Parameters:

Name Type Description Default
filter CancellationRefundFilter

Filter parameters including chain ID, escrow address, receiver address, date range, pagination, and sorting options.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests.

 None

Returns:

Type Description
List[CancellationRefund]

A list of cancellation refunds matching the query parameters. Returns an empty list if no matches are found.

Raises:

Type Description
EscrowClientError

If an unsupported chain ID or invalid addresses are provided.
Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils
from human_protocol_sdk.filter import CancellationRefundFilter

refunds = EscrowUtils.get_cancellation_refunds(
    CancellationRefundFilter(
        chain_id=ChainId.POLYGON_AMOY,
        escrow_address="0x1234567890123456789012345678901234567890",
    )
)

get_escrow staticmethod 

get_escrow(chain_id, escrow_address, options=None)

Fetch a single escrow by its address.

Retrieves detailed information about a specific escrow contract from the subgraph.

Parameters:

Name Type Description Default
chain_id ChainId

Network where the escrow has been deployed.

 required
escrow_address str

Address of the escrow contract.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests.

 None

Returns:

Type Description
Optional[EscrowData]

Escrow data if found, otherwise None.

Raises:

Type Description
EscrowClientError

If the chain ID is invalid or the escrow address is malformed.
Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils

print(
    EscrowUtils.get_escrow(
        ChainId.POLYGON_AMOY,
        "0x1234567890123456789012345678901234567890",
    )
)

get_escrows staticmethod 

get_escrows(filter, options=None)

Retrieve a list of escrows matching the provided filter criteria.

Queries the subgraph for escrow contracts that match the specified parameters including status, date range, and oracle addresses.

Parameters:

Name Type Description Default
filter EscrowFilter

Filter parameters including chain ID, status, date range, and oracle addresses.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests such as custom endpoints or timeout settings.

 None

Returns:

Type Description
List[EscrowData]

A list of escrow records matching the filter criteria. Returns an empty list if no matches are found.
Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils, EscrowFilter, Status

print(
    EscrowUtils.get_escrows(
        EscrowFilter(
            networks=[ChainId.POLYGON_AMOY],
            status=Status.Pending,
            date_from=datetime.datetime(2023, 5, 8),
            date_to=datetime.datetime(2023, 6, 8),
        )
    )
)

get_payouts staticmethod 

get_payouts(filter, options=None)

Fetch payout records from the subgraph.

Retrieves payout transactions for escrows based on the provided filter criteria including escrow address, recipient, and date range.

Parameters:

Name Type Description Default
filter PayoutFilter

Filter parameters including chain ID, escrow address, recipient address, date range, pagination, and sorting options.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests.

 None

Returns:

Type Description
List[Payout]

A list of payout records matching the query parameters. Returns an empty list if no matches are found.

Raises:

Type Description
EscrowClientError

If an unsupported chain ID or invalid addresses are provided.
Example 
from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.escrow import EscrowUtils
from human_protocol_sdk.filter import PayoutFilter

payouts = EscrowUtils.get_payouts(
    PayoutFilter(
        chain_id=ChainId.POLYGON_AMOY,
        escrow_address="0x1234567890123456789012345678901234567890",
    )
)

get_status_events staticmethod 

get_status_events(filter, options=None)

Retrieve status change events for escrows.

Queries the subgraph for escrow status change events within the specified date range and matching the provided statuses.

Parameters:

Name Type Description Default
filter StatusEventFilter

Filter parameters including chain ID, statuses, date range, and oracle addresses.

 required
options Optional[SubgraphOptions]

Optional configuration for subgraph requests.

 None

Returns:

Type Description
List[StatusEvent]

A list of status change events matching the filter criteria. Returns an empty list if no matches are found.

Raises:

Type Description
EscrowClientError

If an unsupported chain ID or invalid launcher address is provided.
Example 
from human_protocol_sdk.constants import ChainId, Status
from human_protocol_sdk.escrow import EscrowUtils
from human_protocol_sdk.filter import StatusEventFilter
import datetime

events = EscrowUtils.get_status_events(
    StatusEventFilter(
        chain_id=ChainId.POLYGON_AMOY,
        statuses=[Status.Pending, Status.Completed],
        date_from=datetime.datetime(2023, 5, 8),
        date_to=datetime.datetime(2023, 6, 8),
    )
)

Payout 

Payout(id, escrow_address, recipient, amount, created_at)

Represents a payout distributed by an escrow.

Attributes:

Name Type Description
id str

Unique payout identifier.
escrow_address str

Address of the escrow that executed the payout.
recipient str

Address of the payout recipient.
amount int

Amount paid in token's smallest unit.
created_at int

Payout creation timestamp in milliseconds.

StatusEvent 

StatusEvent(
    timestamp,
    status,
    chain_id,
    escrow_address,
    block,
    tx_hash,
)

Represents an escrow status change event.

Attributes:

Name Type Description
timestamp int

Event timestamp in milliseconds.
status str

The new status of the escrow.
chain_id ChainId

Chain where the event occurred.
escrow_address str

Address of the escrow that changed status.