Skip to content

README.md

Latest commit

 

History

History
245 lines (188 loc) · 13.5 KB

README.md

File metadata and controls

245 lines (188 loc) · 13.5 KB

HOL HCS SDK (Python)

PyPI Version Python Versions PyPI Downloads Libraries.io Dependencies piwheels CI Security CodeQL Publish Conda Publish Anaconda Version Conda Downloads License GitHub Stars CodeSandbox Examples Typing: mypy Code Style: black Lint: ruff HOL SDK Docs HCS Standards

Python reference implementation of the Hiero Consensus Specifications (HCS) and Registry Broker utilities with parity against the TypeScript and Go SDKs.

📚 Standards SDK Documentation
📖 Hiero Consensus Specifications Documentation

Quick Start

cd standards-sdk-py
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Install

pip install standards-sdk-py
conda install -c hashgraph-online standards-sdk-py

Multi-Language SDK Links

Canonical SDK docs URL: https://hol.org/docs/libraries/standards-sdk/

Language Package Source Canonical Documentation
TypeScript @hol-org/standards-sdk hashgraph-online/standards-sdk https://hol.org/docs/libraries/standards-sdk/
Go github.com/hashgraph-online/standards-sdk-go hashgraph-online/standards-sdk-go https://hol.org/docs/libraries/go-sdk/overview
Python standards-sdk-py hashgraph-online/standards-sdk-py https://hol.org/docs/libraries/python-sdk/overview

Developer Tooling

cd standards-sdk-py
.venv/bin/pre-commit install
.venv/bin/pre-commit run --all-files

Documentation

For standards and API documentation:

Citation and Archival

Supported Packages

Package Coverage
standards_sdk_py.hcs2 HCS-2 registry topic creation, indexed entry operations, memo helpers, mirror reads.
standards_sdk_py.hcs3 HCS-3 recursive file loading helpers.
standards_sdk_py.hcs5 HCS-5 hashinal inscription and minting helpers.
standards_sdk_py.hcs6 HCS-6 non-indexed registry creation, registration helpers, memo helpers.
standards_sdk_py.hcs7 HCS-7 indexed registry and metadata registration helpers.
standards_sdk_py.hcs10 HCS-10 topic/message builders and communication helpers.
standards_sdk_py.hcs11 HCS-11 profile models/builders, validation, inscription helpers.
standards_sdk_py.hcs12 HCS-12 action/assembly/hashlinks helpers.
standards_sdk_py.hcs14 HCS-14 UAID parsing and resolution helpers.
standards_sdk_py.hcs15 HCS-15 account creation and memo helpers.
standards_sdk_py.hcs16 HCS-16 flora account/topic/message helpers.
standards_sdk_py.hcs17 HCS-17 state-hash helpers.
standards_sdk_py.hcs18 HCS-18 discovery topic/message helpers.
standards_sdk_py.hcs20 HCS-20 points message and validation helpers.
standards_sdk_py.hcs21 HCS-21 adapter declaration helpers.
standards_sdk_py.hcs26 HCS-26 memo parser/resolver helpers.
standards_sdk_py.hcs27 HCS-27 checkpoint helpers.
standards_sdk_py.inscriber Inscriber auth, quote, submit, and polling workflows.
standards_sdk_py.registry_broker Full Registry Broker client (search, adapters, registries, credits, verification, chat/encryption, skills, ledger auth).
standards_sdk_py.mirror Mirror node client used by standards and inscriber modules.
standards_sdk_py.shared transport, config, network/operator helpers, and shared typing.

CodeSandbox Examples

Environment Variables

Common:

  • HEDERA_NETWORK
  • HEDERA_ACCOUNT_ID or HEDERA_OPERATOR_ID
  • HEDERA_PRIVATE_KEY or HEDERA_OPERATOR_KEY

Network-scoped overrides:

  • TESTNET_HEDERA_ACCOUNT_ID
  • TESTNET_HEDERA_PRIVATE_KEY
  • MAINNET_HEDERA_ACCOUNT_ID
  • MAINNET_HEDERA_PRIVATE_KEY

Registry Broker:

  • REGISTRY_BROKER_BASE_URL
  • REGISTRY_BROKER_API_KEY
  • REGISTRY_BROKER_LEDGER_API_KEY

Inscriber integration:

  • RUN_INTEGRATION=1
  • RUN_INSCRIBER_INTEGRATION=1

Tests

Unit and contract tests:

cd standards-sdk-py
.venv/bin/pytest -q

Parity checks:

cd standards-sdk-py
.venv/bin/standards-sdk-py-generate-inventory --repo-root ..
.venv/bin/standards-sdk-py-check-parity

Live testnet inscriber end-to-end:

cd standards-sdk-py
cp ../standards-sdk/.env ./.env
pip install hedera-sdk-py
set -a
source <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' ./.env)
set +a
export RUN_INTEGRATION=1
export RUN_INSCRIBER_INTEGRATION=1
.venv/bin/pytest -m integration -k inscriber_registry_broker_end_to_end_testnet -vv -rs

Live testnet HCS-2 end-to-end:

cd standards-sdk-py
export RUN_INTEGRATION=1
export RUN_HCS2_INTEGRATION=1
export HEDERA_NETWORK=testnet
export TESTNET_HEDERA_ACCOUNT_ID="<your-testnet-account-id>"
export TESTNET_HEDERA_PRIVATE_KEY="<your-testnet-private-key>"
.venv/bin/pytest -m integration -k hcs2_end_to_end_testnet -vv -rs

Notes:

  • Set HEDERA_NETWORK=testnet (and do not set a conflicting INSCRIBER_HEDERA_NETWORK).
  • The test uses ledger challenge auth from your testnet credentials to avoid accidentally using a mainnet-scoped API key.

CI/CD and Security

  • Python matrix CI (3.11, 3.12, 3.13) for ruff, black, mypy, unit tests, parity checks, and package validation.
  • Security workflows for dependency review, pip-audit, Bandit SARIF upload, CodeQL, and verified TruffleHog secret scanning.
  • Release workflow for build + twine check, TestPyPI/PyPI trusted publishing, checksum artifacts, provenance attestations, and GitHub release notes.
  • Conda workflow for building packages and uploading to anaconda.org/hashgraph-online when ANACONDA_API_TOKEN is configured.
  • Release indexing automation verifies PyPI + Libraries.io pages and submits a Software Heritage save request.

Contributing

Open issues or pull requests in the repository:

Security

For disclosure and response policy, see SECURITY.md.

Maintainers

Maintained by HOL.

Resources

📝 Blog Tutorials

License

MIT