Merge branch 'main' into aido/696/doc-sync-message-envelope

Author: aido-mth

.config/dictionaries/project.dic

@@ -8,6 +8,7 @@ adminer
 admon
 anypolicy
 apskhem
+asat
 Arissara
 asyncio
 Attributes
@@ -33,6 +34,7 @@ Cabe
 cantopen
 cardano
 carryforward
+catid
 CBOR
 cbork
 cddlc
@@ -251,13 +253,15 @@ pubk
 pubkey
 publickey
 pubspec
+pycardano
 pwrite
 pycodestyle
 pydantic
 pydot
 pyenv
 Pyflakes
 pypackages
+pyproject
 pytest
 pytype
 qpsg

.github/workflows/semantic_pull_request.yml

@@ -32,3 +32,4 @@ jobs:
         docs
         general
         deps
+        catalyst-python

catalyst-python/.python-version

@@ -0,0 +1 @@
+3.13

catalyst-python/Earthfile

@@ -0,0 +1,17 @@
+VERSION 0.8
+
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.6.6 AS python-ci
+
+builder:
+    FROM python-ci+python-base
+
+    COPY pyproject.toml uv.lock .
+    COPY src .
+    COPY tests .
+
+    RUN uv update
+
+build:
+    FROM +builder
+
+    RUN uv run pytest

catalyst-python/README.md

@@ -0,0 +1,4 @@
+# Catalyst Python library
+
+A collection of reusable python code of Catalyst specific entities
+like RBAC, Catalyst Signed Documents, Catalyst API etc.

catalyst-python/pyproject.toml

@@ -0,0 +1,26 @@
+# cspell: words bitcoinlib
+
+[project]
+name = "catalyst-python"
+version = "0.1.0"
+description = "Catalyst python library"
+readme = "README.md"
+authors = [
+    { name = "Mr-Leshiy", email = "[email protected]" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "cryptography>=46.0.3",
+    "pycardano>=0.18.0",
+    "python-bitcoinlib>=0.12.2",
+    "requests>=2.32.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.5,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+]

catalyst-python/src/catalyst_python/__init__.py

@@ -0,0 +1 @@
+"""Catalyst Python Package."""

catalyst-python/src/catalyst_python/address.py

@@ -0,0 +1,39 @@
+# cspell: words convertbits, segwit
+# ruff: noqa: D100, D103, I001, FBT001, PLR1714, SIM108
+
+from hashlib import blake2b
+from bitcoin.segwit_addr import bech32_encode, convertbits
+
+
+# according to [CIP-19](https://cips.cardano.org/cips/cip19/).
+def stake_public_key_to_address(key: str, is_stake: bool, network_type: str) -> str:
+    def stake_header(is_stake: bool, network_type: str) -> str:
+        if is_stake:
+            # stake key hash
+            typeid = int("1110", 2)
+        else:
+            # script hash
+            typeid = int("1111", 2)
+        if network_type == "mainnet":
+            network_id = 1
+        elif network_type == "testnet" or network_type == "preprod" or network_type == "preview":
+            network_id = 0
+        else:
+            raise f"Unknown network type: {network_type}"
+
+        typeid = typeid << 4
+        return typeid | network_id
+
+    key_bytes = bytes.fromhex(key)
+    key_hash = blake2b(key_bytes, digest_size=28)
+    header = stake_header(is_stake=is_stake, network_type=network_type)
+    key_hash_with_header = header.to_bytes(1, "big") + key_hash.digest()
+
+    if network_type == "mainnet":
+        hrp = "stake"
+    elif network_type == "testnet" or network_type == "preprod" or network_type == "preview":
+        hrp = "stake_test"
+    else:
+        raise f"Unknown network type: {network_type}"
+
+    return bech32_encode(hrp, convertbits(key_hash_with_header, 8, 5))

catalyst-python/src/catalyst_python/admin.py

@@ -0,0 +1,31 @@
+# ruff: noqa: D100, D101, D102, D107, I001
+
+from catalyst_python.ed25519 import Ed25519Keys
+from catalyst_python.rbac_token import (
+    generate_rbac_auth_token,
+    generate_cat_id,
+)
+
+
+class AdminKey:
+    def __init__(self, key: Ed25519Keys, network: str, subnet: str | None = None) -> None:
+        self.key = key
+        self.network = network
+        self.subnet = subnet
+
+    def cat_id(self) -> str:
+        return generate_cat_id(
+            scheme="admin.catalyst",
+            network=self.network,
+            subnet=self.subnet,
+            role_0_key=self.key,
+        )
+
+    def auth_token(self) -> str:
+        return generate_rbac_auth_token(
+            scheme="admin.catalyst",
+            network=self.network,
+            subnet=self.subnet,
+            role_0_key=self.key,
+            signing_key=self.key,
+        )

catalyst-python/src/catalyst_python/catalyst_id.py

@@ -0,0 +1,60 @@
+# ruff: noqa: D100, D101, D103, D105, RET505, UP017, PLR0913
+
+from datetime import datetime, timezone
+from enum import IntEnum
+
+from catalyst_python.ed25519 import Ed25519Keys
+from catalyst_python.utils import base64_url
+
+
+class RoleID(IntEnum):
+    ROLE_0 = 0
+    PROPOSER = 3
+
+    def __str__(self) -> str:
+        return f"{int(self)}"
+
+
+# Default is set to URI format
+# Optional field = subnet, role id, rotation, username, nonce
+def generate_cat_id(
+    network: str,
+    role_0_key: Ed25519Keys,
+    scheme: str | None = None,
+    subnet: str | None = None,
+    role_id: RoleID | None = None,
+    rotation: str | None = None,
+    username: str | None = None,
+    nonce: str | None = None,
+) -> str:
+    role0_pk_b64 = base64_url(bytes.fromhex(role_0_key.pk_hex()))
+
+    # If nonce is set to none, use current timestamp
+    # If set to empty string, use empty string (no nonce)
+    if nonce is None:
+        nonce = f"{int(datetime.now(timezone.utc).timestamp())}"
+
+    # Authority part
+    authority = ""
+    if username:
+        authority += f"{username}"
+    if nonce:
+        authority += f":{nonce}"
+    authority += "@"
+
+    if subnet:
+        authority += f"{subnet}.{network}"
+    else:
+        authority += network
+
+    # Path
+    path = f"{role0_pk_b64}"
+    if role_id is not None:
+        path += f"/{role_id}"
+        if rotation is not None:
+            path += f"/{rotation}"
+
+    if scheme:
+        return f"{scheme}://{authority}/{path}"
+    else:
+        return f"{authority}/{path}"