TransactionUtils

Utility helpers for transaction-related queries.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.transaction import TransactionUtils, TransactionFilter

TransactionUtils.get_transactions(
    TransactionFilter(
        chain_id=ChainId.POLYGON_AMOY,
        from_address="0x1234567890123456789012345678901234567890",
        to_address="0x0987654321098765432109876543210987654321",
        start_date=datetime.datetime(2023, 5, 8),
        end_date=datetime.datetime(2023, 6, 8),
    )
)

InternalTransaction

InternalTransaction(
    from_address,
    to_address,
    value,
    method,
    receiver,
    escrow,
    token,
)

Represents an internal transaction within a parent transaction.

Internal transactions are contract-to-contract calls that occur within the execution of a main transaction.

Attributes:

Name	Type	Description
from_address	str	Source address of the internal transaction.
to_address	str	Destination address of the internal transaction.
value	int	Value transferred in token's smallest unit.
method	str	Method signature called in the internal transaction.
receiver	Optional[str]	Receiver address if applicable.
escrow	Optional[str]	Escrow address if the transaction involves an escrow.
token	Optional[str]	Token address if the transaction involves a token transfer.

TransactionData

TransactionData(
    chain_id,
    block,
    tx_hash,
    from_address,
    to_address,
    timestamp,
    value,
    method,
    receiver,
    escrow,
    token,
    internal_transactions,
)

Represents on-chain transaction data retrieved from the subgraph.

Attributes:

Name	Type	Description
chain_id	ChainId	Chain where the transaction was executed.
block	int	Block number containing the transaction.
tx_hash	str	Transaction hash.
from_address	str	Sender address.
to_address	str	Recipient address (contract or EOA).
timestamp	int	Transaction timestamp in milliseconds.
value	int	Value transferred in the main transaction.
method	str	Method signature of the transaction.
receiver	Optional[str]	Receiver address if applicable.
escrow	Optional[str]	Escrow address if the transaction involves an escrow.
token	Optional[str]	Token address if the transaction involves a token transfer.
internal_transactions	List[InternalTransaction]	List of internal transactions.

TransactionUtils

Utility class providing transaction query functions from the subgraph.

This class offers static methods to fetch on-chain transaction data including individual transactions by hash and filtered transaction lists with support for internal transactions.

get_transaction staticmethod

get_transaction(chain_id, hash, options=None)

Retrieve a single transaction by its hash.

Fetches detailed transaction information including internal transactions from the subgraph.

Parameters:

Name	Type	Description	Default
chain_id	ChainId	Network where the transaction was executed.	required
hash	str	Transaction hash to look up.	required
options	Optional[SubgraphOptions]	Optional configuration for subgraph requests.	None

Returns:

Type	Description
Optional[TransactionData]	Transaction data if found, otherwise None.

Raises:

Type	Description
TransactionUtilsError	If the chain ID is not supported.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.transaction import TransactionUtils

tx = TransactionUtils.get_transaction(
    ChainId.POLYGON_AMOY,
    "0x1234567890123456789012345678901234567890abcdef1234567890abcdef12",
)
if tx:
    print(f"Block: {tx.block}")
    print(f"From: {tx.from_address}")
    print(f"To: {tx.to_address}")
    print(f"Value: {tx.value}")
    print(f"Internal txs: {len(tx.internal_transactions)}")

get_transactions staticmethod

get_transactions(filter, options=None)

Retrieve a list of transactions matching the provided filter criteria.

Queries the subgraph for transactions that match the specified parameters including addresses, date/block ranges, method signatures, and related contracts.

Parameters:

Name	Type	Description	Default
filter	TransactionFilter	Filter parameters including chain ID, sender/recipient addresses, date/block ranges, method signature, escrow address, token address, pagination, and sorting options.	required
options	Optional[SubgraphOptions]	Optional configuration for subgraph requests.	None

Returns:

Type	Description
List[TransactionData]	A list of transactions matching the filter criteria. Returns an empty list if no matches are found.

Raises:

Type	Description
TransactionUtilsError	If the chain ID is not supported.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.transaction import TransactionUtils, TransactionFilter
import datetime

# Get all transactions from a specific address
txs = TransactionUtils.get_transactions(
    TransactionFilter(
        chain_id=ChainId.POLYGON_AMOY,
        from_address="0x1234567890123456789012345678901234567890",
    )
)

# Get transactions within a date range with method filter
txs = TransactionUtils.get_transactions(
    TransactionFilter(
        chain_id=ChainId.POLYGON_AMOY,
        from_address="0x1234567890123456789012345678901234567890",
        to_address="0x0987654321098765432109876543210987654321",
        method="transfer",
        start_date=datetime.datetime(2023, 5, 8),
        end_date=datetime.datetime(2023, 6, 8),
    )
)

# Get transactions involving specific escrow
txs = TransactionUtils.get_transactions(
    TransactionFilter(
        chain_id=ChainId.POLYGON_AMOY,
        escrow="0x0987654321098765432109876543210987654321",
        start_block=1000000,
        end_block=2000000,
    )
)

for tx in txs:
    print(f"{tx.tx_hash}: {tx.method} - {tx.value}")

TransactionUtilsError

Bases: Exception

Exception raised when transaction lookup or query operations fail.