Documentation

A bitcoin-core/secp256k1 context.

bitcoin-core/secp256k1 computations typically require a context, the primary purpose of which is to store randomization data as increased protection against side-channel attacks (and the second of which is boring pointer storage to various library callbacks).

You should create and use values of this type via wrcontext or wcontext.

The data constructor is exported only to make the implementation easier to benchmark. You should not pattern match on or manipulate context values.

Execute the supplied continuation within a fresh bitcoin-core/secp256k1 context. The context will be destroyed afterwards.

This function executes the supplied continuation in a context that has not been randomized, and so doesn't offer additional side-channel attack protection. For that, use wrcontext.

>>> wcontext $ \tex -> parse_pub tex bytestring
"<bitcoin-core/secp256k1 public key>"

Same as wcontext, but randomize the bitcoin-core/secp256k1 context with the provided 32 bytes of entropy before executing the supplied continuation.

Use this function to execute computations that may benefit from additional side-channel attack protection.

>>> wrcontext entropy $ \tex -> sign tex sec msg
"<bitcoin-core/secp256k1 signature>"

A bitcoin-core/secp256k1-internal ECDSA signature.

Create a value of this type via sign, or parse a DER-encoded signature via parse_der.

Sign a 32-byte message hash with the provided secret key.

>>> wrcontext entropy $ \tex -> sign tex sec msg
"<bitcoin-core/secp256k1 signature>"

Verify an ECDSA signature for the provided message hash with the supplied public key.

Returns True for a verifying signature, False otherwise.

>>> wcontext $ \tex -> verify tex pub msg good_sig
True
>>> wcontext $ \tex -> verify tex pub msg bad_sig
False

Sign a 32-byte message hash with the provided secret key, using the provided 32 bytes of fresh auxiliary entropy.

BIP340 recommends that 32 bytes of fresh auxiliary entropy be generated and added at signing time as additional protection against side-channel attacks (namely, to thwart so-called "fault injection" attacks). This entropy is supplemental to security, and the cryptographic security of the signature scheme itself does not rely on it, so it is not strictly required; 32 zero bytes can be used in its stead.

The resulting 64-byte Schnorr signature is portable, and so is not wrapped in a newtype.

>>> import qualified System.Entropy as E  -- example entropy source
>>> enn <- E.getEntropy 32
>>> aux <- E.getEntropy 32
>>> wrcontext enn $ \tex -> sign_schnorr tex msg sec aux

Verify a 64-byte Schnorr signature for the provided 32-byte message hash with the supplied public key.

>>> wrcontext entropy $ \tex -> verify_schnorr tex pub msg sig

Compute an ECDH secret key from the provided public key and (32-byte) secret key.

>>> wrcontext entropy $ \tex -> ecdh tex pub sec

Parse a DER-encoded bytestring into a signature.

>>> wcontext $ \tex -> parse_der tex bytestring
"<bitcoin-core/secp256k1 signature>"
>>> wcontext $ \tex -> parse_der tex bad_bytestring
*** Exception: Secp256k1Error

Serialize a signature into a DER-encoded bytestring.

>>> wcontext $ \tex -> serialize_der tex sig

Parse a bytestring encoding a compact (64-byte) signature.

>>> wcontext $ \tex -> parse_compact tex bytestring

Serialize a signature into a compact (64-byte) bytestring.

>>> wcontext $ \tex -> serialize_compact tex sig

A bitcoin-core/secp256k1-internal public key.

Create a value of this type by parsing a compressed or uncompressed public key via parse_pub, deriving one from a secret key via create_pub, or extracting one from a keypair via keypair_pub.

Derive a public key from a 32-byte secret key.

>>> wrcontext entropy $ \tex -> derive_pub tex sec
"<bitcoin-core/secp256k1 public key>"

Parse a compressed (33-byte) or uncompressed (65-byte) public key.

>>> wcontext $ \tex -> parse_pub tex bs
"<bitcoin-core/secp256k1 public key>"

Additively tweak a public key with the supplied 32-byte tweak.

>>> wrcontext $ \tex -> tweak_pub_add pub tweak

Multiplicatively tweak a public key with the supplied 32-byte tweak.

>>> wrcontext $ \tex -> tweak_pub_mul pub tweak

Additively tweak a secret key with the supplied 32-byte tweak.

>>> wrcontext $ \tex -> tweak_sec_add sec tweak

Multiplicatively tweak a secret key with the supplied 32-byte tweak.

>>> wrcontext $ \tex -> tweak_sec_mul sec tweak

Serialize a public key into a compressed (33-byte) bytestring representation.

>>> wcontext $ \tex -> serialize_pub tex pub

Serialize a public key into an uncompressed (65-byte) bytestring represention.

>>> wcontext $ \tex -> serialize_pub_u tex pub

A bitcoin-core/secp256k1-internal x-only public key.

An "x-only" public key corresponds to a public key with even y-coordinate.

Create a value of this type from a Pub via xonly, or parse one directly via parse_xonly.

Convert a public key into an x-only public key (i.e. one with even y coordinate).

>>> wcontext $ \tex -> xonly tex pub
"<bitcoin-core/secp256k1 x-only public key>"

Parse a compressed (33-byte) or uncompressed (65-byte) public key into an x-only public key.

>>> wcontext $ \tex -> parse_xonly tex bytestring
"<bitcoin-core/secp256k1 x-only public key>"

Serialize an x-only public key into a 32-byte bytestring representation.

>>> wcontext $ \tex -> serialize_xonly tex xonly

A bitcoin-core/secp256k1-internal keypair.

Create a value of this type by passing a secret key to keypair.

Derive a keypair from the provided 32-byte secret key.

>>> wrcontext entropy $ \tex -> keypair tex sec
"<bitcoin-core/secp256k1 keypair>"

Extract a public key from a keypair.

>>> wrcontext entropy $ \tex -> keypair_pub tex keypair
"<bitcoin-core/secp256k1 public key>"

Extract a secret key from a keypair.

>>> wrcontext entropy $ \tex -> keypair_sec tex keypair

A catch-all exception type.