@spec convert_pubkey(
  pubkey :: compressed_pubkey() | uncompressed_pubkey(),
  type :: :compressed | :uncompressed | :xonly
) ::
  compressed_pubkey()
  | uncompressed_pubkey()
  | xonly_pubkey()
  | {:error, binary() | :allocation_failed}

Convert a public key to another serialization format.

Inputs

• pubkey an uncompressed public key when converting to :compressed, or a compressed public key when converting to :uncompressed or :xonly
• type the target format, either :compressed, :uncompressed, or :xonly

Returns the converted public key, or {:error, reason} when the correctly sized input does not encode a valid secp256k1 public key.

@spec ec_pubkey_tweak_add(compressed_pubkey() | uncompressed_pubkey(), tweak()) ::
  compressed_pubkey()
  | uncompressed_pubkey()
  | {:error, binary() | :allocation_failed}

Adds a scalar multiple of the generator to a compressed or uncompressed public key.

The output preserves the input serialization format. This is the public-key counterpart of ec_seckey_tweak_add/2 for BIP-32-style public derivation.

@spec ec_seckey_tweak_add(seckey(), tweak()) ::
  seckey() | {:error, binary() | :allocation_failed}

Adds a scalar tweak to a secret key for BIP-32-style private derivation.

Returns an error when the tweak is outside the scalar field or the resulting key would be zero.

@spec ecdh(seckey :: seckey(), pubkey :: compressed_pubkey() | uncompressed_pubkey()) ::
  shared_secret()

Compute libsecp256k1's default hashed ECDH shared secret.

Inputs

• seckey 32 byte long binary
• pubkey compressed or uncompressed secp256k1 public key

Output

• shared_secret 32 byte binary

This wraps libsecp256k1's ECDH module. It returns the upstream library's default hashed ECDH output, currently SHA256 over the compressed shared point. For generic raw ECDH, use :crypto.compute_key/4.

@spec ecdsa_sign(msg_hash :: hash(), seckey :: seckey()) :: ecdsa_sig()

Create an ECDSA signature

Inputs

• msg_hash 32 byte long message hash to sign
• seckey 32 byte long binary

Output

• signature ECDSA signature serialized in compressed format (64 byte binary)

@spec ecdsa_signature_normalize(ecdsa_sig()) ::
  ecdsa_sig() | {:error, binary() | :allocation_failed}

Converts a compact ECDSA signature to the low-S form required by libsecp256k1 verification.

Already-normalized signatures are returned unchanged. Normalization accepts a malleable alternate encoding; use it only when the protocol deliberately accepts mathematical equivalence, and use the normalized bytes thereafter. Protocols requiring canonical low-S signatures should reject high-S instead.

@spec ecdsa_signature_parse_der(ecdsa_der_sig()) ::
  ecdsa_sig() | {:error, binary() | :allocation_failed}

Parses an 8-72-byte strict DER ECDSA signature into compact 64-byte r || s form.

Remove any trailing Bitcoin transaction sighash byte before parsing. Wrong-sized input raises FunctionClauseError; malformed DER in the accepted size range raises ArgumentError.

@spec ecdsa_signature_serialize_der(ecdsa_sig()) ::
  ecdsa_der_sig() | {:error, binary() | :allocation_failed}

Serializes a compact 64-byte ECDSA signature as strict DER.

The result does not include a Bitcoin transaction sighash byte.

@spec ecdsa_valid?(
  signature :: ecdsa_sig(),
  msg_hash :: hash(),
  pubkey :: compressed_pubkey() | uncompressed_pubkey()
) :: boolean()

Validate ECDSA signature.

High-S signatures return false. Normalize only if the surrounding protocol deliberately accepts malleable signature encodings.

Inputs

• signature 64 byte long binary
• msg_hash 32 byte long message hash that was signed
• pubkey compressed (33-byte) or uncompressed (65-byte) public key

@spec keypair(type :: pubkey_type()) :: {seckey(), pubkey()}

Generate new secp256k1 keypair

Input

• type (see pubkey/2)

Output

• 2-tuple with seckey on the first place and pubkey on the second place

@spec keypair(seckey :: seckey(), type :: pubkey_type()) :: {seckey(), pubkey()}

Generate new secp256k1 keypair from provided seckey

For options see pubkey/2

@spec pubkey(seckey :: seckey(), type :: pubkey_type()) :: pubkey()

Derive pubkey from provided seckey

Inputs

• seckey 32 byte long binary
• type one of :xonly, :compressed or :uncompressed

Output

• pubkey serialization type depends on the type provided

@spec schnorr_sign(message :: binary(), seckey :: seckey()) :: schnorr_sig()

Calculate Schnorr signature according to BIP 340

Inputs

• message can accept arbitrary long binary but only 32 byte long hash is the only option strictly according to specification
• seckey 32 byte long binary

Output

• signature Schnorr signature is 64 byte long binary

Note: automatic random nonce is added to every run so generated signature is not deterministic

@spec schnorr_valid?(
  signature :: schnorr_sig(),
  message :: binary(),
  pubkey :: xonly_pubkey()
) :: boolean()

Validate Schnorr signature

Inputs

• signature 64 byte long binary
• message arbitrary long binary
• pubkey xonly pubkey (32 byte long binary)

@spec valid_pubkey?(term()) :: boolean()

Checks whether a binary encodes a valid secp256k1 public key.

Accepts x-only (32-byte), compressed (33-byte), and uncompressed (65-byte) public-key encodings. Returns false for unsupported encodings, wrong-sized binaries, and non-binary terms.

@spec valid_seckey?(term()) :: boolean()

Checks whether a 32-byte binary is a valid secp256k1 secret key.

This validates the scalar value, not only the binary size. A valid secret key is greater than zero and smaller than the secp256k1 curve order. Returns false for wrong-sized binaries and non-binary terms.

@spec xonly_pubkey_tweak_add(xonly_pubkey(), tweak()) ::
  {:ok, xonly_pubkey(), pubkey_parity()}
  | {:error, binary() | :allocation_failed}

Adds a scalar tweak to an x-only internal public key.

Returns the x-only output key and its full-point parity. Keep both values when constructing and verifying Taproot commitments.

@spec xonly_pubkey_tweak_add_check(
  xonly_pubkey(),
  pubkey_parity(),
  xonly_pubkey(),
  tweak()
) :: boolean()

Checks an x-only public-key tweak result and parity.

This verifies the key arithmetic only. The caller remains responsible for deriving the tweak according to BIP-341 when using it as a Taproot commitment.

@spec xonly_seckey_tweak_add(seckey(), tweak()) ::
  seckey() | {:error, binary() | :allocation_failed}

Tweaks a secret key using x-only semantics for signing Taproot outputs.

The keypair is normalized to an even-Y internal public key before adding the tweak.