Skip to content

KVStore

What is KVStore?#

KVStore (Key-Value Store) is a decentralized, on-chain storage component of the HUMAN Protocol. It lets any Ethereum address (oracles, requesters, workers) 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): store or update a value under your address.
  • get(address, key): retrieve a value tied to any Ethereum address.
  • setBulk(keys, values): store or update multiple values under your address.

Use the KVStore client and SDK utilities to interact with the contract:

Why HUMAN Protocol uses KVStore#

KVStore lets participants attach extra information to their wallet addresses. For example, 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#

  • Decentralized: fully on-chain; no centralized database needed.
  • Permissioned: only the owner's address can modify its entries.
  • Publicly discoverable: anyone can read stored data for transparency.
  • Supports rotation: users can update keys or values anytime.
  • SDK-integrated: easy to use via TypeScript and Python packages.

Predefined keys#

HUMAN Protocol defines the keys below; you can also set custom keys.

Key Description
category Categories of jobs you can process (machine_learning, market_making).
fee Fee charged per job (percentage, usually 1-5).
job_types Tasks you handle (e.g., image_boxes, image_boxes_from_points, audio_transcription).
name Oracle name shown to annotators.
public_key URL to your encryption/signing public key. See the PGP key generation guide.
public_key_hash Fingerprint of your public key; can be set via the PGP guide above or the Python SDK helper.
registration_instructions URL with registration instructions (mainly for annotation tools).
registration_needed Boolean indicating whether users must register (e.g., CVAT).
role Your role (job_launcher, exchange_oracle, recording_oracle, reputation_oracle).
url Base URL of your oracle API.
website URL of your homepage.
webhook_url Endpoint URL where you receive results or notifications during job processing.