KVStoreUtils

Utility helpers for KVStore queries.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.kvstore import KVStoreUtils

print(
    KVStoreUtils.get_kvstore_data(
        ChainId.POLYGON_AMOY,
        "0x15d34aaf54267db7d7c367839aaf71a00a2c6a65",
    )
)

KVStoreData

KVStoreData(key, value)

Represents a key-value pair from the KVStore.

Attributes:

Name	Type	Description
key	str	The key of the key-value pair.
value	str	The value associated with the key.

KVStoreUtils

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

This class offers static methods to fetch KVStore data from the HUMAN Protocol subgraph, including individual key-value pairs, bulk data, and specialized methods for URLs with hash verification and public keys.

get staticmethod

get(chain_id, address, key, options=None)

Get the value of a specific key for an address.

Queries the subgraph for a specific key-value pair associated with an address.

Parameters:

Name	Type	Description	Default
chain_id	ChainId	Network where the KVStore data has been stored.	required
address	str	Ethereum address associated with the key-value pair.	required
key	str	Key to retrieve (cannot be empty).	required
options	Optional[SubgraphOptions]	Optional configuration for subgraph requests.	None

Returns:

Type	Description
str	Value for the key if it exists.

Raises:

Type	Description
KVStoreClientError	If the key is empty, address is invalid, chain ID is invalid, or the key is not found for the address.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.kvstore import KVStoreUtils

role = KVStoreUtils.get(
    ChainId.POLYGON_AMOY,
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    "role",
)
print(role)

get_file_url_and_verify_hash staticmethod

get_file_url_and_verify_hash(
    chain_id, address, key="url", options=None
)

Get a stored URL and verify its content hash.

Retrieves a URL from KVStore, fetches its content, and verifies that the content hash matches the stored hash value. This ensures the file content has not been tampered with.

Parameters:

Name	Type	Description	Default
chain_id	ChainId	Network where the KVStore data has been stored.	required
address	str	Address from which to get the URL value.	required
key	Optional[str]	Configurable URL key. Defaults to "url". The hash key is expected to be "{key}_hash".	'url'
options	Optional[SubgraphOptions]	Optional configuration for subgraph requests.	None

Returns:

Type	Description
str	URL value if it exists and the content hash matches. Returns empty string if URL is not set.

Raises:

Type	Description
KVStoreClientError	If the address is invalid, hash verification fails, or the URL is unreachable.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.kvstore import KVStoreUtils

chain_id = ChainId.POLYGON_AMOY
address = "0x62dD51230A30401C455c8398d06F85e4EaB6309f"

url = KVStoreUtils.get_file_url_and_verify_hash(chain_id, address)
linkedin_url = KVStoreUtils.get_file_url_and_verify_hash(
    chain_id, address, "linkedin_url"
)

get_kvstore_data staticmethod

get_kvstore_data(chain_id, address, options=None)

Retrieve all KVStore data for a given address.

Queries the subgraph for all key-value pairs associated with a specific address.

Parameters:

Name	Type	Description	Default
chain_id	ChainId	Network where the KVStore data has been stored.	required
address	str	Address whose KVStore data to retrieve.	required
options	Optional[SubgraphOptions]	Optional configuration for subgraph requests such as custom endpoints or timeout settings.	None

Returns:

Type	Description
Optional[List[KVStoreData]]	List of KVStore data entries if found, empty list otherwise.

Raises:

Type	Description
KVStoreClientError	If the chain ID is invalid or the address is malformed.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.kvstore import KVStoreUtils

data = KVStoreUtils.get_kvstore_data(
    ChainId.POLYGON_AMOY,
    "0x15d34aaf54267db7d7c367839aaf71a00a2c6a65",
)
for item in data:
    print(f"{item.key}: {item.value}")

get_public_key staticmethod

get_public_key(chain_id, address)

Get the public key of an entity from KVStore.

Retrieves and validates the public key stored for a given address. The public key URL is fetched from the public_key key and verified against its hash.

Parameters:

Name	Type	Description	Default
chain_id	ChainId	Network where the KVStore data has been stored.	required
address	str	Address from which to get the public key.	required

Returns:

Type	Description
str	Public key content if it exists and is valid. Returns empty string if no public key is set.

Raises:

Type	Description
KVStoreClientError	If the address is invalid or hash verification fails.

Example

from human_protocol_sdk.constants import ChainId
from human_protocol_sdk.kvstore import KVStoreUtils

public_key = KVStoreUtils.get_public_key(
    ChainId.POLYGON_AMOY,
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
)
print(public_key)