Package xyz.tcheeric.cashu.voucher.domain

Class VoucherFingerprint

java.lang.Object
xyz.tcheeric.cashu.voucher.domain.VoucherFingerprint
public class VoucherFingerprint extends Object
Cryptographic fingerprinting for Cashu vouchers.

Provides collision-resistant fingerprints for vouchers based on their unique identifiers. The fingerprint is deterministic and can be used for:

  • Duplicate detection during redemption
  • Idempotency key generation for API calls
  • Tracking redemption attempts across distributed systems

Algorithm

The fingerprint is computed as SHA-256 of a canonical string representation: 

   SHA-256(voucherId || "|" || issuerId || "|" || signature)

Including the signature ensures that even if a voucher ID is reused (which should not happen), different signatures produce different fingerprints.

Security Properties

  • Deterministic: Same voucher always produces same fingerprint
  • Collision-resistant: Different vouchers produce different fingerprints
  • Non-reversible: Cannot derive voucher details from fingerprint
See Also:

  • Constructor Details

    • VoucherFingerprint

      public VoucherFingerprint()

  • Method Details

    • compute

      public String compute(SignedVoucher voucher)
      Computes the fingerprint for a signed voucher.
      Parameters:
      voucher - the signed voucher to fingerprint (must not be null)
      Returns:
      64-character hex-encoded SHA-256 hash
      Throws:
      IllegalArgumentException - if voucher is null

    • compute

      public String compute(xyz.tcheeric.cashu.common.VoucherSecret secret)
      Computes the fingerprint for a voucher secret.

      The fingerprint includes:

      • Voucher ID (UUID)
      • Issuer ID
      • Signature (if present)
      Parameters:
      secret - the voucher secret to fingerprint (must not be null)
      Returns:
      64-character hex-encoded SHA-256 hash
      Throws:
      IllegalArgumentException - if secret is null or missing required fields

    • compute

      public String compute(String voucherId, String issuerId, String signature)
      Computes the fingerprint from raw voucher components.

      This method is useful when you have the components but not the full VoucherSecret object.

      Parameters:
      voucherId - the voucher ID (must not be null or blank)
      issuerId - the issuer ID (must not be null or blank)
      signature - the signature hex string (may be null)
      Returns:
      64-character hex-encoded SHA-256 hash

    • isValid

      public boolean isValid(String fingerprint)
      Validates that a fingerprint matches the expected format.
      Parameters:
      fingerprint - the fingerprint to validate
      Returns:
      true if the fingerprint is a valid 64-character hex string