[Advanced]: Implemente compressed DER SPKI export methods for ECDSA secp256k1

[MonaaEid]

🧠 Advanced Contributors — Prerequisites & Expectations

Caution

Advanced issues are the highest-risk work in this project. We will reject PRs that do not meet these standards.

🏁 Concrete Prerequisites

• Proven History: Successfully completed ≥ 10 non-trivial intermediate issues in this repo.
• Consistency: ≥ 3–4 months of active, human-led contributions to this SDK.
• Expertise: Deep architectural understanding of _Executable, Transaction, and Query base classes.
• Advanced Python: Demonstrated proficiency with complex patterns (e.g., async concurrency, decorators, or state management) used in the core SDK.

Note

Workflow Exception: For issues focused on GitHub Actions / Workflows, the Python-specific thresholds above may be waived if the contributor demonstrates expert-level proficiency in CI/CD security and automation.

⚠️ AI Usage Policy

Using AI to generate code for Advanced issues is strictly forbidden. AI may be used only to help explain file relationships. Submitting AI-mined code or unvalidated generated output is grounds for immediate rejection.

⏱️ Timeline & Workflow

• Typical time: ~1 month / ~50 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Mandatory: Post your proposed architectural approach as a comment and wait for explicit maintainer approval before writing any code.

🐞 Problem Description

We need to add compressed DER SPKI export support for ECDSA secp256k1 public keys.

Motivation

• Provide standardized DER encoding utilities for cryptographic operations.

• Ensure interoperability with external systems requiring compressed DER SPKI format.

🛠️ Implementation Notes

Technical domains involved in this issue:

• API Client Architecture (request → serialization → execution → response mapping)
• Backward Compatibility (preserving method signatures, defaults, and return types)
• Protobuf Alignment (reading .proto files, _to_proto() / _from_proto() correctness)
• State & Immutability (correct usage of guards like _require_not_frozen)
• Execution Boundaries (retry logic, backoff, node selection, gRPC deadlines)

Replace this with specific implementation notes.

🛡️ Quality & Review Standards

The bar for advanced PRs is "safe, maintainable, architecturally sound, and production-ready."

🚀 Defining "Production Ready"

1. Architectural Fit: The solution must fit naturally into the existing SDK abstractions. Avoid "hacks" or isolated logic that bypasses the core execution model.
2. Security & Correctness: Evaluate all logic for injection risks, state corruption, or thread-safety issues. Every line of code must be manually verified.
3. Maintainability: Code must be clear enough for any other maintainer to debug without your assistance. Prefer standard patterns over "clever" one-liners.
4. Backward Compatibility: Public API signatures must be preserved. If a breaking change is required, it must be explicitly managed through a deprecation cycle.

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current Hiero SDK architectural approaches.
• I have tested my changes extensively against both local and network environments.
• I have verified naming, types, and field ordering against pinned Protobufs (v0.72.0-rc.2).
• Every line of code is personally understood and explainable (no unvalidated AI code).

📚 Resources & Support

Project References:

• SDK Project Structure
• Transaction Lifecycle
• Hedera Protobufs (v0.72.0-rc.2)

🆘 Stuck?

• Office Hours (Wednesdays, 2pm UTC)
• Discord #hiero-python-sdk

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Extend existing to_bytes_der() and to_string_der() methods with an optional compressed parameter defaulting to False for backward compatibility
• Manually construct DER SPKI structure for compressed output since the cryptography library does not support this natively
• Use RFC 5480-compliant DER encoding with fixed AlgorithmIdentifier prefix for secp256k1 and BIT STRING containing the 33-byte compressed EC point
• Follow existing test patterns with round-trip verification and parametrized key type coverage

Design Choices

Design Choice 1: Should the compressed option modify existing methods or create new dedicated methods?

Options Considered:

1. Add compressed parameter to existing to_bytes_der() and to_string_der() methods with False as default
2. Create entirely new methods to_bytes_der_compressed() and to_string_der_compressed()

Chosen Option: 1

Rationale: Adding a parameter maintains API consistency with to_bytes_ecdsa(compressed=True) and preserves backward compatibility with default False.

Design Choice 2: How should the compressed parameter behave when called on Ed25519 keys?

Options Considered:

1. Raise a TypeError if compressed=True is passed for Ed25519
2. Silently ignore the parameter for Ed25519 keys (parameter only applies to ECDSA)

Chosen Option: 2

Rationale: Silently ignoring aligns with the principle of least surprise—Ed25519 DER output is unambiguous, and erroring would force unnecessary type-checking on callers.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Compressed DER SPKI Implementation

This phase adds the compressed SPKI encoding capability to the PublicKey class. The implementation requires manual DER construction since the cryptography library does not support compressed-point SPKI output directly.

Task 1: Define DER SPKI Structure Constants

Define the fixed DER prefix bytes for secp256k1 SPKI AlgorithmIdentifier to avoid inline magic bytes and enable reuse.

• Add a module-level constant in src/hiero_sdk_python/crypto/public_key.py for the secp256k1 SPKI AlgorithmIdentifier prefix
• The prefix encodes: outer SEQUENCE header placeholder, AlgorithmIdentifier SEQUENCE containing id-ecPublicKey OID (1.2.840.10045.2.1) and secp256k1 OID (1.3.132.0.10)
• Include a brief docstring explaining the DER structure for maintainability

Task 2: Implement Compressed DER SPKI Construction

Add logic to construct compressed-point SPKI DER when requested for ECDSA keys.

• Modify to_bytes_der() in src/hiero_sdk_python/crypto/public_key.py to accept an optional compressed: bool = False parameter
• When compressed=True and key is ECDSA: construct DER manually by concatenating the AlgorithmIdentifier prefix with a BIT STRING containing the 33-byte compressed point from to_bytes_ecdsa(compressed=True)
• When compressed=False or key is Ed25519: delegate to existing cryptography library serialization (current behavior)
• The DER structure follows RFC 5480: SEQUENCE { AlgorithmIdentifier, BIT STRING { unused_bits=0, compressed_point } }

Task 3: Update String Export Method

Propagate the compression option to the hex-string export method.

• Modify to_string_der() in src/hiero_sdk_python/crypto/public_key.py to accept optional compressed: bool = False parameter
• Pass the parameter through to to_bytes_der(compressed=compressed)
• Return the hex encoding of the result (existing pattern)

🤖 Prompt for AI agents

This phase implements compressed DER SPKI encoding for ECDSA secp256k1 public
keys in `src/hiero_sdk_python/crypto/public_key.py`, requiring manual DER
construction since the `cryptography` library does not natively support
compressed-point SPKI output.

**Task 1: Define DER SPKI Structure Constants**
- Add a module-level constant for the secp256k1 SPKI AlgorithmIdentifier prefix
bytes
- The prefix encodes the outer SEQUENCE header placeholder, and an
AlgorithmIdentifier SEQUENCE containing:
  - id-ecPublicKey OID (1.2.840.10045.2.1)
  - secp256k1 OID (1.3.132.0.10)
- Include a brief docstring explaining the DER structure

**Task 2: Implement Compressed DER SPKI Construction**
- Modify `to_bytes_der()` to accept an optional `compressed: bool = False`
parameter
- When `compressed=True` and the key is ECDSA:
- Manually construct the DER output by concatenating the AlgorithmIdentifier
prefix with a BIT STRING wrapping the 33-byte compressed point retrieved via
`to_bytes_ecdsa(compressed=True)`
- Follow RFC 5480 DER structure: `SEQUENCE { AlgorithmIdentifier, BIT STRING {
unused_bits=0, compressed_point } }`
- When `compressed=False` or the key is Ed25519: fall through to the existing
`cryptography` library serialization (no behavior change)

**Task 3: Update String Export Method**
- Modify `to_string_der()` to accept an optional `compressed: bool = False`
parameter
- Pass `compressed=compressed` through to `to_bytes_der()`
- Return the hex encoding of the result, consistent with the existing pattern

Phase 2: Testing

This phase adds comprehensive test coverage for the new compressed DER SPKI functionality, following existing test patterns in the codebase.

Task 1: Add Compressed DER SPKI Export Tests

Verify correct compressed SPKI output structure and content.

• Add test in tests/unit/keys_public_test.py that generates an ECDSA keypair, calls to_bytes_der(compressed=True), and verifies:
  • Output is valid DER (parseable)
  • Output length is 56 bytes (vs ~88 bytes for uncompressed SPKI)
  • Embedded point is 33 bytes (compressed format)
• Add test verifying to_string_der(compressed=True) returns hex encoding of compressed DER
• Follow existing fixture pattern using ecdsa_keypair

Task 2: Add Round-Trip Verification Tests

Ensure compressed SPKI can be loaded back and produces equivalent keys.

• Add test that exports ECDSA key with to_bytes_der(compressed=True), reloads via PublicKey.from_der(), and verifies raw bytes match original
• Verify that compressed SPKI import produces a key that exports identical compressed and uncompressed raw points
• This confirms the cryptography library's load_der_public_key() correctly handles compressed-point SPKI (RFC 5480 compliance)

Task 3: Add Edge Case and Compatibility Tests

Cover boundary conditions and cross-format compatibility.

• Add test verifying Ed25519 keys ignore the compressed parameter (output unchanged whether True or False)
• Add test comparing compressed vs uncompressed SPKI for same ECDSA key—both must reload to identical raw key bytes
• Add test with known test vector: fixed ECDSA private key scalar → derive public key → verify compressed SPKI hex matches expected value
• Add parametrized test covering both key types with @pytest.mark.parametrize("key_type", ["ed25519", "ecdsa"])

🤖 Prompt for AI agents

This phase adds comprehensive test coverage for the compressed DER SPKI
functionality in `tests/unit/keys_public_test.py`, following existing fixture
and round-trip verification patterns in the codebase.

**Task 1: Add Compressed DER SPKI Export Tests**
- Using the existing `ecdsa_keypair` fixture, add a test that calls
`to_bytes_der(compressed=True)` and asserts:
  - Output is valid DER (parseable)
  - Output length is 56 bytes (compared to ~88 bytes for uncompressed SPKI)
  - Embedded point within the output is 33 bytes (compressed format)
- Add a test verifying `to_string_der(compressed=True)` returns the hex encoding
of the compressed DER bytes

**Task 2: Add Round-Trip Verification Tests**
- Add a test that exports an ECDSA key via `to_bytes_der(compressed=True)`,
reloads it with `PublicKey.from_der()`, and verifies the raw bytes match the
original
- Verify that the reloaded key exports identical compressed and uncompressed raw
points as the original, confirming `load_der_public_key()` handles
compressed-point SPKI per RFC 5480

**Task 3: Add Edge Case and Compatibility Tests**
- Add a test confirming Ed25519 keys produce identical output from
`to_bytes_der(compressed=True)` and `to_bytes_der(compressed=False)` (parameter
is silently ignored)
- Add a test comparing compressed vs uncompressed SPKI for the same ECDSA key,
asserting both reload to identical raw key bytes
- Add a known test vector test: derive a public key from a fixed ECDSA private
key scalar and verify the compressed SPKI hex matches an expected hardcoded
value
- Add a parametrized test using `@pytest.mark.parametrize("key_type",
["ed25519", "ecdsa"])` covering both key types

Research

The crypto module in src/hiero_sdk_python/crypto/ contains a unified PublicKey class supporting both Ed25519 and ECDSA secp256k1 keys. The existing to_bytes_der() method delegates to the cryptography library's SubjectPublicKeyInfo serialization, which always produces uncompressed (65-byte) point encoding. The to_bytes_ecdsa(compressed=True) method already supports compressed raw point export. Since the cryptography library does not provide compressed-point SPKI serialization, the implementation must manually construct the DER structure. Test patterns in tests/unit/keys_public_test.py use fixtures returning raw cryptography keypairs and follow round-trip verification patterns.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase implements compressed DER SPKI encoding for ECDSA secp256k1 public
keys in `src/hiero_sdk_python/crypto/public_key.py`, requiring manual DER
construction since the `cryptography` library does not natively support
compressed-point SPKI output.

**Task 1: Define DER SPKI Structure Constants**
- Add a module-level constant for the secp256k1 SPKI AlgorithmIdentifier prefix
bytes
- The prefix encodes the outer SEQUENCE header placeholder, and an
AlgorithmIdentifier SEQUENCE containing:
  - id-ecPublicKey OID (1.2.840.10045.2.1)
  - secp256k1 OID (1.3.132.0.10)
- Include a brief docstring explaining the DER structure

**Task 2: Implement Compressed DER SPKI Construction**
- Modify `to_bytes_der()` to accept an optional `compressed: bool = False`
parameter
- When `compressed=True` and the key is ECDSA:
- Manually construct the DER output by concatenating the AlgorithmIdentifier
prefix with a BIT STRING wrapping the 33-byte compressed point retrieved via
`to_bytes_ecdsa(compressed=True)`
- Follow RFC 5480 DER structure: `SEQUENCE { AlgorithmIdentifier, BIT STRING {
unused_bits=0, compressed_point } }`
- When `compressed=False` or the key is Ed25519: fall through to the existing
`cryptography` library serialization (no behavior change)

**Task 3: Update String Export Method**
- Modify `to_string_der()` to accept an optional `compressed: bool = False`
parameter
- Pass `compressed=compressed` through to `to_bytes_der()`
- Return the hex encoding of the result, consistent with the existing pattern
===============================================================================

Task: 2

This phase adds comprehensive test coverage for the compressed DER SPKI
functionality in `tests/unit/keys_public_test.py`, following existing fixture
and round-trip verification patterns in the codebase.

**Task 1: Add Compressed DER SPKI Export Tests**
- Using the existing `ecdsa_keypair` fixture, add a test that calls
`to_bytes_der(compressed=True)` and asserts:
  - Output is valid DER (parseable)
  - Output length is 56 bytes (compared to ~88 bytes for uncompressed SPKI)
  - Embedded point within the output is 33 bytes (compressed format)
- Add a test verifying `to_string_der(compressed=True)` returns the hex encoding
of the compressed DER bytes

**Task 2: Add Round-Trip Verification Tests**
- Add a test that exports an ECDSA key via `to_bytes_der(compressed=True)`,
reloads it with `PublicKey.from_der()`, and verifies the raw bytes match the
original
- Verify that the reloaded key exports identical compressed and uncompressed raw
points as the original, confirming `load_der_public_key()` handles
compressed-point SPKI per RFC 5480

**Task 3: Add Edge Case and Compatibility Tests**
- Add a test confirming Ed25519 keys produce identical output from
`to_bytes_der(compressed=True)` and `to_bytes_der(compressed=False)` (parameter
is silently ignored)
- Add a test comparing compressed vs uncompressed SPKI for the same ECDSA key,
asserting both reload to identical raw key bytes
- Add a known test vector test: derive a public key from a fixed ECDSA private
key scalar and verify the compressed SPKI hex matches an expected hardcoded
value
- Add a parametrized test using `@pytest.mark.parametrize("key_type",
["ed25519", "ecdsa"])` covering both key types

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Hello, this is CommunityCallBot.

This is a reminder that the Hiero Python SDK Community Call will begin in approximately 4 hours (14:00 UTC).

The call is an open forum where contributors and users can discuss topics, raise issues, and influence the direction of the Python SDK.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.