EscrowClient

Client to perform actions on Escrow contracts and obtain information from the contracts.

Selects the network based on the Web3 chain id. Configure Web3 with an account and signer middleware for writes; read operations work without a signer.

Examples:

With signer:

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.escrow import EscrowClient

def get_w3_with_priv_key(priv_key: str):
    w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
    gas_payer = w3.eth.account.from_key(priv_key)
    w3.eth.default_account = gas_payer.address
    w3.middleware_onion.inject(
        SignAndSendRawMiddlewareBuilder.build(priv_key),
        'SignAndSendRawMiddlewareBuilder',
        layer=0,
    )
    return (w3, gas_payer)

(w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
escrow_client = EscrowClient(w3)

Read-only:

from eth_typing import URI
from web3 import Web3
from web3.providers.auto import load_provider_from_uri

from human_protocol_sdk.escrow import EscrowClient

w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
escrow_client = EscrowClient(w3)

EscrowCancel ¶

EscrowCancel(tx_hash, amount_refunded)

Represents the result of an escrow cancellation transaction.

Attributes:

Name	Type	Description
`txHash`	`str`	The hash of the transaction that cancelled the escrow.
`amountRefunded`	`int`	The amount refunded during the escrow cancellation.

EscrowClient ¶

EscrowClient(web3)

A client for interacting with escrow smart contracts.

This client provides methods to create, fund, configure, and manage escrow contracts on the Human Protocol network. It handles transaction signing, validation, and event processing for escrow operations.

Attributes:

Name	Type	Description
`w3`	`Web3`	Web3 instance configured for the target network.
`network`	`dict`	Network configuration for the current chain.
`factory_contract`	`Contract`	Contract instance for the escrow factory.

Initialize an EscrowClient instance.

Parameters:

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

Raises:

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

bulk_payout ¶

bulk_payout(
    escrow_address,
    recipients,
    amounts,
    final_results_url,
    final_results_hash,
    payout_id,
    force_complete,
    tx_options=None,
)

Distribute payouts to recipients and set final results.

Performs bulk payment distribution to multiple recipients and records the final results URL and hash.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required
`recipients`	`List[str]`	List of recipient addresses.	required
`amounts`	`List[int]`	Token amounts for each recipient (in token's smallest unit).	required
`final_results_url`	`str`	Final results file URL.	required
`final_results_hash`	`str`	Final results file hash.	required
`payout_id`	`Union[str, int]`	Payout identifier. String for newer contracts, integer transaction ID for older contracts.	required
`force_complete`	`bool`	Whether to force completion after payout (if supported).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If validation fails or the transaction reverts.

Example

escrow_client.bulk_payout(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    ["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],
    [Web3.to_wei(5, "ether")],
    "http://localhost/results.json",
    "b5dad76bf6772c0f07fd5e048f6e75a5f86ee079",
    payout_id="payout-1",
    force_complete=True,
)

cancel ¶

cancel(escrow_address, tx_options=None)

Cancel the specified escrow and refund the balance.

Finalizes the cancellation and transfers remaining funds to the canceler.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow to cancel.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`EscrowCancel`	Cancellation details including transaction hash and refunded amount.

Raises:

Type	Description
`EscrowClientError`	If validation fails or the transfer event is missing.

Example

escrow_cancel_data = escrow_client.cancel(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f"
)

complete ¶

complete(escrow_address, tx_options=None)

Set the status of an escrow to completed.

Marks the escrow as completed, preventing further modifications.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow to complete.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If validation fails or the transaction reverts.

Example

escrow_client.complete("0x62dD51230A30401C455c8398d06F85e4EaB6309f")

create_bulk_payout_transaction ¶

create_bulk_payout_transaction(
    escrow_address,
    recipients,
    amounts,
    final_results_url,
    final_results_hash,
    payoutId,
    force_complete=False,
    tx_options=None,
)

Prepare an unsigned bulk payout transaction.

Creates a transaction dictionary that can be signed and sent externally. Useful for offline signing or custom transaction handling.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required
`recipients`	`List[str]`	List of recipient addresses.	required
`amounts`	`List[int]`	Token amounts for each recipient (in token's smallest unit).	required
`final_results_url`	`str`	Final results file URL.	required
`final_results_hash`	`str`	Final results file hash.	required
`payoutId`	`str`	Unique identifier for the payout (string signature).	required
`force_complete`	`Optional[bool]`	Whether to force completion after payout. Defaults to False.	`False`
`tx_options`	`Optional[TxParams]`	Optional transaction parameters to seed the transaction.	`None`

Returns:

Type	Description
`TxParams`	A populated transaction dictionary ready to sign and send, including nonce, gas estimate, gas price/fees, and chain ID.

Raises:

Type	Description
`EscrowClientError`	If validation fails.

Example

tx = escrow_client.create_bulk_payout_transaction(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    ["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],
    [Web3.to_wei(5, "ether")],
    "http://localhost/results.json",
    "b5dad76bf6772c0f07fd5e048f6e75a5f86ee079",
    "payout-1",
    force_complete=False,
)
signed = w3.eth.account.sign_transaction(tx, "PRIVATE_KEY")
w3.eth.send_raw_transaction(signed.raw_transaction)

create_escrow ¶

create_escrow(
    token_address, job_requester_id, tx_options=None
)

Create a new escrow contract.

Parameters:

Name	Type	Description	Default
`token_address`	`str`	ERC-20 token address to fund the escrow.	required
`job_requester_id`	`str`	Off-chain identifier for the job requester.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`str`	Address of the newly created escrow contract.

Raises:

Type	Description
`EscrowClientError`	If the token address is invalid or the transaction fails.

Example

escrow_address = escrow_client.create_escrow(
    "0x1234567890abcdef1234567890abcdef12345678",
    "job-requester",
)

create_fund_and_setup_escrow ¶

create_fund_and_setup_escrow(
    token_address,
    amount,
    job_requester_id,
    escrow_config,
    tx_options=None,
)

Create, fund, and configure an escrow in a single transaction.

This is a convenience method that combines escrow creation, funding, and setup into one atomic operation.

Parameters:

Name	Type	Description	Default
`token_address`	`str`	ERC-20 token address to fund the escrow.	required
`amount`	`int`	Token amount to fund (in token's smallest unit).	required
`job_requester_id`	`str`	Off-chain identifier for the job requester.	required
`escrow_config`	`EscrowConfig`	Escrow configuration parameters including oracle addresses and manifest data.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`str`	Address of the newly created and configured escrow contract.

Raises:

Type	Description
`EscrowClientError`	If inputs are invalid or the transaction fails.

Example

escrow_address = escrow_client.create_fund_and_setup_escrow(
    "0x1234567890abcdef1234567890abcdef12345678",
    Web3.to_wei(5, "ether"),
    "job-requester",
    escrow_config,
)

ensure_correct_bulk_payout_input ¶

ensure_correct_bulk_payout_input(
    escrow_address,
    recipients,
    amounts,
    final_results_url,
    final_results_hash,
)

Validate inputs for bulk payout operations.

Performs comprehensive validation of all bulk payout parameters including address validity, array lengths, amounts, and escrow balance.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required
`recipients`	`List[str]`	List of recipient addresses.	required
`amounts`	`List[int]`	Token amounts for each recipient (in token's smallest unit).	required
`final_results_url`	`str`	Final results file URL.	required
`final_results_hash`	`str`	Final results file hash.	required

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If any parameter is invalid, including: - Invalid escrow or recipient addresses - Empty or mismatched arrays - Too many recipients (exceeds maximum) - Invalid amounts (negative, zero, or exceeding escrow balance) - Invalid URL or hash

fund ¶

fund(escrow_address, amount, tx_options=None)

Add funds to the escrow.

Transfers tokens from the caller's account to the escrow contract.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow to fund.	required
`amount`	`int`	Amount of tokens to transfer (must be positive, in token's smallest unit).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If inputs are invalid or the transfer fails.

Example

amount = Web3.to_wei(5, "ether")
escrow_client.fund("0x62dD51230A30401C455c8398d06F85e4EaB6309f", amount)

get_balance ¶

get_balance(escrow_address)

Get the remaining balance for a specified escrow.

Queries the current available balance in the escrow that can be used for payouts.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`int`	Remaining escrow balance in token's smallest unit.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_exchange_oracle_address ¶

get_exchange_oracle_address(escrow_address)

Get the exchange oracle address of the escrow.

Retrieves the address of the oracle responsible for exchange rate data.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Exchange oracle address.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_factory_address ¶

get_factory_address(escrow_address)

Get the escrow factory address of the escrow.

Retrieves the address of the factory contract that created this escrow.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Escrow factory address.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_intermediate_results_hash ¶

get_intermediate_results_hash(escrow_address)

Get the intermediate results file hash.

Retrieves the hash of the intermediate results file.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Intermediate results file hash.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_intermediate_results_url ¶

get_intermediate_results_url(escrow_address)

Get the intermediate results file URL.

Retrieves the URL where intermediate results are stored.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Intermediate results URL.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_job_launcher_address ¶

get_job_launcher_address(escrow_address)

Get the job launcher address of the escrow.

Retrieves the address of the account that launched/created this escrow.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Job launcher address.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_manifest ¶

get_manifest(escrow_address)

Get the manifest data.

Retrieves the manifest URL or JSON string that defines the job requirements.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Name	Type	Description
`str`	`str`	Manifest data (URL or JSON string).

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_manifest_hash ¶

get_manifest_hash(escrow_address)

Get the manifest file hash.

Retrieves the hash of the manifest that defines the job requirements.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Manifest file hash.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_recording_oracle_address ¶

get_recording_oracle_address(escrow_address)

Get the recording oracle address of the escrow.

Retrieves the address of the oracle responsible for recording job results.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Recording oracle address.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_reputation_oracle_address ¶

get_reputation_oracle_address(escrow_address)

Get the reputation oracle address of the escrow.

Retrieves the address of the oracle responsible for reputation tracking.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Reputation oracle address.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_reserved_funds ¶

get_reserved_funds(escrow_address)

Get the reserved funds for a specified escrow.

Queries the amount of funds that have been reserved for future payouts.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`int`	Reserved funds amount in token's smallest unit.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_results_url ¶

get_results_url(escrow_address)

Get the final results file URL.

Retrieves the URL where final results are stored.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Final results URL.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_status ¶

get_status(escrow_address)

Get the current status of the escrow.

Retrieves the current state of the escrow (e.g., Launched, Pending, Completed).

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`Status`	Current escrow status enum value.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

get_token_address ¶

get_token_address(escrow_address)

Get the token address used to fund the escrow.

Retrieves the ERC-20 token contract address used for this escrow.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required

Returns:

Type	Description
`str`	Token address used to fund the escrow.

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid.

request_cancellation ¶

request_cancellation(escrow_address, tx_options=None)

Request cancellation of the specified escrow.

Initiates the cancellation process. If the escrow is expired, it may finalize immediately; otherwise, it transitions to ToCancel status.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow to request cancellation.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If validation fails or the transaction reverts.

Example

escrow_client.request_cancellation(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f"
)

setup ¶

setup(escrow_address, escrow_config, tx_options=None)

Set escrow roles and manifest metadata.

Configures the escrow with oracle addresses and manifest information.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow contract to configure.	required
`escrow_config`	`EscrowConfig`	Escrow configuration parameters including oracle addresses and manifest data.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If the escrow address is invalid or the transaction fails.

Example

escrow_client.setup("0xYourEscrow", escrow_config)

store_results ¶

store_results(
    escrow_address,
    url,
    hash,
    funds_to_reserve=None,
    tx_options=None,
)

Store results URL and hash, with optional funds reservation.

Stores the intermediate or final results location and hash. Optionally reserves funds for future payouts.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow.	required
`url`	`str`	Results file URL.	required
`hash`	`str`	Results file hash.	required
`funds_to_reserve`	`Optional[int]`	Optional funds to reserve for payouts. If None, uses legacy signature without reservation.	`None`
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`EscrowClientError`	If validation fails or the transaction reverts.

Example

escrow_client.store_results(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    "http://localhost/results.json",
    "b5dad76bf6772c0f07fd5e048f6e75a5f86ee079",
)

withdraw ¶

withdraw(escrow_address, token_address, tx_options=None)

Withdraw additional tokens from the escrow.

Withdraws tokens (other than the primary escrow token) to the canceler's address. Useful for recovering accidentally sent tokens.

Parameters:

Name	Type	Description	Default
`escrow_address`	`str`	Address of the escrow to withdraw from.	required
`token_address`	`str`	Address of the token to withdraw.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`EscrowWithdraw`	Withdrawal details including transaction hash, token address, and amount.

Raises:

Type	Description
`EscrowClientError`	If validation fails or transfer event is missing.

Example

withdrawal = escrow_client.withdraw(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    "0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4",
)

EscrowClientError ¶

Bases: Exception

Exception raised when errors occur during escrow operations.

EscrowConfig ¶

EscrowConfig(
    recording_oracle_address,
    reputation_oracle_address,
    exchange_oracle_address,
    manifest="",
    hash="",
)

Configuration parameters for escrow setup.

Attributes:

Name	Type	Description
`recording_oracle_address`	`str`	Address of the recording oracle.
`reputation_oracle_address`	`str`	Address of the reputation oracle.
`exchange_oracle_address`	`str`	Address of the exchange oracle.
`manifest`	`str`	Manifest payload (URL or JSON string).
`hash`	`str`	Manifest file hash.

Raises:

Type	Description
`EscrowClientError`	If addresses are invalid or manifest data is invalid.

EscrowWithdraw ¶

EscrowWithdraw(tx_hash, token_address, withdrawn_amount)

Represents the result of an escrow withdrawal transaction.

Attributes:

Name	Type	Description
`txHash`	`str`	The hash of the transaction associated with the escrow withdrawal.
`token_address`	`str`	The address of the token used for the withdrawal.
`withdrawn_amount`	`int`	The amount withdrawn from the escrow.