QANplatform

We express our gratitude to the QANplatform team for the collaborative engagement that enabled the execution of this Blockchain Protocol Security Assessment.

QAN XLINK is a cryptographic protocol that establishes and maintains a cryptographically provable association between Ethereum-compatible Elliptic Curve (secp256k1) private keys and Post-Quantum (ML-DSA-65) private keys, enabling seamless migration to post-quantum cryptography while preserving Ethereum compatibility until quantum computers break elliptic curve cryptography.

The system users should acknowledge all the risks summed up in the risks section of the report

{FindingsVulnSeverityStatusTable}

Documentation quality

• Excellent README documentation: The README provides a comprehensive overview with a clear problem statement, solution approach, goals, non-goals, and detailed technical specifications, including byte-level format descriptions.

• Comprehensive inline documentation: All public functions, types, and methods have detailed Go doc comments explaining their purpose, parameters, return values, and usage patterns.

• Clear API documentation: Function signatures are well-documented with parameter descriptions, error conditions, and usage examples (e.g., New() function has detailed parameter explanations).

• Security-focused documentation: Critical security considerations are explicitly documented, such as warnings about ValidateVerbose() not being suitable for public-facing domains due to error information leakage.

• Technical specification completeness: The README includes detailed byte-level format specifications, message structures, and cryptographic protocol details with code examples.

• Error handling documentation: Error conditions and validation requirements are clearly documented (e.g., chain ID validation, private key requirements).

• Usage pattern documentation: Clear examples of how to use different payload types (Link, Renew, Relink) and their specific purposes.

• Constant and type documentation: All constants, types, and interfaces have explanatory comments describing their purpose and usage.

• Area to improve would be to add missing API usage examples: While the README explains the concept well, it lacks concrete code examples showing how to create and use XLINK objects in practice.

• Another area to improve is to expand error message documentation: Some error conditions could benefit from more detailed explanations of when they occur and how to resolve them.

Code quality

• Excellent code reuse through shared interfaces and common functions: The codebase uses a well-designed Payload interface and shared functions.

• Consistent template patterns with proper abstraction: The loader functions follow a consistent pattern using generic helper functions (loadPayloadFromHex, loadPayloadFromPem) that accept payload-specific loaders as parameters.

• Well-structured inheritance hierarchy: All payload types (Link, Renew, Relink) properly implement the Payload interface and share common functionality through corePayload embedding.

• Proper separation of concerns: Cryptographic operations, payload handling, address management, and validation are cleanly separated into different modules.

• Consistent error handling patterns: All functions follow Go conventions with proper error returns and descriptive error messages.

• Good use of Go generics.

• Proper memory management.

• Constants are cleanly organized and logically grouped.

Architecture quality

• A library-based design with no inherent scalability limitations: XLINK is a cryptographic library that can be integrated into any blockchain system, with payload sizes optimized for efficiency (Link: 5.3KB, Renew: 3.4KB, Relink: 8.6KB).

• Fully decentralized cryptographic protocol: No central authorities or trusted parties are required; all validation is performed locally using cryptographic proofs and public key recovery.

• Optimized for efficiency with constant-time validation: Uses efficient cryptographic operations, constant-time execution for security, and minimal payload sizes compared to pure post-quantum alternatives (5000%+ storage savings mentioned in README).

• High compatibility with Ethereum ecosystem: Built on standard secp256k1 and ML-DSA-65, supports EIP-155 chain IDs, Ethereum address derivation, and can be adapted by any newly-launched blockchain.

• Strong cryptographic guarantees with comprehensive validation: Implements constant-time validation, secure key disposal, cross-signature verification, and comprehensive test coverage (19 test functions) including failure scenarios and edge cases.

• Well-structured interfaces, shared validation logic, and clean abstraction layers between cryptographic operations, payload handling, and address management.

• Future-proof architecture with versioning support: Built-in versioning system for backward compatibility and planned migration roadmap (2027-2029) for post-quantum transition.

• Minimal external dependencies: Only depends on established cryptographic libraries (Cloudflare CIRCL, Go Ethereum) with no complex external integrations or single points of failure.

Test coverage

The test coverage is comprehensive for core functionality with excellent negative case coverage, but lacks multi-user scenarios and performance testing.

• A comprehensive test suite with 19 test functions and 46 sub-tests: The test file xlink_test.go contains extensive coverage with multiple test scenarios for each major functionality.

• Strong positive case coverage: All three payload types (Link, Renew, Relink) are thoroughly tested for creation, serialization, validation, and round-trip operations with 100% success path coverage.

• Excellent negative case coverage: Tests include 20+ error condition checks covering nil parameter validation, invalid payload sizes, corrupted signatures, malformed hex/PEM data, and boundary conditions.

• Comprehensive edge case testing: The test suite covers timestamp validation ranges, chain ID boundaries, mnemonic validation (23/24/25 words), address format validation, and cryptographic failure scenarios.

• Security-focused test coverage: The suite includes tests for replay attack prevention, signature tampering detection, key zeroization, and private key isolation to prevent memory leaks.

• Good integration test coverage: Tests cover complete workflows including payload creation, serialization/deserialization, validation, and cross-format conversions (bytes/hex/PEM).

• Limited concurrent user testing: Tests focus on single-user scenarios with no multi-user interaction testing or concurrent access patterns.

• Missing performance and stress testing: The test suite includes no benchmarks, load testing, or performance regression tests for cryptographic operations or large payload handling.

• Strong mutation testing foundation: The 77% mutation score indicates good test quality with comprehensive assertion coverage and proper error condition validation.

XLINK is a cryptographic protocol library that enables seamless migration from Elliptic Curve to Post-Quantum cryptography for blockchain systems.

Xlink Engine — the main cryptographic engine that manages key pairs and creates XLINK payloads. It handles both Elliptic Curve (secp256k1) and Post-Quantum (ML-DSA-65) private keys derived from the same mnemonic seed. Key capabilities include:

• Key Management: Derives EC and PQ key pairs from 24-word BIP-39 mnemonics.

• Payload Creation: Generates Link, Renew, and Relink payloads with cross-signatures.

• Address Generation: Creates both Ethereum-compatible and XLINK addresses.

• Secure Disposal: Implements secure key zeroization through the Close() method.

Loader: a component that parses and validates XLINK payloads from various formats (bytes, hex, PEM). It supports all three payload types and performs cryptographic validation.

Payload Types — three distinct cryptographic certificates:

• Link: Establishes the initial binding between EC and PQ public keys (5.3KB payload)

• Renew: Proves recent knowledge of PQ private key for ongoing validation (3.4KB payload)

• Relink: Enables emergency re-linking with new PQ keys if the original is compromised (8.6KB payload)

Address System — a dual addressing scheme supporting both Ethereum-compatible addresses (derived from EC keys) and XLINK addresses (derived from PQ key hashes) with enhanced checksumming and collision resistance. The protocol ensures 100% successful migration to post-quantum cryptography without user interaction, while maintaining full Ethereum ecosystem compatibility until quantum computers break elliptic curve cryptography.

The scope of the project includes the following components from the provided repository:

Components in Scope

The entire xlink folder, which includes:

• Key Generation & Derivation;

• Signature Generation & Verification;

• Address Derivation;

• Payload Creation & Validation;

• Link Payload;

• Renew Payload;

• Relink Payload;

• Cross-Validation Logic;

• Payload Serialization & Deserialization;

• State & Memory Management, Key Lifecycle, Memory Safety;

• Timestamp & Replay Protection;

• Version & Protocol Management;

• Utility & Helper Functions.

Retest

Below are the SHA256 checksum of all the files after remediation being applied:

• address.go 708581811da94c181be393cb1e03bef2913d68fedaa9b4ce91a54df12c152f7b

• crypto.go cdd8460e8c83e6cfa174f73c2cf2be1243015379bfb8fb8322ee7f0b9b61d8a3

• helpers.go - 018e0d3d1e3eb404be9cbaa789453fbba630395752d0da52973cab4952b8a828

• link.go - 8774d14793ce1482d1f13e104eb2160b8b64c7db109a490b62543c3278358258

• loader.go - b17318a62ed683b1cc0ade72485a6fb554727c95ab273321a734c121dcbd5630

• payload.go - 8aea5349cdacd46733f11180e2503478e4ae99a3fa14a42698809699fe85aafb

• pqpublickey.go - 025421e7c0cf2132c49baf7b6554fb46a24684959b92082e9d1fc9f81129db49

• relink.go - d451d634180ac5ebe194ef4e034d318a777262c87bf7aa673245f91552cca8bc

• renew.go - ec61874cd9053c42366d650cc33760d7646cc6ad7e7c487e39c48a5cbad392ff

• timestamp.go - 619b9dc7a8eaf193b3057605666108c33b2538b1b9f30bcadac50d73760f3fed

• version.go - e30bfbdad9d0407334e2de3d74353bfd03cb9020ce098c2f3cc625597f56e956

• wordlist.go - 6653a99cbcba64bba0c0a2ffcd491f4fcb2c072fe55a8e24bde4ece2697e368e

• xlink.go - 3af7cb263fd5599df8465ed523b00277a1053092077fef09e49a502f0ee8777e

• xlink_test.go - 92e9ebb0d50149a6cda9fd92e94cd30ddd91b7bbc8cc17781a1057b6ef87215a

• go.mod - 39122d384bcd5028ff2339fb12351bfba317084ca91c66953072f3f296b8c3c4

• go.sum - 70eb38aecbf0afd9096075defcdfd423a162b4348b892187c8c6f3b3f1506ca2

• HACKEN_AUDIT_ANALYSIS_RESULT_REMEDIATION.md - 4cb3b536ae98038f55fab04a561d2c8c23d43d73d3e91f12688e1cb69337ab1d

• README.md - f0bcda0e5d9967b08d057c46cfed3ad3f721f1c90ee762139826bbac6c25608f