KVStore

What is KVStore?

KVStore (Key‑Value Store) is a decentralized, on‑chain storage component of the HUMAN Protocol. It allows any Ethereum address (oracles, requesters or workers) to store, update, and retrieve key-value pairs securely on-chain, tied exclusively to the owner’s address.

How it works?

HUMAN Protocol uses a smart contract to store this information on chain:

• set(key, value) – stores or updates a value under your address.

• get(address, key) – retrieves a value tied to any Ethereum address.

• setBulk(keys, values) – stores or updates a set of values under your address.

The interaction with this contract can be done via KVStore client and utils of the SDK:

• Typescript.

• Python.

Why HUMAN Protocol uses KVStore?

HUMAN Protocol uses KVStore to let participants attach extra information to their wallet addresses. For instance, oracles configure on-chain settings like roles, fees, or encryption keys in a way that everyone can read but only the oracle can modify.

Benefits

Feature	Benefit
Decentralized	Fully on-chain; no centralized database needed
Permissioned	Only the owner’s address can modify its entries
Publicly discoverable	Anyone can read what’s stored (supports transparency)
Supports rotation	Users can update keys or values anytime
SDK-integrated	Easy to use via TS/Python packages

Predefined keys

The HUMAN protocol has the following predefined keys, despite users can set any other custom key:

category	Category of jobs you can process (machine_learning, market_making).
fee	How much you charge per job processed (in %, usually 1-5).
job_types	A list of the kinds of tasks you handle (image_boxes,image_boxes_from_points, audio_transcription etc.).
name	Your oracle’s name which will be displayed to annotators on a dashboard.
public_key	Url to a file that contains your encryption/signing public key (so others can send or verify secure data). Check this tutorial on how to generate PGP pair: https://docs.humanprotocol.org/hub/human-tech-docs/developer/faq#how-to-generate-pgp-key-pair
public_key_hash	A shorter fingerprint of your public key for quick checking (should be automatically set via https://docs.humanprotocol.org/hub/human-tech-docs/developer/faq#how-to-generate-pgp-key-pair or https://sdk.humanprotocol.org/python-sdk/human_protocol_sdk.kvstore/human_protocol_sdk.kvstore.kvstore_client#set_file_url_and_hash-url-key-url-tx_options-none)
registration_instructions	Url to a file or page that contains registrations instructions (for annotation tools mostly).
registration_needed	True/false flag indicates whether users have to register or not (on the annotation tools mostly, e.g CVAT).
role	Your role in the protocol (job_launcher, exchange_oracle, recording_oracle, reputation_oracle)
url	Base url of your oracle API.
website	Url of your homepage.
webhook_url	The endpoint URL where you’ll receive results or notifications during the job processing.