The repository contains the Python SDK for managing DID Documents and Anoncreds Verifiable Credentials registry using Hedera Consensus Service.
Project description
Hiero DID SDK Python
This repository contains the Python SDK that enables developers to manage Decentralized Identifiers (DIDs) and AnonCreds Verifiable Credentials on the Hedera network using the Hedera Consensus Service.
This library is using Hiero Python SDK.
Table of contents
Overview
Decentralized identity ecosystems are built upon decentralized identifiers (DIDs) and verifiable credentials (VCs) standards, providing necessary functionality to publish and resolve DID documents and issue/verify credentials (claims).
Data model of such ecosystems rely on Verifiable Data Registries (VDRs), commonly represented by decentralized ledgers.
Hiero, as an open-source Decentralized Ledger Technology (DLT), is a great VDR option providing high-performance and low costs of operations. Hedera, while being built on Hiero, is a large and trusted network that will be a great choice for solutions searching for high-reliability.
In particular, Hedera and other Hiero-based networks can be used as VDR for Hedera DID Method and AnonCreds Verifiable Credentials by leveraging Hedera Consensus Service (HCS).
This SDK is designed to simplify:
- Creation and management of Hedera DID documents
- Creation and management of AnonCreds resources
- Adoption of Hiero-based VDRs for AnonCreds use cases
- Empowering new and existing Python-based agent implementations with high-performance and low operational costs provided by Hiero
Documentation
Dev and API
We're planning to publish dev guides along with mkdocs-generated API documentation to GH pages in near future. You can find documentation sources in repo.
Meanwhile, dev guides have been added to this README for convenience.
If you're planning to contribute to the project, please also check contribution guidelines.
Design
SDK design documentation can be found in corresponding repo folder.
Dev environment
The project uses Makefile for dev scripts. You can view available commands by running:
make help
Core commands are listed below:
Install dependencies and tools
make install
Run code quality checks
make check
Run tests
make test
Build artifacts
make build
Getting started
Prerequisites
- Python 3.12+
- Poetry (at least 1.8.4)
- NodeJS and npm (used by pre-commit hooks)
- Tools for Makefile support (Windows only)
- Can be installed with chocolatey:
choco install make
- Can be installed with chocolatey:
Install package (from Git source)
pip install git+https://github.com/hiero-ledger/hiero-did-sdk-python@main
Please note that PyPi package will soon be published and replace Git source dependency as recommended installation method.
Example usage
Here you can find basic SDK usage examples.
For more complex examples, please refer to SDK integration tests:
Create Hedera Client (for testnet)
from hiero_sdk_python import Client, Network, AccountId, PrivateKey
client = Client(
network=Network("testnet")
)
client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
Register new Hedera DID on testnet network and add DID service
from hiero_did_sdk_python import HederaDid
did = HederaDid(client=client, private_key_der="private_key_der")
await did.register()
await did.add_service(
id_=f"{did.identifier}#service-1", service_type="LinkedDomains", service_endpoint="https://example.com/vcs"
)
Resolve existing Hedera DID
from hiero_did_sdk_python import HederaDidResolver
resolver = HederaDidResolver(client)
resolution_result = await resolver.resolve(
"did:hedera:testnet:zvAQyPeUecGck2EsxcsihxhAB6jZurFrBbj2gC7CNkS5o_0.0.5063027")
Create AnonCreds credential schema and credential definition
from hiero_did_sdk_python import HederaAnonCredsRegistry, AnonCredsSchema, AnonCredsCredDef, CredDefValue, CredDefValuePrimary
issuer_did = "did:hedera:testnet:zvAQyPeUecGck2EsxcsihxhAB6jZurFrBbj2gC7CNkS5o_0.0.5063027"
registry = HederaAnonCredsRegistry(client)
schema = AnonCredsSchema(
name="schema-name",
issuer_id=issuer_did,
attr_names=["name", "age"],
version="1"
)
schema_registration_result = await registry.register_schema(schema, issuer_did, "OPERATOR_KEY_DER")
cred_def = AnonCredsCredDef(
schema_id=schema_registration_result.schema_state.schema_id,
issuer_id=issuer_did,
value=CredDefValue(primary=CredDefValuePrimary(...)),
tag="cred-def-tag"
)
cred_def_registration_result = await registry.register_cred_def(cred_def, issuer_did, "OPERATOR_KEY_DER")
Configuration
At the moment, SDK comes with following configuration capabilities:
- Hedera Client configuration
- Cache implementation (optional)
- Logger configuration (optional)
Hedera Client configuration
Configuration consists from two parts:
- Network configuration
- Basic configuration is lightweight and consists from selection of specific network ("mainnet", "testnet", " previewnet"), complex parts are handled by Hedera Python SDK
- Custom configuration can be provided, if necessary
- Hedera operator (account) configuration
- Essentially, account "credentials" that will be used for Hedera network integration and paying fees
- Needs to be provided explicitly and can be changed for specific Hedera Client instance via provider class
Examples
Create client for Testnet and set operator config:
from hiero_sdk_python import Client, Network, AccountId, PrivateKey
client = Client(
network=Network("testnet")
)
client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
Create client provider with custom network config:
from hiero_sdk_python import Client, Network, AccountId, PrivateKey
TESTNET_NODES = [
("0.testnet.hedera.com:50211", AccountId(0, 0, 3)),
("1.testnet.hedera.com:50211", AccountId(0, 0, 4))
]
client = Client(
network=Network(network="testnet", nodes=TESTNET_NODES, mirror_address="hcs.testnet.mirrornode.hedera.com:5600"),
)
client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
Cache implementation
SDK utilizes cache to optimize read operations and provides an option to customize cache implementation (individually for each resolver instance).
By default, in-memory cache implementation is used.
You can create custom cache implementation by inheriting Cache base class. Custom cache instance needs to be provided in resolver constructor arguments.
Classes that accept custom cache implementation:
Example
from hiero_did_sdk_python import Cache, HederaDidResolver
class CustomCache(Cache):
...
custom_cache_instance = CustomCache[str, object]()
resolver = HederaDidResolver(client, custom_cache_instance)
Logger configuration
Logger configuration supports following properties that can be set with environment variables:
- Log level
- Env variable name:
HEDERA_DID_SDK_LOG_LEVEL - Currently supported values: "DEBUG", "INFO", "WARN", "ERROR"
- Env variable name:
- Log format (in string representation)
- Env variable name:
HEDERA_DID_SDK_LOG_FORMAT - For log format pattern reference, please see Python docs:
- Env variable name:
Contributing to this Project
Whether you’re fixing bugs, enhancing features, or improving documentation, your contributions are important — let’s build something great together!
For instructions on how to contribute to this repo, please review the Contributing Guide for the Hiero DID SDK.
More instructions for contribution can be found in the Global Contributing Guide.
Code of Conduct
Hiero uses the Linux Foundation Decentralised Trust Code of Conduct.
