KVStoreClient

Client for interacting with the KVStore contract.

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.kvstore import KVStoreClient

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

w3 = get_w3_with_priv_key("YOUR_PRIVATE_KEY")
kvstore_client = KVStoreClient(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.kvstore import KVStoreClient

w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
kvstore_client = KVStoreClient(w3)

KVStoreClient ¶

KVStoreClient(web3, gas_limit=None)

Client for interacting with the KVStore smart contract.

This client provides methods to read and write key-value pairs on-chain, supporting both individual and bulk operations, as well as URL storage with content hash verification.

Attributes:

Name	Type	Description
`w3`	`Web3`	Web3 instance configured for the target network.
`network`	`dict`	Network configuration for the current chain.
`kvstore_contract`	`Contract`	Contract instance for the KVStore.
`gas_limit`	`Optional[int]`	Optional gas limit for transactions.

Initialize a KVStoreClient instance.

Parameters:

Name	Type	Description	Default
`web3`	`Web3`	Web3 instance configured for the target network. Must have a valid provider and chain ID.	required
`gas_limit`	`Optional[int]`	Optional gas limit for transactions.	`None`

Raises:

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

Example

from web3 import Web3
from human_protocol_sdk.kvstore import KVStoreClient

w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
kvstore_client = KVStoreClient(w3)

get ¶

get(address, key)

Get the value of a key-value pair from the KVStore.

Retrieves the value associated with a key for a specific address.

Parameters:

Name	Type	Description	Default
`address`	`str`	Ethereum address associated with the key-value pair.	required
`key`	`str`	Key to retrieve (cannot be empty).	required

Returns:

Type	Description
`str`	Value of the key-value pair if it exists, empty string otherwise.

Raises:

Type	Description
`KVStoreClientError`	If the key is empty, address is invalid, or the query fails.

Example

role = kvstore_client.get(
    "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
    "Role",
)
print(role)  # "RecordingOracle"

set ¶

set(key, value, tx_options=None)

Set a key-value pair in the KVStore contract.

Stores a single key-value pair on-chain associated with the sender's address.

Parameters:

Name	Type	Description	Default
`key`	`str`	Key to set (cannot be empty).	required
`value`	`str`	Value to assign to the key.	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`KVStoreClientError`	If the key is empty or the transaction fails.

Example

kvstore_client.set("Role", "RecordingOracle")

set_bulk ¶

set_bulk(keys, values, tx_options=None)

Set multiple key-value pairs in the KVStore contract.

Stores multiple key-value pairs on-chain in a single transaction, all associated with the sender's address.

Parameters:

Name	Type	Description	Default
`keys`	`List[str]`	List of keys to set (no key can be empty).	required
`values`	`List[str]`	Corresponding list of values (must match keys length).	required
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`KVStoreClientError`	If any key is empty, arrays are empty, arrays have different lengths, or the transaction fails.

Example

kvstore_client.set_bulk(
    ["Role", "Webhook_url"],
    ["RecordingOracle", "http://localhost"],
)

set_file_url_and_hash ¶

set_file_url_and_hash(url, key='url', tx_options=None)

Set a URL value and its content hash in the KVStore.

Fetches the content from the URL, computes its hash, and stores both the URL and hash on-chain. The hash key is automatically generated by appending _hash to the provided key.

Parameters:

Name	Type	Description	Default
`url`	`str`	URL to store (must be valid and accessible).	required
`key`	`Optional[str]`	Configurable URL key. Defaults to `"url"`. The hash will be stored with key `"{key}_hash"`.	`'url'`
`tx_options`	`Optional[TransactionOptions]`	Optional transaction parameters such as gas limit.	`None`

Returns:

Type	Description
`None`	None

Raises:

Type	Description
`KVStoreClientError`	If the URL is invalid, unreachable, or the transaction fails.

Example

kvstore_client.set_file_url_and_hash("http://localhost/manifest.json")
kvstore_client.set_file_url_and_hash(
    "https://linkedin.com/me", "linkedin_url"
)

KVStoreClientError ¶

Bases: Exception

Exception raised when errors occur during KVStore operations.