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

Adds a scalar multiple of the generator to a full public key.

Compressed input produces compressed output and uncompressed input produces uncompressed output. Returns an error for an invalid key or tweak, or when the resulting point would be at infinity.

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

Adds a scalar tweak to a secret key.

This is the private-key counterpart of ec_pubkey_tweak_add/2. The tweak must be a 32-byte scalar less than the secp256k1 curve order; zero is allowed. Returns an error when the tweak is invalid or the resulting secret key would be zero.

@spec valid_pubkey?(Secp256k1.pubkey()) :: boolean()

Checks whether an x-only, compressed, or uncompressed public key can be parsed.

@spec valid_seckey?(Secp256k1.seckey()) :: boolean()

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

@spec xonly_pubkey(Secp256k1.seckey() | Secp256k1.compressed_pubkey()) ::
  Secp256k1.xonly_pubkey() | {:error, binary() | :allocation_failed}

Derives or converts an x-only public key.

A 32-byte secret key derives its x-only public key. A 33-byte compressed public key is converted without requiring its secret key; its parity prefix is omitted from the returned serialization.

Examples

iex> {seckey, _} = Secp256k1.keypair(:compressed)
iex> xonly = Secp256k1.Extrakeys.xonly_pubkey(seckey)
iex> byte_size(xonly)
32

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

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

Returns the tweaked x-only public key together with the parity of the full output point. The parity is required to verify the tweak with xonly_pubkey_tweak_add_check/4.

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

Checks an x-only public-key tweak result, including its parity.

This verifies the key-tweak arithmetic. It does not verify that the tweak was built as a BIP-341 Taproot commitment.

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

Tweaks a secret key using x-only public-key semantics.

Before adding the tweak, this normalizes the keypair so its public key has even Y. Use this result to sign for the output returned by xonly_pubkey_tweak_add/2.