Merge branch 'main' into workflow-label-trigger-simplify

Author: NssGourav

.github/scripts/cron-admin-update-spam-list.js

@@ -8,6 +8,7 @@
  */
 
 const fs = require('fs').promises;
+const { LABEL_AUTOMATED } = require('./labels.js');
 
 const SPAM_LIST_PATH = '.github/spam-list.txt';
 const dryRun = (process.env.DRY_RUN || 'false').toString().toLowerCase() === 'true';
@@ -229,7 +230,7 @@ module.exports = async ({github, context, core}) => {
           repo,
           title,
           body,
-          labels: [LABEL_SPAM_LIST_UPDATE, 'automated']
+          labels: [LABEL_SPAM_LIST_UPDATE, LABEL_AUTOMATED]
         });
         console.log('Issue created successfully');
       }

.github/scripts/labels.js

@@ -0,0 +1,11 @@
+/**
+ * Central location for label definitions to facilitate future changes.
+ * This file serves as the single source of truth for all GitHub label names used by automated workflows.
+ */
+const LABEL_BROKEN_MARKDOWN_LINKS = 'notes: broken markdown links';
+const LABEL_AUTOMATED = 'notes: automated';
+
+module.exports = {
+  LABEL_BROKEN_MARKDOWN_LINKS,
+  LABEL_AUTOMATED
+};

.github/workflows/cron-pr-check-broken-links.yml

@@ -1,5 +1,9 @@
 name: Cron – Check Broken Markdown Links
 
+concurrency:
+  group: cron-check-broken-markdown-links
+  cancel-in-progress: false
+
 on:
   schedule:
     - cron: "0 0 1 * *"
@@ -42,12 +46,14 @@ jobs:
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
+            const { LABEL_BROKEN_MARKDOWN_LINKS, LABEL_AUTOMATED } = require('./.github/scripts/labels.js');
+
             // Determine if this is a dry run
             const isManual = context.eventName === 'workflow_dispatch';
-            const dryRun = isManual ? String(context.payload.inputs.dry_run).toLowerCase() === 'true' : false;
+            const dryRun = isManual ? String(context.payload?.inputs?.dry_run).toLowerCase() === 'true' : false;
 
             // Labels configuration
-            const targetLabels = ['broken-markdown-links', 'automated'];
+            const targetLabels = [LABEL_BROKEN_MARKDOWN_LINKS, LABEL_AUTOMATED];
             const issueTitle = "Scheduled Markdown Link Check Found Broken Links";
             const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
 

.github/workflows/request-triage-review.yml

@@ -0,0 +1,43 @@
+name: Request triage review on beginner and Good First Issue PRs
+
+on:
+  pull_request_target:
+    types: [opened, labeled]
+
+concurrency:
+  group: triage-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  request-triage:
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'Good First Issue') || contains(github.event.pull_request.labels.*.name, 'beginner') }}
+    runs-on: [self-hosted,hl-sdk-py-lin-md]
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        with:
+          egress-policy: audit
+
+      - name: Request triage review
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const tag = "<!-- triage -->";
+            const { data: comments } = await github.rest.issues.listComments({
+                                         owner: context.repo.owner,
+                                         repo: context.repo.repo,
+                                         issue_number: context.payload.pull_request.number
+                                    });
+            if (!comments.some(c => c.body?.includes(tag))) {
+                await github.rest.issues.createComment({
+                 owner: context.repo.owner,
+                  repo: context.repo.repo,
+                   issue_number: context.payload.pull_request.number,
+             body: `${tag} Requesting triage review from: @hiero-ledger/hiero-sdk-python-triage`
+               });
+            }

CONTRIBUTING.md

@@ -32,7 +32,7 @@ Thank you for your interest in contributing to the Hiero Python SDK!
 3. Follow [Setup Guide](docs/sdk_developers/training/setup)
 4. Follow [Workflow Guide](docs/sdk_developers/workflow.md)
 5. GPG and DCO sign commits [Quickstart Signing](docs/sdk_developers/training/workflow/07_signing_requirements.md)
-6. Submit a PR [Quickstart Submit PR](docs/sdk_developers/training/workflow/11_submit_pull_request.md)
+6. Submit a PR [Quickstart Submit PR](docs/sdk_developers/training/workflow/10_submit_pull_request.md)
 
 **Detailed Docs:**
 

src/hiero_sdk_python/crypto/public_key.py

@@ -413,6 +413,90 @@ def to_bytes_der(self) -> bytes:
             encoding=serialization.Encoding.DER, format=serialization.PublicFormat.SubjectPublicKeyInfo
         )
 
+    @classmethod
+    def _encode_vlq(cls, value: int) -> bytes:
+        """
+        Encode a value in Variable-Length Quantity (VLQ) format.
+        """
+        if value < 0:
+            raise ValueError("VLQ value must be non-negative")
+        if value == 0:
+            return b"\x00"
+
+        encoded = bytearray()
+        while value > 0:
+            encoded.insert(0, value & 0x7F)
+            value >>= 7
+
+        # Set the high bit (0x80) on all bytes except the last
+        for i in range(len(encoded) - 1):
+            encoded[i] |= 0x80
+
+        return bytes(encoded)
+
+    @classmethod
+    def _encode_der_length(cls, length: int) -> bytes:
+        """Encode a DER length field per X.690 standards."""
+        if length < 0:
+            raise ValueError("DER length must be non-negative")
+        if length < 0x80:
+            return bytes([length])
+
+        length_bytes = length.to_bytes((length.bit_length() + 7) // 8, "big")
+        return bytes([0x80 | len(length_bytes)]) + length_bytes
+
+    @classmethod
+    def _encode_der_oid(cls, oid: str) -> bytes:
+        """
+        Encode a dotted OID string into DER OID bytes including tag and length.
+        """
+        parts = [int(part) for part in oid.split(".")]
+
+        is_valid = len(parts) >= 2 and parts[0] in (0, 1, 2) and parts[1] >= 0 and (parts[0] == 2 or parts[1] < 40)
+        if not is_valid:
+            raise ValueError(f"Invalid OID structure for '{oid}'")
+
+        first, second = parts[0], parts[1]
+
+        # Encode the combined root using VLQ to handle edge cases correctly
+        encoded = bytearray(cls._encode_vlq(40 * first + second))
+
+        for value in parts[2:]:
+            encoded.extend(cls._encode_vlq(value))
+
+        return bytes([0x06]) + cls._encode_der_length(len(encoded)) + bytes(encoded)
+
+    @classmethod
+    def _encode_der_sequence(cls, content: bytes) -> bytes:
+        """Encode DER SEQUENCE tag, length, and content per X.690 standards."""
+        return bytes([0x30]) + cls._encode_der_length(len(content)) + content
+
+    @classmethod
+    def _encode_der_bit_string(cls, content: bytes) -> bytes:
+        """
+        Encode DER BIT STRING tag, length, and content per X.690 standards.
+        """
+        payload = bytes([0x00]) + content
+        return bytes([0x03]) + cls._encode_der_length(len(payload)) + payload
+
+    def to_bytes_der_ecdsa_compressed(self) -> bytes:
+        """
+        Returns DER-encoded SubjectPublicKeyInfo for secp256k1 using a compressed SEC1 point.
+        Raises:
+            ValueError: If this key is not ECDSA secp256k1.
+        """
+        if not self.is_ecdsa():
+            raise ValueError("Compressed ECDSA DER export is only supported for ECDSA keys")
+
+        # id-ecPublicKey + secp256k1 OID algorithm identifier
+        algorithm_id = self._encode_der_sequence(
+            self._encode_der_oid("1.2.840.10045.2.1") + self._encode_der_oid("1.3.132.0.10")
+        )
+        compressed_point = self.to_bytes_ecdsa(compressed=True)
+        subject_public_key = self._encode_der_bit_string(compressed_point)
+
+        return self._encode_der_sequence(algorithm_id + subject_public_key)
+
     #
     # ---------------------------------
     # Type-specific (Ed25519, ECDSA secp256k1) to hex string.
@@ -440,6 +524,12 @@ def to_string_der(self) -> str:
         """
         return self.to_bytes_der().hex()
 
+    def to_string_der_ecdsa_compressed(self) -> str:
+        """
+        Returns DER SPKI hex for ECDSA secp256k1 using a compressed SEC1 point.
+        """
+        return self.to_bytes_der_ecdsa_compressed().hex()
+
     def to_string_raw(self) -> str:
         """
         Catch all ed25519 or ecdsa for convenience.

src/hiero_sdk_python/query/account_balance_query.py

@@ -172,7 +172,7 @@ def _get_query_response(self, response: Any) -> crypto_get_account_balance_pb2.C
         """
         return response.cryptogetAccountBalance
 
-    def _is_payment_required(self):
+    def _is_payment_required(self) -> bool:
         """
         Account balance query does not require payment.
 

src/hiero_sdk_python/utils/key_utils.py

@@ -7,43 +7,30 @@
 
 from __future__ import annotations
 
-from hiero_sdk_python.crypto.private_key import PrivateKey
-from hiero_sdk_python.crypto.public_key import PublicKey
+from hiero_sdk_python.crypto.key import Key
 from hiero_sdk_python.hapi.services import basic_types_pb2
 
 
-# Type alias for keys that can be either PrivateKey or PublicKey
-Key = PrivateKey | PublicKey
-
-
 def key_to_proto(key: Key | None) -> basic_types_pb2.Key | None:
     """
-    Helper function to convert a key (PrivateKey or PublicKey) to protobuf Key format.
+    Helper function to convert an SDK key to protobuf Key format.
 
-    This function handles the conversion of SDK key types to protobuf format:
-    - If a PrivateKey is provided, its corresponding public key is extracted and converted.
-    - If a PublicKey is provided, it is converted directly to protobuf.
-    - If None is provided, None is returned.
+    This function handles any concrete subclass of Key by delegating to its
+    to_proto_key() implementation. If None is provided, None is returned.
 
     Args:
-        key (Optional[Key]): The key to convert (PrivateKey or PublicKey), or None
+        key (Optional[Key]): The key to convert, or None
 
     Returns:
         basic_types_pb2.Key (Optional): The protobuf key or None if key is None
 
     Raises:
-        TypeError: If the provided key is not a PrivateKey, PublicKey, or None.
+        TypeError: If the provided key is not a Key instance or None.
     """
-    if not key:
+    if key is None:
         return None
 
-    # If it's a PrivateKey, get the public key first, then convert to proto
-    if isinstance(key, PrivateKey):
-        return key.public_key()._to_proto()
-
-    # If it's a PublicKey, convert directly to proto
-    if isinstance(key, PublicKey):
-        return key._to_proto()
+    if isinstance(key, Key):
+        return key.to_proto_key()
 
-    # Safety net: This will fail if a non-key is passed
-    raise TypeError("Key must be of type PrivateKey or PublicKey")
+    raise TypeError("Key must be of type PrivateKey or PublicKey, or another SDK Key implementation")

tests/unit/keys_public_test.py

@@ -328,6 +328,91 @@ def test_from_bytes_invalid():
         PublicKey.from_bytes(data)
 
 
+# ------------------------------------------------------------------------------
+# Test: DER helper encoders and compressed DER export
+# ------------------------------------------------------------------------------
+def test_encode_der_length_short_and_long_forms():
+    assert PublicKey._encode_der_length(0) == b"\x00"
+    assert PublicKey._encode_der_length(0x7F) == b"\x7f"
+    assert PublicKey._encode_der_length(0x80) == b"\x81\x80"
+    assert PublicKey._encode_der_length(0x0100) == b"\x82\x01\x00"
+    assert PublicKey._encode_der_length(0x1000000) == b"\x84\x01\x00\x00\x00"
+
+
+def test_encode_der_length_negative_raises():
+    with pytest.raises(ValueError, match="non-negative"):
+        PublicKey._encode_der_length(-1)
+
+
+def test_encode_der_oid_known_values():
+    # id-ecPublicKey
+    assert PublicKey._encode_der_oid("1.2.840.10045.2.1") == bytes.fromhex("06072a8648ce3d0201")
+    # secp256k1
+    assert PublicKey._encode_der_oid("1.3.132.0.10") == bytes.fromhex("06052b8104000a")
+
+
+def test_encode_der_oid_combined_root_multibyte():
+    # "2.999" -> 2*40 + 999 = 1079, encoded as VLQ: 0x88 0x37
+    result = PublicKey._encode_der_oid("2.999.1")
+    assert result == bytes.fromhex("0603883701")
+    assert result[0] == 0x06  # OID tag
+    assert result[1] == 0x03  # Length of OID content
+
+
+def test_encode_der_oid_invalid_components_raise():
+    for oid in ("1", "3.1.1", "1.40.1", "9.999.1"):
+        with pytest.raises(ValueError, match=f"Invalid OID structure for '{oid}'"):
+            PublicKey._encode_der_oid(oid)
+
+    with pytest.raises(ValueError, match="non-negative"):
+        PublicKey._encode_der_oid("1.2.-1")
+
+    with pytest.raises(ValueError, match="invalid literal for int()"):
+        PublicKey._encode_der_oid("1.999bit")
+    with pytest.raises(ValueError):
+        PublicKey._encode_der_oid("")
+    with pytest.raises(ValueError):
+        PublicKey._encode_der_oid("...")
+
+
+def test_encode_der_sequence_and_bit_string():
+    assert PublicKey._encode_der_sequence(b"\x01\x02") == b"\x30\x02\x01\x02"
+    assert PublicKey._encode_der_bit_string(b"\xaa\xbb") == b"\x03\x03\x00\xaa\xbb"
+
+
+def test_to_bytes_der_ecdsa_compressed_structure_and_roundtrip(ecdsa_keypair):
+    _, pub = ecdsa_keypair
+    public_key = PublicKey(pub)
+
+    der = public_key.to_bytes_der_ecdsa_compressed()
+    compressed_point = public_key.to_bytes_ecdsa(compressed=True)
+
+    # Fixed SPKI prefix for secp256k1 compressed-point encoding.
+    expected_prefix = bytes.fromhex("3036301006072a8648ce3d020106052b8104000a032200")
+    assert der.startswith(expected_prefix)
+    assert der[len(expected_prefix) :] == compressed_point
+
+    # Ensure produced DER is parseable and preserves the same public key bytes.
+    loaded = PublicKey.from_der(der)
+    assert loaded.is_ecdsa()
+    assert loaded.to_bytes_ecdsa(compressed=True) == compressed_point
+
+
+def test_to_bytes_der_ecdsa_compressed_rejects_ed25519(ed25519_keypair):
+    _, pub = ed25519_keypair
+    public_key = PublicKey(pub)
+
+    with pytest.raises(ValueError, match="only supported for ECDSA"):
+        public_key.to_bytes_der_ecdsa_compressed()
+
+
+def test_encode_vlq_values():
+    assert PublicKey._encode_vlq(0) == b"\x00"
+    assert PublicKey._encode_vlq(127) == b"\x7f"
+    assert PublicKey._encode_vlq(128) == b"\x81\x00"
+    assert PublicKey._encode_vlq(0x4000) == b"\x81\x80\x00"
+
+
 # ------------------------------------------------------------------------------
 # Test: from_string_xxx
 # ------------------------------------------------------------------------------