Developer Interface¶

All objects are available directly under the root namespace coincurve.

`verify_signature(signature: bytes, message: bytes, public_key: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> bool` ¶

Verify an ECDSA signature.

Parameters:

Name	Type	Description	Default
`signature`	`bytes`	The ECDSA signature.	required
`message`	`bytes`	The message that was supposedly signed.	required
`public_key`	`bytes`	The formatted public key.	required
`hasher`	`Callable[[bytes], bytes] \| None`	The hash function to use, which must return 32 bytes. By default, the `sha256` algorithm is used. If `None`, no hashing occurs.	`sha256`
`context`	`Context`	The secp256k1 context.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`bool`	A boolean indicating whether or not the signature is correct.

Raises:

Type	Description
`ValueError`	If the public key could not be parsed or was invalid, the message hash was not 32 bytes long, or the DER-encoded signature could not be parsed.

`PrivateKey` ¶

`init(secret: bytes | None = None, context: Context = GLOBAL_CONTEXT)` ¶

Initializes a private key.

Parameters:

Name	Type	Description	Default
`secret`	`bytes \| None`	The secret used to initialize the private key. If not provided, a new key will be generated.	`None`
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

`sign(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes` ¶

Creates an ECDSA signature.

Parameters:

Name	Type	Description	Default
`message`	`bytes`	The message to sign.	required
`hasher`	`Callable[[bytes], bytes] \| None`	The hash function to use, which must return 32 bytes. By default, the `sha256` algorithm is used. If `None`, no hashing occurs.	`sha256`
`custom_nonce`	`tuple[CData, CData]`	Custom nonce data in the form `(nonce_function, input_data)`. For more information, refer to the `libsecp256k1` documentation here.	`DEFAULT_NONCE`

Returns:

Type	Description
`bytes`	The ECDSA signature.

Raises:

Type	Description
`ValueError`	If the message hash was not 32 bytes long, the nonce generation function failed, or the private key was invalid.

`sign_recoverable(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes` ¶

Creates a recoverable ECDSA signature.

Parameters:

Name	Type	Description	Default
`message`	`bytes`	The message to sign.	required
`hasher`	`Callable[[bytes], bytes] \| None`	The hash function to use, which must return 32 bytes. By default, the `sha256` algorithm is used. If `None`, no hashing occurs.	`sha256`
`custom_nonce`	`tuple[CData, CData]`	Custom nonce data in the form `(nonce_function, input_data)`. For more information, refer to the `libsecp256k1` documentation here.	`DEFAULT_NONCE`

Returns:

Type	Description
`bytes`	The recoverable ECDSA signature.

Raises:

Type	Description
`ValueError`	If the message hash was not 32 bytes long, the nonce generation function failed, or the private key was invalid.

`sign_schnorr(message: bytes, aux_randomness: bytes = b'') -> bytes` ¶

Creates a Schnorr signature.

Parameters:

Name	Type	Description	Default
`message`	`bytes`	The message to sign.	required
`aux_randomness`	`bytes`	32 bytes of fresh randomness, empty bytestring (auto-generated), or None (no randomness).	`b''`

Returns:

Type	Description
`bytes`	The Schnorr signature.

Raises:

Type	Description
`ValueError`	If the message was not 32 bytes long, the optional auxiliary random data was not 32 bytes long, signing failed, or the signature was invalid.

`ecdh(public_key: bytes) -> bytes` ¶

Computes an EC Diffie-Hellman secret in constant time.

Note

This prevents malleability by returning sha256(compressed_public_key) instead of the x coordinate directly.

Parameters:

Name	Type	Description	Default
`public_key`	`bytes`	The formatted public key.	required

Returns:

Type	Description
`bytes`	The 32-byte shared secret.

Raises:

Type	Description
`ValueError`	If the public key could not be parsed or was invalid.

`add(scalar: bytes, update: bool = False) -> PrivateKey` ¶

Adds a scalar to the private key.

Parameters:

Name	Type	Description	Default
`scalar`	`bytes`	The scalar with which to add.	required
`update`	`bool`	Whether to update the private key in-place.	`False`

Returns:

Type	Description
`PrivateKey`	The new private key, or the modified private key if `update` is `True`.

Raises:

Type	Description
`ValueError`	If the tweak was out of range or the resulting private key was invalid.

`multiply(scalar: bytes, update: bool = False) -> PrivateKey` ¶

Multiplies the private key by a scalar.

Parameters:

Name	Type	Description	Default
`scalar`	`bytes`	The scalar with which to multiply.	required
`update`	`bool`	Whether to update the private key in-place.	`False`

Returns:

Type	Description
`PrivateKey`	The new private key, or the modified private key if `update` is `True`.

`to_int() -> int` ¶

Returns the private key as an integer.

`to_hex() -> str` ¶

Returns the private key encoded as a hex string.

`to_pem() -> bytes` ¶

Returns the private key encoded in PEM format.

`to_der() -> bytes` ¶

Returns the private key encoded in DER format.

`from_int(num: int, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

Creates a private key from an integer.

Parameters:

Name	Type	Description	Default
`num`	`int`	The private key as an integer.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PrivateKey`	The private key.

`from_hex(hexed: str, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

Creates a private key from a hex string.

Parameters:

Name	Type	Description	Default
`hexed`	`str`	The private key encoded as a hex string.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PrivateKey`	The private key.

`from_pem(pem: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

Creates a private key from PEM format.

Parameters:

Name	Type	Description	Default
`pem`	`bytes`	The private key encoded in PEM format.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PrivateKey`	The private key.

`from_der(der: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

Creates a private key from DER format.

Parameters:

Name	Type	Description	Default
`der`	`bytes`	The private key encoded in DER format.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PrivateKey`	The private key.

`PublicKey` ¶

`init(data: bytes | ffi.CData, context: Context = GLOBAL_CONTEXT)` ¶

Initializes a public key.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	The formatted public key. This class supports parsing compressed (33 bytes, header byte `0x02` or `0x03`), uncompressed (65 bytes, header byte `0x04`), or hybrid (65 bytes, header byte `0x06` or `0x07`) format public keys.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Raises:

Type	Description
`ValueError`	If the public key could not be parsed or was invalid.

`verify(signature: bytes, message: bytes, hasher: Hasher = sha256) -> bool` ¶

Verifies an ECDSA signature.

Parameters:

Name	Type	Description	Default
`signature`	`bytes`	The ECDSA signature.	required
`message`	`bytes`	The message that was supposedly signed.	required
`hasher`	`Callable[[bytes], bytes] \| None`	The hash function to use, which must return 32 bytes. By default, the `sha256` algorithm is used. If `None`, no hashing occurs.	`sha256`

Returns:

Type	Description
`bool`	A boolean indicating whether the signature is correct.

Raises:

Type	Description
`ValueError`	If the message hash was not 32 bytes long or the DER-encoded signature could not be parsed.

`format(compressed: bool = True) -> bytes` ¶

Formats the public key.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	Whether to use the compressed format.	`True`

Returns:

Type	Description
`bytes`	The 33 byte formatted public key, or the 65 byte formatted public key
`bytes`	if `compressed` is `False`.

`point() -> tuple[int, int]` ¶

Returns the public key as a coordinate point.

`combine(public_keys: list[PublicKey], update: bool = False) -> PublicKey` ¶

Adds a number of public keys together.

Parameters:

Name	Type	Description	Default
`public_keys`	`list[PublicKey]`	A sequence of public keys.	required
`update`	`bool`	Whether to update the public key in-place.	`False`

Returns:

Type	Description
`PublicKey`	The combined public key, or the modified public key if `update` is `True`.

Raises:

Type	Description
`ValueError`	If the sum of the public keys was invalid.

`add(scalar: bytes, update: bool = False) -> PublicKey` ¶

Adds a scalar to the public key.

Parameters:

Name	Type	Description	Default
`scalar`	`bytes`	The scalar with which to add.	required
`update`	`bool`	Whether to update the public key in-place.	`False`

Returns:

Type	Description
`PublicKey`	The new public key, or the modified public key if `update` is `True`.

Raises:

Type	Description
`ValueError`	If the tweak was out of range or the resulting public key was invalid.

`multiply(scalar: bytes, update: bool = False) -> PublicKey` ¶

Multiplies the public key by a scalar.

Parameters:

Name	Type	Description	Default
`scalar`	`bytes`	The scalar with which to multiply.	required
`update`	`bool`	Whether to update the public key in-place.	`False`

Returns:

Type	Description
`PublicKey`	The new public key, or the modified public key if `update` is `True`.

`combine_keys(public_keys: list[PublicKey], context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

Adds a number of public keys together.

Parameters:

Name	Type	Description	Default
`public_keys`	`list[PublicKey]`	A sequence of public keys.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKey`	The combined public key.

Raises:

Type	Description
`ValueError`	If the sum of the public keys was invalid.

`from_signature_and_message(signature: bytes, message: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

Recovers an ECDSA public key from a recoverable signature.

Parameters:

Name	Type	Description	Default
`signature`	`bytes`	The recoverable ECDSA signature.	required
`message`	`bytes`	The message that was supposedly signed.	required
`hasher`	`Callable[[bytes], bytes] \| None`	The hash function to use, which must return 32 bytes. By default, the `sha256` algorithm is used. If `None`, no hashing occurs.	`sha256`
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKey`	The public key that signed the message.

Raises:

Type	Description
`ValueError`	If the message hash was not 32 bytes long or recovery of the ECDSA public key failed.

`from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

Derives a public key from a private key secret.

Parameters:

Name	Type	Description	Default
`secret`	`bytes`	The private key secret.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKey`	The public key.

Raises:

Type	Description
`ValueError`	If an invalid secret was used.

`from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

Derives a public key from a valid private key secret, avoiding input checks.

Parameters:

Name	Type	Description	Default
`secret`	`bytes`	The private key secret.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKey`	The public key.

Raises:

Type	Description
`ValueError`	If the secret was invalid.

`from_point(x: int, y: int, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

Derives a public key from a coordinate point.

Parameters:

Name	Type	Description	Default
`x`	`int`	The x coordinate.	required
`y`	`int`	The y coordinate.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKey`	The public key.

`PublicKeyXOnly` ¶

`init(data: bytes | ffi.CData, parity: bool = False, context: Context = GLOBAL_CONTEXT)` ¶

Initializes a BIP340 x-only public key.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	The formatted public key.	required
`parity`	`bool`	Whether the encoded point is the negation of the public key.	`False`
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Raises:

Type	Description
`ValueError`	If the public key could not be parsed or is invalid.

`verify(signature: bytes, message: bytes) -> bool` ¶

Verifies a Schnorr signature over a given message.

Parameters:

Name	Type	Description	Default
`signature`	`bytes`	The 64-byte Schnorr signature to verify.	required
`message`	`bytes`	The message to be verified.	required

Returns:

Type	Description
`bool`	A boolean indicating whether the signature is correct.

Raises:

Type	Description
`ValueError`	If the signature is not 64 bytes long.

`format() -> bytes` ¶

Serializes the public key.

Returns:

Type	Description
`bytes`	The public key serialized as 32 bytes.

Raises:

Type	Description
`ValueError`	If the public key in `self.public_key` is invalid.

`tweak_add(scalar: bytes) -> None` ¶

Adds a scalar to the public key.

Parameters:

Name	Type	Description	Default
`scalar`	`bytes`	The scalar with which to add.	required

Returns:

Type	Description
`None`	The modified public key.

Raises:

Type	Description
`ValueError`	If the tweak was out of range or the resulting public key would be invalid.

`from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly` `classmethod` ¶

Derives an x-only public key from a private key secret.

Parameters:

Name	Type	Description	Default
`secret`	`bytes`	The private key secret.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKeyXOnly`	The x-only public key.

Raises:

Type	Description
`ValueError`	If the secret was invalid.

`from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly` `classmethod` ¶

Derives an x-only public key from a valid private key secret, avoiding input checks.

Parameters:

Name	Type	Description	Default
`secret`	`bytes`	The private key secret.	required
`context`	`Context`	The context to use.	`GLOBAL_CONTEXT`

Returns:

Type	Description
`PublicKeyXOnly`	The x-only public key.

Raises:

Type	Description
`ValueError`	If the secret was invalid.

Developer Interface¶

verify_signature(signature: bytes, message: bytes, public_key: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> bool ¶

PrivateKey ¶

__init__(secret: bytes | None = None, context: Context = GLOBAL_CONTEXT) ¶

sign(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes ¶

sign_recoverable(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes ¶

sign_schnorr(message: bytes, aux_randomness: bytes = b'') -> bytes ¶

ecdh(public_key: bytes) -> bytes ¶

add(scalar: bytes, update: bool = False) -> PrivateKey ¶

multiply(scalar: bytes, update: bool = False) -> PrivateKey ¶

to_int() -> int ¶

to_hex() -> str ¶

to_pem() -> bytes ¶

to_der() -> bytes ¶

from_int(num: int, context: Context = GLOBAL_CONTEXT) -> PrivateKey classmethod ¶

from_hex(hexed: str, context: Context = GLOBAL_CONTEXT) -> PrivateKey classmethod ¶

from_pem(pem: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey classmethod ¶

from_der(der: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey classmethod ¶

PublicKey ¶

__init__(data: bytes | ffi.CData, context: Context = GLOBAL_CONTEXT) ¶

verify(signature: bytes, message: bytes, hasher: Hasher = sha256) -> bool ¶

format(compressed: bool = True) -> bytes ¶

point() -> tuple[int, int] ¶

combine(public_keys: list[PublicKey], update: bool = False) -> PublicKey ¶

add(scalar: bytes, update: bool = False) -> PublicKey ¶

multiply(scalar: bytes, update: bool = False) -> PublicKey ¶

combine_keys(public_keys: list[PublicKey], context: Context = GLOBAL_CONTEXT) -> PublicKey classmethod ¶

from_signature_and_message(signature: bytes, message: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> PublicKey classmethod ¶

from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey classmethod ¶

from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey classmethod ¶

from_point(x: int, y: int, context: Context = GLOBAL_CONTEXT) -> PublicKey classmethod ¶

PublicKeyXOnly ¶

__init__(data: bytes | ffi.CData, parity: bool = False, context: Context = GLOBAL_CONTEXT) ¶

verify(signature: bytes, message: bytes) -> bool ¶

format() -> bytes ¶

tweak_add(scalar: bytes) -> None ¶

from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly classmethod ¶

from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly classmethod ¶

`verify_signature(signature: bytes, message: bytes, public_key: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> bool` ¶

`PrivateKey` ¶

`init(secret: bytes | None = None, context: Context = GLOBAL_CONTEXT)` ¶

`sign(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes` ¶

`sign_recoverable(message: bytes, hasher: Hasher = sha256, custom_nonce: Nonce = DEFAULT_NONCE) -> bytes` ¶

`sign_schnorr(message: bytes, aux_randomness: bytes = b'') -> bytes` ¶

`ecdh(public_key: bytes) -> bytes` ¶

`add(scalar: bytes, update: bool = False) -> PrivateKey` ¶

`multiply(scalar: bytes, update: bool = False) -> PrivateKey` ¶

`to_int() -> int` ¶

`to_hex() -> str` ¶

`to_pem() -> bytes` ¶

`to_der() -> bytes` ¶

`from_int(num: int, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

`from_hex(hexed: str, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

`from_pem(pem: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

`from_der(der: bytes, context: Context = GLOBAL_CONTEXT) -> PrivateKey` `classmethod` ¶

`PublicKey` ¶

`init(data: bytes | ffi.CData, context: Context = GLOBAL_CONTEXT)` ¶

`verify(signature: bytes, message: bytes, hasher: Hasher = sha256) -> bool` ¶

`format(compressed: bool = True) -> bytes` ¶

`point() -> tuple[int, int]` ¶

`combine(public_keys: list[PublicKey], update: bool = False) -> PublicKey` ¶

`add(scalar: bytes, update: bool = False) -> PublicKey` ¶

`multiply(scalar: bytes, update: bool = False) -> PublicKey` ¶

`combine_keys(public_keys: list[PublicKey], context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

`from_signature_and_message(signature: bytes, message: bytes, hasher: Hasher = sha256, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

`from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

`from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

`from_point(x: int, y: int, context: Context = GLOBAL_CONTEXT) -> PublicKey` `classmethod` ¶

`PublicKeyXOnly` ¶

`init(data: bytes | ffi.CData, parity: bool = False, context: Context = GLOBAL_CONTEXT)` ¶

`verify(signature: bytes, message: bytes) -> bool` ¶

`format() -> bytes` ¶

`tweak_add(scalar: bytes) -> None` ¶

`from_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly` `classmethod` ¶

`from_valid_secret(secret: bytes, context: Context = GLOBAL_CONTEXT) -> PublicKeyXOnly` `classmethod` ¶