Python bindings to libsecp256k1

To install (and/or upgrade):

python -m pip install --upgrade btclib-secp256k1

Quickstart

Sign and verify, ECDSA and BIP340. Every line below is executed by the test suite, on every interpreter and every kind of wheel, so an example that stops working fails a build rather than sitting here:

>>> import hashlib
>>> from btclib_secp256k1 import dsa, keys, ssa, xonly

>>> # BIP340 test vector 1; yours comes from os.urandom or a wallet
>>> prvkey = 0xB7E151628AED2A6ABF7158809CF4F3C762E7160F38B4DA56A784D9045190CFEF
>>> pubkey = keys.pubkey_from_prvkey(prvkey)
>>> msg = hashlib.sha256(b"hello").digest()

ECDSA, over the 32-byte hash, with the deterministic RFC6979 nonce:

>>> signature = dsa.sign(msg, prvkey)
>>> dsa.verify(msg, pubkey, signature)
True

BIP340 Schnorr, over the same hash, against the x-only key:

>>> xonly_pubkey, parity = xonly.from_pubkey(pubkey)
>>> signature = ssa.sign(msg, prvkey)
>>> ssa.verify(msg, xonly_pubkey, signature)
True

Both take the private key as bytes or as an int, and both return bytes. What each argument may be, and what is refused rather than coerced, is What the boundary checks below; every function states its own contract in its docstring.

Versioning

btclib-secp256k1 version numbers track the wrapped libsecp256k1 version: release M.N.P wraps libsecp256k1 vM.N.P, and the vendored library is v0.8.0. When a new release of the bindings is needed while still wrapping the same libsecp256k1 version, a fourth number is appended: 0.8.0.1, 0.8.0.2, etc.

secp256k1-zkp (btclib-org/btclib-secp256k1#603) is vendored beside secp256k1, not in place of it, and carries no release of its own to track: it is pinned at 8f9ab5f2, on fametrano/secp256k1-zkp rather than on BlockstreamResearch/secp256k1-zkp directly (#828) -- the commit that exposes secp256k1_borromean_verify as a public function, internal linkage there keeping it out of BlockstreamResearch/secp256k1-zkp's own built library. Proposed upstream as BlockstreamResearch/secp256k1-zkp#373, not yet merged. The published wheels do not build against this submodule at all; #605 is what reads it. A re-pin is a pull request of its own, reviewing the delta against the commit named here.

The name

This package was btclib_libsecp256k1 up to and including 0.7.1.3, and 0.8.0 is the first release under this name. lib named the C library being wrapped, and a python distribution is not that library: it is bindings to secp256k1 for the library downstream of this package, which is what the name now says.

Nothing on PyPI bridges the two, deliberately: btclib_libsecp256k1 stops at 0.7.1.3 and stays installable, wrapping libsecp256k1 0.7.1, and pip install btclib_libsecp256k1 keeps resolving to it rather than following the rename. Moving means changing the requirement and the import, which spell the new name differently: the requirement takes the distribution's hyphen and the import the package's underscore.

-btclib_libsecp256k1>=0.7.1.3
+btclib-secp256k1>=0.8.0

-from btclib_libsecp256k1 import dsa, keys, ssa, xonly
+from btclib_secp256k1 import dsa, keys, ssa, xonly

The two can be installed side by side while that happens: the import package was renamed with the distribution, so neither shadows the other. Everything inside the API — the module names, every function, and the ffi and lib a caller reaches MuSig2 through — is unchanged.

Design

These bindings are a boundary, not a library: every function is one libsecp256k1 call, with its arguments validated first and its return code checked. A function returning a key or a signature calls it twice: libsecp256k1 hands back an opaque object — a secp256k1_pubkey, a secp256k1_ecdsa_signature — that only a second call serializes into bytes, no libsecp256k1 call producing them directly. keys.pubkey_from_prvkey is secp256k1_ec_pubkey_create followed by secp256k1_ec_pubkey_serialize; every other function returning a key or a signature has the same shape, the second call being the serialization the first cannot do rather than a second decision. ecdh.shared_point is the one whose serialization is not a call: secp256k1_ecdh hands its point to a hash function rather than back, and the octets are assembled from the two coordinates that function copies out.

A function that does make a second decision is named after both of them and is here for one reason: what the composition saves is the crossing between its halves, which is the caller's cost and not its own choice. xonly.from_prvkey is the private key's public key and then the x of it; keys.pubkey_tweak_mul_sum is a pubkey_tweak_mul per term and one pubkey_sum over them, which is the multi-scalar multiplication a verification equation is written as, with no product serialized on its way into the sum. Neither computes anything libsecp256k1 does not: the arithmetic is upstream's calls in the order the equation names them, and Parsing the key once below is where the crossing they save is measured. One entry point is more than a composition, and it is dsa.sign(grind=True): a loop that signs again, with a counter mixed into the nonce, until r is the low one. That is Bitcoin Core's CKey::Sign and not a scheme of this package's — a signer's size policy, which is why it is asked for and never done by default — and Grinding for a low r below is where its cost, and the reason the loop is python rather than C, are measured. The cryptography — the algorithms, the constant-time implementation, the side-channel hardening — is upstream's, and none of it is reimplemented, extended or second-guessed here. Wrappers of the same C library cannot honestly differ in what it computes, nor in how fast; where they can differ is the boundary, and that is where the work went:

• what runs is known: the version number names the libsecp256k1 being wrapped (see Versioning), pinned as a submodule and compiled from source with every optional module requested explicitly, upstream defaults not being part of its API. __version__ describes the C code underneath, not the wrapper around it
• the surface is complete: every optional module is compiled in and reachable, through a validated binding where a function suffices and through the raw lib where only an object would do (see Wrapped modules). What is absent — the ECDH hash callback, linking a system library — is absent by recorded decision, not by omission
• no input can take the process down: the bindings validate before calling, so a malformed key or signature raises ValueError naming the check that failed, before the C call could meet it; and the vendored build replaces the abort()ing libsecp256k1 default callbacks, so even an illegal argument handed to lib directly is survived, context.check() reporting it verbatim. What that validation is, and what it deliberately is not, is What the boundary checks below
• side channels are the context's problem, and it is handled: the one shared context is randomized at import time, before any thread exists; concurrent use is documented and tested, free-threaded interpreter included (see Thread safety)
• the boundary is typed: py.typed ships, mypy runs in strict mode, and the cffi extension itself is described by a hand-written stub, so what downstream type-checks against is the real signatures rather than Any
• validation is independent: the tests are published vectors (BIP340, RFC6979, third-party fixtures) and invariants over derived inputs, never the downstream library these bindings exist to serve; branch coverage is ratcheted at 100%, with only the unreachable excluded from the measure
• provenance is checkable: every wheel and the sdist are built and tested in public CI from the pinned source, and published by the workflow itself through Trusted Publishing with PEP 740 attestations — no long-lived token, and no maintainer laptop in the path. The sdist attached to the GitHub release carries a build provenance attestation besides, which gh attestation verify checks; SECURITY.md has the command

Which library answered is read off the import line. Everything outside btclib_secp256k1.zkp is libsecp256k1; everything under it is secp256k1-zkp, the fork of it carrying the confidential-assets and adaptor-signature work mainline does not. A namespace rather than an argument on each call, because the libraries overlap by name and not by API: musig is in both, and the fork's is mainline's entry points plus the ones its adaptor signatures need, so one musig would name both and an import line could not say which was reached — outside zkp it is mainline's that answers.

The default of the flag that builds the fork flips — the published wheels then carrying secp256k1-zkp — at the first of the events btclib-org/btclib-secp256k1#603 names, and not before: "BlockstreamResearch/secp256k1-zkp cuts a tag, which gives the pin a release to anchor the vendored-source review against", or "btclib acquires a run-time caller of anything under zkp". Versioning above names the commit the fork is pinned at, and Build below the flag.

What the boundary checks

Every wrapper validates its arguments before calling, and what it validates is deliberately narrow: the boundary checks what C cannot see, and decides nothing else.

• sizes are checked here, because nothing else can. libsecp256k1 takes bare pointers whose length is in the parameter name — msg32, input32, seckey — and reads a fixed number of bytes from them. Hand a 32-byte parameter 20 bytes and it reads past the end, and no return code or callback of the library can report it: the length never reached C to be checked. This is memory safety rather than cryptography, and it is the one part that cannot be left to the caller — a binding that reads adjacent heap into a signature when handed a short bytes would be safe only for the single caller who remembers to check first
• and the type is checked with the size, that check being one question. len answers for a bytearray and a memoryview as readily as for bytes, so a size check on its own let both through, and cffi refused them one call later in its own words and about a ctype — naming neither the argument nor what was wrong with it. What crosses is octets: bytes, bytearray or memoryview, plus an int where a scalar is named. Anything else is refused here and called by the name the signature gives it — the TypeError these wrappers raise, every other refusal below being a ValueError. The three are not a leniency of the kind refused above: each states a value and a width, so nothing has to be disbelieved and nothing supplied — the int is the wider door of the two, the 32-octet width being the curve's. What they are not is passed through. The copy is taken at the boundary, so a caller holding a secret in memory they can overwrite — which is the reason to reach for a bytearray at all — cannot change what libsecp256k1 is about to read
• validity is libsecp256k1's to decide, and it does. Whether 32 bytes are a scalar in [1, n-1] is answered by secp256k1_ec_seckey_verify, and keys.prvkey_verify is that call, not a reimplementation of it. A public key becomes one by passing secp256k1_ec_pubkey_parse, a signature by secp256k1_ecdsa_signature_parse_der, a tweak by the return value of the function applying it; the ValueError names what the library refused. No wrapper here knows the curve order
• and a caller validating its own input gets a verdict, not an exception. keys.prvkey_verify, keys.pubkey_verify, xonly.pubkey_verify and dsa.signature_verify are the four: the same proof the parse beside each of them makes, with nothing kept and nothing to catch. A library holding octets at its own boundary has its own word for what is wrong with them, and an exception carrying this package's word for it is a message it would have to translate. The length is part of the verdict — 34 octets are no public key, and answering False is what a caller asking "do I have one" wants — where every entry point that goes on to use the key raises instead
• nothing is normalized into validity. An argument of the wrong size raises, and is never padded: the 32 bytes of nonce entropy are 32 bytes or omitted, a shorter value being a caller mistake rather than a small number. They are aux_rand32 in every module that takes them, BIP340's own name for the pair libsecp256k1 spells ndata here and rnd32 there, and what omitting them means is the one thing that differs: fresh randomness where BIP340 and BIP324 ask for it, and the RFC6979 nonce alone where ECDSA leaves it deterministic. Taking a public key in any of its serializations is not a leniency of that kind and is worth the distinction: BIP340 verification (ssa.verify) and taproot tweaking (xonly.tweak_add, xonly.tweak_add_check) take 32, 33 or 65 octets because 02 || x, 03 || x and 04 || x || y are one key — lift_x is the even-y point whatever form the x arrived in, and a signer whose point has odd y signs with n - d for that reason. The y is not consulted rather than guessed at, and xonly.from_pubkey answers which form was handed in for a caller that wants to know. A leniency is a guess at what the caller meant, and that decision is theirs to make. dsa.verify(..., normalize=True) is that decision made, rather than an exception to it: ECDSA signatures are malleable, which of the two forms one carries was the signer's choice, and a caller checking signatures it did not make says so in the call instead of round-tripping the signature through dsa.normalize and back into DER. Off, which is the default, a signature outside the lower-s form is refused as before
• the one convenience is the int scalar, and it widens nothing. A private key or a tweak may be given as an int, checked against 0 <= num < 2**256 and serialized big endian. This is not the padding refused above: a short bytes states a value and a width, and accepting it means choosing which of the two to disbelieve, while an int states only a value — the 32-byte width is the curve's, not a fact the caller supplied and got wrong. The set of valid scalars is unchanged; only the type spelling them is. What the door is for is the caller who already holds a number: a nonce, a vector, a tweak just computed. The cost is not in that serialization, which is a loop over nine CPython digits and measures as noise. It is that an int holding a secret was produced by python arithmetic, variable in time with the magnitude of its operands and leaving unzeroized copies of every intermediate on the heap — and that happened before this binding saw the value. bytes is not zeroized either, so what passing them buys is narrow but real: no arithmetic on the secret happened here. Scalar arithmetic that must not leak belongs where that can be promised

None of these checks branches on the content of a secret — they look at a type, a length, or a magnitude, all of which the caller knows already — so where the C call underneath carries a constant-time guarantee, these checks leave it intact rather than provide it. Not every wrapped call has one: keys.pubkey_tweak_mul runs the variable-time secp256k1_ecmult, and says so in its own docstring rather than borrowing secp256k1_ecdh's guarantee. What python cannot give back, where the guarantee does hold, is what happens on either side of that call: bytes is not zeroized either, and SECURITY.md records both limits as inherent.

And there is a way past all of it: lib and ffi are exported, and a call made through them has no python in front of it whatsoever. It is the path for a caller who wants the library and nothing added to it -- musig included, nothing stopping a caller from driving a MuSig2 session through lib directly the way musig.py itself does underneath.

Parsing the key once

A public key crosses this boundary as octets, and every wrapper taking one begins by parsing it — for a compressed key that is a field square root, which is a measurable part of the verification that follows it. A caller that has already paid for that parse can hand it on instead of paying again: keys.parse returns the libsecp256k1 object, and every wrapper whose first act is to build one has a half that takes it in place of the octets.

That half is spelled _foo_, and both underscores are load-bearing. The leading one says private, and means it: an object is a promise no argument check can hold a caller to, so what answers for a wrong one is libsecp256k1's own illegal-argument callback, and a caller reaching for these is past the boundary that proves things. The trailing one says which kind of private — _verify_ takes a parsed key where _parse_der is an ordinary helper.

A private half does not read that callback, and what it answers when libsecp256k1 refuses its object is therefore whatever the C call answered: its own exception where a return code allowed one, and otherwise a value that means nothing — False from a verification, an ordering from a comparison, None from a sum, and, in ecdh, 32 bytes that are a shared secret with nobody. Nothing raises in those four. context.check() immediately after the call is what says so, and proving the object once — keys.parse built it, or keys.pubkey_verify answered for the octets it came from — is what makes the question moot. The public half has no such case, having parsed its own octets, and that is the whole of what a caller gives up by reaching past it.

>>> ecdsa_sig = dsa.sign(msg, prvkey)
>>> parsed = keys.parse(pubkey)           # a valid point: proved once
>>> parsed_sig = dsa.parse_der(ecdsa_sig)
>>> dsa._verify_(msg, parsed, parsed_sig)  # used, rather than proved again
True

The public half is the private one with a parse in front of it, and nothing else about the two differs: the remaining arguments are checked exactly as before, a bare pointer's length being what no C return code can report. The callers this is for are the one that validates a key and then verifies with it, the one checking several signatures against a single key, and the one asking is_low_s about a signature it is about to verify. xonly.parse is the same thing for the x coordinate BIP340 verifies against, dsa.parse_der and dsa.parse_compact for the two serializations of a signature, and every one of them has a serialize beside it turning the object back into octets.

The other side of the boundary is spelled the same way. A wrapper that produces an object — recovering a key from a signature, decoding it, deriving it, adding keys together, signing — serializes what libsecp256k1 handed it already made, and its private half answers with the object instead:

>>> from btclib_secp256k1 import recovery
>>> sig, recid = recovery.sign(msg, prvkey)
>>> parsed_recoverable = recovery.parse_compact(sig, recid)
>>> recovered = recovery._recover_(msg, parsed_recoverable)  # the point
>>> dsa._verify_(msg, recovered, parsed_sig)                 # as it stands
True

So _foo_ means one thing in both directions: the half that speaks in libsecp256k1 objects, where the public half speaks in octets. What it buys is what composing two wrappers otherwise pays between them — a serialization of a point that was already in hand, and a parse of what was just serialized, which for the compressed form is that square root again. Sorting keys and then adding them together is the composition that pays it per key; scanning block after block for a silent payment pays it per transaction, which is why silentpayments has a private half beside its entry points, the summary of a transaction's inputs included.

Some compositions are an entry point instead of two halves, where what the caller wanted was the composition. xonly.from_prvkey is the x-only public key of a private key — the two halves above composed, which is what BIP340 and BIP341 ask for and what this package used to make every caller spell in two steps, with a full public key in the middle that nothing wanted. keys.pubkey_tweak_mul_sum is the other: a term per scalar and one sum over them, which is a verification equation, a MuSig2 aggregate key and BIP352's tweak data, and where the crossing is per term — every product serialized as 65 octets only for the sum to parse them again. Handed over whole it is about a seventh of the call from three terms up and stays there, 64 terms 459.3 µs against 536.5; the CHANGELOG entry that added it has the count-by-count table and the conditions. It is the naive form and not a batched algorithm: secp256k1_ecmult_multi_var is internal to libsecp256k1 and not declared in its public header, so what is saved here is the crossing, which is flat in the number of terms.

ssa.Signer.pubkey reads that same key off the keypair the signer already holds, which is a read rather than a multiplication, and so is cheaper than any composition could be.

Outposts past the boundary

The private halves above hand one object from a call to the next. What they do not answer is the caller who crosses the boundary again and again with the same key: a signer signing message after message, a wallet walking a BIP32 path one index at a time. Each crossing pays the conversion at its far end — a keypair is a point multiplication, a compressed key is a field square root — and pays it for a key it had already converted.

ssa.Signer and keys.PubkeyTweakChain are the two outposts on that side of the boundary held for that reason. Each holds the converted object across calls, so the conversion happens once and every crossing afterwards carries only what changes: a message, a tweak. musig's KeyAggCache, Session and SecretNonce hold state too, and for a different reason the rule below makes precise.

The two are not worth the same, and the numbers below say which is which. A keypair is arithmetic — a point multiplication, half of what a signature costs — and no serialization would give it back. A parsed public key is a parse, and the caller can make that parse cheap by carrying the uncompressed form instead: 0.269 microseconds against 2.326. So the signer saves what nothing else can, and the chain saves what a caller free to choose its serialization could have saved itself.

The rule that separates them is the test a proposal for a third one would have to pass, and it is worth stating on its own, because the answer to every proposal of that kind — a held public key for verifying, for ECDH, for combining — is here rather than in the proposal:

what an object saves is the cost of rebuilding, from octets, whatever it holds. It earns its state when that cost is arithmetic, and does not when it is a parse.

musig's three do not answer to this rule, and are not measured against it below: there is no octets form of a keyagg cache, a session or a secret nonce to rebuild from in the first place, musig.py's own module docstring saying why. What decides that exception is #87's own test — "a handle is a lifetime someone has to own and invalidate" — which ssa.Signer and keys.PubkeyTweakChain never had to pass, holding an object this package could equally have handed back as bytes.

The saving is not merely bounded by that cost; it is that cost, and by construction rather than by measurement. ssa.sign builds the keypair, signs with it and wipes it; signer.sign is that middle term with the first already paid — so the difference between them is secp256k1_keypair_create on any machine, and what the numbers below add is that nothing else of consequence sits in it. They are the ones this section already states: 15.82 microseconds against the signer's 8.27, of which the keypair is 7.55, and 15.82 − 8.27 is that 7.55.

The chain reads the same way and answers differently, which is the distinction of the paragraph above arrived at from the other end. What it saves is the parse it holds, so which parse decides the figure — and that is the pair the paragraph above states, the caller's to choose by the serialization they carry. A keypair offers its caller no such choice.

Some things the rule needs said, or it reads as narrower than it is. The first is what recovers a parse, and it is keys.parse itself, not a cheaper serialization. The argument through the uncompressed form does not reach an x-only key, which is a field square root to rebuild and has no second serialization to escape to — and it does not always reach a full one either, which is what the walk below measures: from the 33 octets an xpub carries, reaching the uncompressed form costs a reserialize that the chain does not pay. A caller who wants the parse held holds it — keys.parse hands back the object and the private halves take it, which is what "the private halves above hand one object from a call to the next" already promised. What a class would add there is a name, not a saving. The second is the other side of the ledger: this package is stateless by construction, and musig.KeyAggCache and musig.Session are its exception, each an object with an owner and an invalidation and, Thread safety says, its own answer to sharing one across threads. What the rule above does not weigh is ergonomics — the line a caller does not have to write is real, and belongs with the caller along with the lifetimes.

So the numbers confirm the rule rather than establish it, and it is worth being clear which of them would survive a different machine. Not the microsecond counts, which are one laptop's; the identity is what carries, and it carries because it is structural rather than because a ratio travels better than an absolute. A rule resting instead on which of two measurements is larger would invert on the first machine that measured them differently — and one such pair is a rounding error apart, which the walk below is about.

ssa.Signer holds the keypair:

>>> messages = [hashlib.sha256(bytes([index])).digest() for index in range(3)]
>>> with ssa.Signer(prvkey) as signer:
...     signatures = [signer.sign(each) for each in messages]
>>> [ssa.verify(m, xonly_pubkey, s) for m, s in zip(messages, signatures)]
[True, True, True]

ssa.sign builds that keypair, signs with it and overwrites it before returning, so a caller signing a second message under the same key builds it again — and it is about half of what a BIP340 signature costs here, 15.82 microseconds against the signer's 8.27, of which the keypair is 7.55. signer.pubkey() reads the x-only key off it rather than deriving it a second time.

keys.PubkeyTweakChain holds the parsed point:

>>> tweaks = [hashlib.sha256(bytes([index])).digest() for index in range(5)]
>>> chain = keys.PubkeyTweakChain(pubkey)
>>> path = [chain.tweak_add(tweak) for tweak in tweaks]
>>> path[-1] == chain.pubkey()
True

That is a BIP32 path walked one index at a time, and the shape of it is what costs: each step needs the previous step's serialized key to hash into the next tweak, so pubkey_tweak_add on the compressed form parses at every step the very point the step before had built and serialized — 64.62 microseconds against the chain's 55.14, for the five steps above, which is the 2.326 of a compressed parse saved four times.

What that comparison leaves out is the caller's other move, and it is worth stating because it is nearly free: walking the same path in the uncompressed form and compressing each answer in python is 54.75, which is the chain's 55.14 within the noise. The uncompressed parse is 0.269, so there is almost nothing left for holding the point to save — the chain's saving is real against the compressed walk and a rounding error against that one, where the caller already holds the 65 octets — which two paragraphs below is the assumption that turns out to decide it. What it is unambiguously worth is not having to write bytes([2 + (sec[64] & 1)]) + sec[1:33] where BIP32 wants 33 octets to hash. chain.pubkey() is the key it has arrived at, and chain._pubkey_() the point itself for a caller handing it on.

The two moves do not compose into a third saving, which is worth saying because the shape of them invites it. A chain answers whichever serialization it is asked for, but it re-parses nothing in either: the point is what it holds. So chain.tweak_add(compressed=False) saves no parse that chain.tweak_add() had been paying, and gives back the line above to be written at every step — it measures slightly slower, for the serialization and that line, and it is not the spelling to reach for.

What the three numbers do leave unasked is where the walk starts. An xpub carries the 33 octets, so a caller taking the uncompressed path reaches its starting form through keys.reserialize — a compressed parse, the 2.326 above, and a serialization — before the first step, and that is rather more than the 0.39 separating the two walks. Counted from the key a BIP32 caller actually holds, the chain is ahead of the uncompressed walk rather than a rounding error behind it: the parse it pays at construction is the one that caller could not have avoided, and it pays it once where the compressed walk pays it five times. Which does not make the chain's saving arithmetic — this section's distinction stands — but it is the parse the caller could not make cheap, which is the case the class is for.

What the two do not share is what they hold. A parsed public key is a public value a caller may keep for as long as it likes; a keypair is the private key in libsecp256k1's own layout, so the signer hands the caller a lifetime and not only a saving. That is what the with block is for: on the way out of it the keypair is overwritten, whether the block ended in a signature or in an exception, and a wiped signer refuses to sign rather than signing with the zeros left behind. signer.wipe() is the same instruction spelled by hand, for a caller who is done before the block is. The chain needs none of it, and has none of it. What none of it changes is the python side: the bytes or int the constructor is handed is a python object like any other, and SECURITY.md records why that copy cannot be taken back.

ECDSA has no counterpart, and the reason is in the equation rather than in the C signature. BIP340 challenges with e = H(R ‖ P ‖ m), so the public key is an input to every signature: it has to be derived, which is a point multiplication, and the keypair is where it is kept — with the parity that decides whether the signature is made with d or with n - d. ECDSA signs s = k⁻¹(z + r·d), and P appears nowhere in it. There is no object derived from the key, and so nothing to hold across calls.

What a dsa.Signer could save is the argument check scalar makes of the private key: 0.117 microseconds of the 12.93 a signature costs, where ssa.Signer saves the 7.55 of 15.82. What it would cost is the lifetime the paragraph above describes, a second copy of the secret held for as long as the signer is. That trade is worth making for half a signature and not for a hundredth of one.

The other ground such a signer could be argued on is the memory, and it needs no signer. Where a scalar is accepted — a private key, a tweak — a cffi array of 32 octets is accepted too, and where the call only reads it libsecp256k1 is handed the caller's own memory. So a caller signing again and again under one key can hold it in ffi.new("unsigned char[32]"), wipe that when done, and have no bytes of the key made per signature. It is the only argument of these bindings that is not copied on the way in, and the trade is stated where the copying one is: the copy bytes and bytearray get is also what stops the caller changing the octets libsecp256k1 is reading, and a caller who hands in memory instead of a value has taken that on. SECURITY.md carries it with the wipe that goes with it.

Which item type the array was declared as does not matter — char, unsigned char, uint8_t, signed char — because what crosses is a re-view of those octets rather than a conversion of them. What is refused is a pointer, whose length is not the pointer's own to know, an array of wider items, which is this machine's byte order rather than a scalar, and any length but 32.

Some calls copy it, and are meant to. keys.prvkey_negate, keys.prvkey_tweak_add and keys.prvkey_tweak_mul copy because libsecp256k1 writes the answer through that pointer. zkp.generator.pedersen_blind_generator_blind_sum copies for that reason too: secp256k1-zkp writes the correction through the last element of its blinding_factor array, which the header declares In/Out. The sender side of silentpayments, zkp.generator.pedersen_blind_sum and that same call copy because this package wipes what it copied on the way out. Handing any of them the caller's memory would negate, overwrite or zero the secret they passed, so a copy is owed. _secret.scalar_buffer takes it where mainline's own ffi allocates; the two in zkp.generator take theirs through the subpackage's ffi, which is what every array there is built through. Those of them that answer a new secret take a keyword-only into, which is the other facility's question rather than this one's — it is how that secret comes back into a buffer instead of a bytes. The sender side of silentpayments takes none: what silentpayments.create_outputs answers is the x-only public keys of the outputs, no entry point of that module has an into at all, and the copy it takes is owed for the wiping reason alone.

Where that binds is not the signing, which never asked: the private halves hand libsecp256k1 the pointer, so a key in a buffer reached _signed before this and reaches it now. It binds on the derivation — keys._pubkey_from_prvkey_ asks for a scalar — and the sharpest case is the failing branch of the check above, which derives in order to tell a wrong argument from a fault: with the key in a buffer it used to answer TypeError: the private key must be bytes or an int, telling a caller they had mistyped the argument they had passed correctly. Which is the reason the door is open, rather than the microsecond a signer would have hoisted.

What does cost in dsa.sign is the DER serialization, 0.757 microseconds, and a caller who wanted the other form never has to pay it: compact=True answers the 64 octets of r ‖ s directly, where reaching them through to_compact writes the DER and parses it straight back.

Checking the signature before answering with it

dsa.sign, ssa.sign and recovery.sign check what they just made against the very key that made it, and a signature that fails is raised on rather than returned. It is the one argument here that defaults to on, and verify=False is how a caller declines it.

The three have the same reasoning behind them and did not arrive by the same route. For BIP340 it is a step of the algorithm: Default Signing ends with "If Verify(bytes(P), m, sig) returns failure, abort", and the note beside it says why — "Verifying the signature before leaving the signer prevents random or attacker provoked computation errors. This prevents publishing invalid signatures which may leak information about the secret key. It is recommended, but can be omitted if the computation cost is prohibitive." Schnorr is linear, so what leaks is not vague: two signatures over one nonce and two challenges give up d by subtraction. For ECDSA no standard asks for it and Bitcoin Core does it anyway, at the end of CKey::Sign, under a comment reading "Additional verification step to prevent using a potentially corrupted signature" — and Core offers no way to turn it off, where this does.

What it catches is not a bad argument: those have all raised by the time it runs. It catches the computation itself going wrong, whether by bad memory or by a fault induced on purpose, and the whole of the protection is not publishing the result.

recovery.sign asks a different question, and the section below says why. What it shares with the other two is the reason and the argument.

It costs what a verification costs, and in ECDSA a point multiplication besides — the public key, which BIP340 needs to sign at all and ECDSA needs for neither of the two things sign does. Measured with the variants alternated in one process, an Apple M5, macOS 26.6, arm64, CPython 3.13.14, seven rounds of 20 000 calls with the minimum of each kept, and a last row running one of them a second time so that the noise has a figure of its own:

and recovery.sign in a session of its own, which re-measured dsa.sign beside it so that the two are comparable rather than merely printed together — 12.06 against 31.54 for dsa.sign there, agreeing with the row above, and a noise row of ±0.02:

Microseconds per signature. The finding is the gap between the two increments: 19.5 for ECDSA against 12.7 for BIP340, and the 6.8 between them is the multiplication secp256k1_ec_pubkey_create does and secp256k1_keypair_xonly_pub does not — the keypair holds the point already, which is the same 7.55 the signer hoists. So the step the specification prescribes is also the cheaper of the two, and a Signer pays it at the same price as a bare ssa.sign.

verify=False is not the only thing a caller can do about that gap. dsa.sign takes a pubkey, the key the check verifies under, so that a caller already holding it does not have the multiplication done again. That is most of what ECDSA's check costs above BIP340's, and handing the key in brings the two to the same operation — a bare verification. In a session of its own, an Apple M5, macOS 26.6, arm64, CPython 3.13.14, nine rounds of 3 000 calls with the minimum of each kept, and the unchecked signature run a second time so the noise has a figure of its own — its dsa.sign rows sitting a few tenths under the two sessions above, which is between sessions and not within any of them:

The 7.40 between the second row and the last is the derivation, which is secp256k1_ec_pubkey_create through keys._pubkey_from_prvkey_. Timed alone in a session of the same shape it is 7.31, against a noise of ±0.14. The 7.55 above is a different call — the keypair's own multiplication — and lands within half a microsecond of it because the two do the same work.

Within the rows where the key is handed in, 2.02 is what a compressed key costs to parse over an uncompressed one — the field square root that recovers y, which is why the longer encoding is the cheaper argument here — and 0.26 is the uncompressed parse itself, which only the private half avoids. Those are what the parse adds back above the fully parsed row, not slices of the derivation above.

The key is taken on trust: checking it against the private key would cost the multiplication the argument exists to save. What that would otherwise confuse is a wrong argument with a wrong computation, since a key that is not this private key's fails verification exactly as a fault does, so the failing branch — and only that one — derives the key and asks again: RuntimeError where the signature does not verify under the key the private key actually has, ValueError where it does. A key handed in beside verify=False is refused rather than ignored.

What the trust cannot do is pass a bad signature. The keys a signature verifies under are a property of that signature, so a key fixed before the signature exists is not one of them, and the argument can cost a wrong diagnosis but never a wrong success. It can also catch what the derived check cannot: a private key corrupted before it was signed with agrees with a public key derived from the same corrupted octets, and does not agree with one that came from anywhere else.

ssa.sign takes no such argument, and that is a decision rather than an omission: its check is a bare verification already, the keypair holding the point, so there would be nothing to save and one more way for a check to fail. recovery.sign takes it: its check derived the very same key before comparing what it recovered against it, and that check is the dearest of the three. The saving is not larger for that, being the same call at the same price, and the table below is where both are read. What taking it cost is a third cause a mismatch can have, which is the recovery id.

recovery.sign recovers instead of verifying, and the difference is the recovery id. A verification does not look at it: a recoverable signature carrying the wrong one verifies perfectly and then recovers a key that is not the signer's — and recovering a key is the one thing a caller of that module is going to do with the answer. So the check is the one the id deserves: recover from the signature, and refuse a key that is not the one that signed.

That is Bitcoin Core's own distinction, and it makes it in the same file. CKey::Sign ends in secp256k1_ecdsa_verify; CKey::SignCompact ends in secp256k1_ecdsa_recover followed by secp256k1_ec_pubkey_cmp against the key derived from the private one. Both under the same comment.

It subsumes the verification exactly, rather than probably. Recovery is not selective: for a given id it answers the key under which that r and s verify, so an inconsistent pair does not fail — it comes back as a different key, and fails only where r is not the x of a point at all. That is the stronger argument rather than a weaker one. Because the recovered key is by construction the key that verifies the signature, recovered == signer is a verification, with the id checked besides; nothing is given up by no longer verifying, and it is provable rather than argued. What it costs is 22.4 microseconds against ECDSA's 19.5 — a recovery being about a verification's work, and the comparison and the derivation making up the rest.

What the three check is not quite the same region either, and recovery's is the one worth knowing: what its check reads is the id held inside the secp256k1_ecdsa_recoverable_signature, while the id the caller receives is the one serialize_compact writes afterwards — so the recovery id is outside the checked region exactly as a DER encoding is. Core does the same, CKey::SignCompact recovering from its rsig and not from the octets it filled. ssa verifies the very 64 octets it answers with; dsa verifies the signature object and serializes it afterwards, so the DER or compact encoding is outside what was checked — as it is in Core, whose CKey::Sign verifies the secp256k1_ecdsa_signature and serializes after. All three are defensible, the serializers being memcpy-shaped where the signing is arithmetic, and the difference is worth a sentence rather than a change.

The derivation inside it is what a caller can hand in, exactly as dsa.sign takes it. Measured in one session with dsa.sign beside it so that the two are comparable rather than merely printed together — an Apple M5, macOS 26.6, arm64, CPython 3.14.6, nine rounds of 3 000 calls with the minimum of each kept, and the unchecked signature run a second time so the noise has a figure of its own:

dsa.sign in that same session was 12.14 unchecked, 31.97 with the key derived and 24.55 with an uncompressed one handed in — a check of 19.83 becoming 12.41 — which puts both of its tables here within a few tenths of the ones above, between sessions and not within either. The 7.51 the argument removes is secp256k1_ec_pubkey_create and nothing else: timed alone in the same session it is 7.53. The 2.18 between the two serializations is the field square root that recovers y, and the 0.24 under it is the uncompressed parse only the private half avoids. What stays is what a recovery and a comparison cost over a verification, about 3 microseconds either way it is read — 15.42 against 12.41 with a key handed in, 22.93 against 19.83 with it derived — and that it is the same 3 both times is what says the argument took the derivation away and left the rest alone.

The diagnosis costs one comparison more than dsa's, and pays it only where something is already wrong. A mismatch here has three causes where dsa's has two — the key given, the recovery id, or the computation — and the derivation the matching path skipped is what separates the one that is an argument from the two that are not. Where the recovered key is the signer's after all, the key handed in is the wrong one, which is a ValueError; where it is not, the signature does not recover its own signer, which is what a wrong id and a fault both look like from here. Neither of those is anything a caller of sign passed — the id comes back from secp256k1_ecdsa_sign_recoverable beside the signature, so a wrong one is a fault by the time the check runs — and that is why the two share the RuntimeError.

Every other microsecond figure in this file was measured before this argument existed and is therefore the signature without the check: verify=False is the column they are in.

Grinding for a low r

dsa.sign(grind=True) answers the signature of the same key and message whose r has its high bit clear. DER spends a leading zero octet on an integer whose top bit is set, so that signature encodes one octet shorter — which is what Bitcoin Core's CKey::Sign grinds for, and this is Core's scheme rather than a rephrasing of it: the first attempt is the plain RFC6979 signature, and each retry mixes a uint32 counter, little endian in the first 4 of 32 octets, into the nonce. Written any other way it would answer octets nobody else answers; written this way, tests/vectors_test.py holds it to Core's own vectors and to rust-secp256k1's.

It costs a signature and then some: 24.9 microseconds against the 11.7 of a plain one, measured beside it over 2000 keys, because half the attempts are wasted and the tail is longer than the average — 2.09 attempts on the mean, and the worst of those 2000 keys took 14. That is why it is a parameter and not the default, and why s is not mentioned in the same breath: libsecp256k1 has already returned the lower of the two, so there is nothing there to grind for.

Where the loop is written was measured, not assumed. Four loops answering the same signature, alternated in one process — 2000 keys signed once each, seven rounds, the minimum of each kept — with the compact form of the result, which is what the retry reads, and a last row running the implemented loop a second time so that the noise has a figure of its own:

The finding is the spread: three tenths of a microsecond separate the four, against a noise row of one, and the caller's own loop is not measurably behind the one inside the package. So what crossing this boundary once per signature could save is somewhere inside that spread — and most of what is in it is the per-attempt serialization the predicate costs, not where the buffers live, the two buffer rows being 0.1 apart. A loop compiled in C would have started from the last row, and it would have cost the one thing these bindings do not trade: a dynamic build compiles no C at all, so a C helper would be a feature the static wheels have and the dynamic ones do not. Which leaves grinding here worth having for the scheme and the vectors that judge it, and not for the microseconds.

Holding the buffers at module level is what the last row costs, and it is not available anyway: a package with one shared context and a thread safety story does not get to keep scratch memory where a second thread reaches it.

What the loop tests is is_low_r, which is the compact serialization and not the DER length: the two are not the same question, DER being 6 + lenR + lenS, so a high r of 33 octets with an s that happens to need only 31 encodes to 70 octets too — about one signature in 500 — and a length test would take those for low-r ones. The first octet of the compact form is the top of r, which is exactly what Core's SigHasLowR reads. A caller asks the same question of a signature it did not make with dsa.is_low_r, and it is a question and not a rule: unlike is_low_s, nothing rejects a high-r signature, which is valid and always was. What it says is that this one is an octet shorter than it might have been.

The entropy argument is refused together with it. Grinding writes the very 32 octets aux_rand32 is, so dsa.sign(msg, key, aux, grind=True) raises rather than resolving silently in favour of one of them. recovery.sign has no grind, and the reason is that there is nothing to shorten: a recoverable signature is 65 fixed octets, so grinding one would buy the caller two signatures' worth of nothing.

Wrapped modules

All the optional libsecp256k1 modules are compiled in and their declarations are available through the lib and ffi cffi objects. The table is mainline's:

keys provides the public key of a private key (pubkey_from_prvkey, compressed by default, compressed=False for the uncompressed form) and the scalar and point algebra (tweaking, negation, combination, arbitrary point multiplication, and the multi-scalar multiplication of pubkey_tweak_mul_sum) underlying BIP32 key derivation, plus the lexicographic ordering of public keys (pubkey_cmp, pubkey_sort) that BIP67 and MuSig2 key aggregation call for; xonly provides the BIP341 taproot tweaking of x-only public keys and of their private keys, and the x-only public key itself, from a full public key (from_pubkey) or straight from a private key (from_prvkey); hashes provides the BIP340 tagged hash, the domain separation the taproot tags are built on.

Wherever one of these answers a secret — a tweaked or negated private key, a shared secret or a shared point, a nonce — it also takes a keyword-only into: a writable buffer of exactly the secret's length, in contiguous octets, which receives the secret in place of the bytes the call would otherwise return, so that the copy the caller is left holding is one they can overwrite. It is an addition and not a change; omit it and nothing differs. SECURITY.md is where what it does and does not buy is stated, and names the silentpayments secrets it does not reach.

Two of those have a second spelling for a caller doing arithmetic rather than holding a key. keys.pubkey_sum is pubkey_combine with the point at infinity answered as None instead of refused: P + (-P) is the identity, which a curve library has a value for and which no secp256k1_pubkey can hold, so the sum that is no public key is the one thing the two calls do differently. And xonly.to_pubkey is the lift: an x-only key is an x, the point it names is the one with even y, and reading that y is secp256k1_ec_pubkey_parse of 0x02 || x — octets a caller used to write itself, there being no libsecp256k1 call from an x-only object back to a point.

Converting between two serializations of the same value is keys.reserialize for a key and dsa.to_der and dsa.to_compact for a signature. Two names there and one here, because which serialization a signature arrived in cannot be read off its octets: a DER signature of 64 of them exists, and begins with the 0x30 a compact r may begin with too. So the input form is named by the call, as compact names it on dsa.sign and dsa.verify, where a key's is read from its length.

ssa.sign signs a 32-byte message hash, as bitcoin does; ssa.sign_custom signs a message of any length, which BIP340 allows and which a protocol of its own may define.

dsa.nonce_rfc6979 and ssa.nonce_bip340 answer the nonce each signer derives, which is the one part of signing these bindings used to compute and never show. libsecp256k1 exports both derivations as callable pointers, so this is the C function itself rather than a second implementation of it, called with what the signer passes it -- and what comes back is the k of the signature the same arguments produce, which is how tests/nonces_test.py checks it: r is the x of k times the generator. A python implementation of either derivation has published vectors and, until now, no oracle. The nonce is the secret a signature is built on, so reading one into python takes it out of constant-time code: what these are for is checking a derivation, not driving one.

ecdh.shared_secret returns the SHA256 of the compressed shared point, the libsecp256k1 default. The hash function is not exposed: libsecp256k1 takes it as a C callback, and a protocol needing another derivation has the shared point itself as ecdh.shared_point(pubkey, prvkey). That is the same secp256k1_ecdh and its constant-time secp256k1_ecmult_const, handed a hash function this package compiles into the vendored library, which copies the two coordinates out rather than hashing them, so no python runs in the middle of the call. keys.pubkey_tweak_mul(pubkey, prvkey) answers the same point through secp256k1_ecmult, variable time in the tweak.

silentpayments is BIP352, and the elliptic curve half of it, which is what libsecp256k1 implements: create_outputs is the sender's side and takes the private keys of the inputs the payment is funded from, prevouts_summary and scan_outputs the recipient's, and label and labeled_spend_pubkey the several addresses one scan key can receive at. What is not there is what BIP352 states over scripts -- which inputs of a transaction are eligible, and which of those are taproot -- because that is a script question and there is no script here: the two kinds of key are two arguments, and the caller says which is which. tests/vectors_test.py drives both directions of every BIP352 vector, and reads that eligibility off the keys the vector file itself publishes rather than off its scripts, for the same reason.

Some things about it are worth knowing before it is used. The summary prevouts_summary returns is opaque and not a serialization: what is inside is libsecp256k1's own, portable across neither platforms nor versions, and the only thing to do with it is hand it to scan_outputs in the same process. And the label cache is a mapping the caller owns: libsecp256k1 recognizes a label by calling back to look it up, so a labeled output is found only if its label is in the mapping handed in -- which is also why the keys of that mapping are bytes and only bytes, a bytearray and a memoryview not being hashable.

secp256k1_context_set_sha256_compression, new in libsecp256k1 0.8.0, has no binding, by the decision that keeps the ECDH hash out: it replaces the SHA256 compression function the library uses internally, and its purpose is to route it to a hardware implementation. Reached from python it would do the opposite -- a python call per 64-byte block, in the innermost loop of every hash the library computes -- so what it is for is unreachable through these bindings and what it would be is a way to make them slow. It remains available through lib for a caller who has a C function pointer to give it.

MuSig2 is wrapped, in musig. What its two-round protocol needs is a session whose secret nonce cannot be reused, and that is a property of an object's lifetime rather than of a function: only whoever owns the session can invalidate it. This package is otherwise stateless by construction, every other function being one libsecp256k1 call with its arguments validated, and musig.KeyAggCache and musig.Session are its exception -- the Outposts past the boundary section above says why the existing rule for holding an object does not reach them, and musig.py's own module docstring records the decision to take the exception rather than to leave the state to whoever calls this package, KeyAggCache and Session having no serialization to hand back regardless.

musig.SecretNonce is the object that carries the secret: nonce_gen and nonce_gen_counter return one, partial_sign wipes it whether it signs or is refused, and a session abandoned before that -- the case libsecp256k1 itself cannot see -- is wipe, or the with statement that calls it on the way out. ssa.Signer is the model this follows, and SECURITY.md records both as the buffers in this package whose zeroing is asked for rather than done.

A PSBT's multi-party signing state is not what musig.Session is: that object is scoped to one process and one two-round exchange -- it has no serialization, the module docstring above giving the reason that is taken as an exception here -- so whoever needs PSBT-level coordination holds that state elsewhere, outside this package.

The aggregate signature Session.partial_sig_agg answers is a plain BIP340 signature, over the aggregate key KeyAggCache.pubkey_get or agg_pubkey names: ssa.verify is what checks it, and nothing in musig duplicates that call. keys.pubkey_sort is BIP327's key ordering, applied before KeyAggCache if the signers have not agreed on another one.

A call made through lib directly -- which musig's own functions are, underneath, and which a caller reaching past them is free to make too -- has no argument validation in front of it, so libsecp256k1 is the only thing checking its preconditions: it reports a violated one through a callback of the context and returns 0, leaving nothing in the return value to say what happened. context.check() raises what was reported, the failed precondition verbatim, and is meant to follow such a call:

if not lib.secp256k1_musig_partial_sign(ctx, psig, secnonce, ...):
    context.check()  # ValueError, naming the failed precondition

That example is the one that matters: partial signing zeroes the secret nonce, so signing twice with it is refused, and this is how a caller reaching lib directly learns why -- musig.SecretNonce.partial_sign answers its own ValueError for the same case instead, its callers having no callback to read. The entry points taking octets need none of it, validating their arguments before calling; the private halves taking an object need exactly it, for the reason Parsing the key once gives. Either way the abort()ing libsecp256k1 defaults are replaced by do-nothing stubs in the vendored build, so no illegal argument can take the hosting process down.

btclib_secp256k1.zkp is the same layout over secp256k1-zkp: a lib and an ffi of its own, a zkp.context holding that library's own shared context and raising what it reported, and a wrapper module per secp256k1-zkp module wrapped. Which those are is the API documentation rather than a list here, that set growing a module at a time. silentpayments runs the other way: secp256k1-zkp's own copy of that module is mainline's, blob for blob at the commits Versioning names, so the flagged extension declares none of it and BIP352 is reached through btclib_secp256k1.silentpayments alone.

Thread safety

The bindings can be called concurrently from several threads. They hold a single libsecp256k1 context, created and randomized at import time and passed to every call: secp256k1_context_randomize is what mutates a context, it runs once before any thread exists, and each call allocates the buffers it writes to.

This matters on a free-threaded interpreter, for which a wheel is built (cp314t), where those calls are no longer serialized; tests/concurrency_test.py exercises it.

btclib_secp256k1.zkp.context holds a second, separate context, one library over, and does not build it the same way: the guarantee above rests on the shared context above being built at plain module scope, which Python's own import lock serializes for every thread that reaches it; zkp's is deferred to the first call instead, by decision (#607 onward), so that importing the subpackage never reaches for the flagged extension on its own. context._lock is what makes that deferred build safe under several threads (#717): held for the whole of it, so two threads racing the first call still build one context between them rather than one each, freeing the other's callback closures out from under it.

The outposts above are what hold a buffer across calls, and they answer differently. ssa.Signer does not cost that guarantee: libsecp256k1 takes a keypair const, so several threads may sign through one signer. What is theirs to order is the wipe, which overwrites the very memory a concurrent signature is reading — the same shape of race as re-randomizing the context below, and the reason the with block ends where the threads have joined. musig.Session reads the same way: every call that takes one — SecretNonce.partial_sign, partial_sig_verify, partial_sig_agg — takes it const, secp256k1_musig_session never being written to after Session.__init__ builds it, so several threads may verify or sign through one session at once.

keys.PubkeyTweakChain is the exception, and by construction: secp256k1_ec_pubkey_tweak_add takes its key as in and out, so every tweak_add writes the point the chain holds. One chain belongs to one thread, and a path is a sequence in any case — two threads sharing one are not two walkers of it but two writers of the same point. Each thread that wants one builds its own, which costs the parse the chain exists to pay once. musig.KeyAggCache is the same shape: pubkey_ec_tweak_add and pubkey_xonly_tweak_add write the cache in place, so two threads tweaking one race, where two threads only ever reading it — through nonce_gen, Session.__init__, partial_sign — do not, none of those calls writing to it.

musig.SecretNonce is neither of the two shapes above, being narrower than both: it is meant to be read exactly once, from whichever thread gets there first, and refused everywhere else — a keypair's read-any-number-of-times constness does not apply, and neither does a chain's one-object-one-thread convention, since a shared secret nonce is exactly the case this class has to make safe rather than ask a caller to avoid. Reading self._secnonce and then clearing it are two statements, and without ordering them two threads calling partial_sign on the same object could each pass the read before either reaches the clear, and both go on to drive secp256k1_musig_partial_sign over the same native secnonce at once — an unsynchronized concurrent access on the exact memory a MuSig2 nonce-reuse leak comes from, the worst failure this module has. A lock private to the instance is what orders it: SecretNonce._take makes the read and the clear one atomic step, so at most one caller — from any thread — ever receives the object. tests/concurrency_test.py races WORKERS threads on one SecretNonce and asserts exactly one signs.

The one way to lose that guarantee is to re-randomize the shared context while it is in use. context._randomize(context.ctx) is there for a caller who wants fresh blinding, and libsecp256k1 asks for exclusive access to a context to mutate one: call it before the threads start, or hold a read-write lock over every call that takes ctx.

What context.check() reports is per thread: the callback recording it runs on the thread of the call that triggered it, which is what attributes a message to the right caller.

What is not protected is the secret material itself, which lives in Python objects for as long as the interpreter keeps them: see SECURITY.md.

The vendored library is not optional

Linking against a libsecp256k1 already installed on the system, instead of the vendored one, is what a distribution packager needs: Debian, Fedora, conda-forge, Nix and Alpine have policies against vendored copies of a cryptographic library. This package does not offer that mode, by decision, and the account of it belongs here rather than in a closed issue.

In favour of it:

• it is the only way to reach the users of apt, dnf and conda, who do not install from PyPI at all; the coincurve fork libsecp256k1-py-bindings exists to fill exactly that gap for a conda-forge recipe
• a libsecp256k1 vulnerability would then be fixed once for the whole system, instead of once per wheel of every package vendoring it
• it would cost little to add: the build is a single CMake path, so there is exactly one method to bypass, and pkg-config already knows where an installed library and its headers are

Against it:

• the versioning contract above breaks, and nothing can detect that it has: libsecp256k1 has no runtime version function, and no version macro in its headers either, so __version__ would go on claiming the version it wraps over a library of any vintage. The only machine-readable version is the pkg-config field, read at build time and gone afterwards
• the module set stops being an assertion: headers are installed per module, so what is there can be detected, but a distribution ships an older library, without musig or ellswift, and recovery is off by default upstream. Every binding module would need a capability check, and the table above a column of conditions
• the abort() semantics would differ between the two builds: the shared context sets its own callbacks, so the bindings stay safe either way, but a system library is built with the abort()ing defaults, so a context created through lib could take the process down, which is what tests/core_test.py asserts cannot happen
• the test suite would become conditional on the library it finds, where the ratchet is measured on the two linkages this tree builds from the vendored source and on nothing whose vintage it does not know
• it is a second build path, which unifying on CMake removed, and a support surface: reports about a libsecp256k1 this project did not build, possibly patched downstream, in consensus critical code

It stays out until a packager asks for it. The value is in opening a channel, and the costs above are paid from the first day, whether anyone walks it or not.

Build

The vendored libsecp256k1 is built with CMake on every platform, out of tree: the submodule is only ever read from. CMake is declared as a build requirement, so a PEP 517 frontend provisions it and only a C toolchain has to be there already; a system CMake 3.22 or newer serves just as well, with --no-build-isolation.

The cffi extension itself is compiled with the interpreter's own toolchain, which on Windows is the standard setuptools/MSVC one; a gcc in the PATH is still required there, as it preprocesses the library headers for cffi. Both Windows architectures are built this way: the vendored library is built for the architecture of the interpreter, which is what its toolchain compiles the extension for, and not for the one of the host, which is what CMake would otherwise pick. The two differ whenever the interpreter is emulated, and on Windows arm64 that is the default case rather than an exotic one; the same holds for a universal2 interpreter on macOS, which needs both architectures in the archive it links. The win_arm64 wheels start at CPython 3.11, the first version with a Windows arm64 build. The dynamic (ABI mode) Windows wheel is instead cross-compiled on Linux with mingw-w64, through the vendored CMake toolchain file, and is x86_64 only.

BTCLIB_LIBSECP256K1_ZKP=true builds a second static extension, over the vendored secp256k1-zkp, beside the one every wheel carries: it is what btclib_secp256k1.zkp loads, and no published wheel carries it. scripts/README.md has that variable beside the ones choosing among the paths above, and says what BTCLIB_LIBSECP256K1_ZKP=true alongside one of them does: the build declines, this extension having no dynamic form.

How to get the submodule, set up the development environment, run the suite, reproduce each CI job locally, and what a change is expected to satisfy are in CONTRIBUTING.md; what a pull request is answered against is in REVIEWING.md.

Release process

Releases are published to PyPI by the release GitHub workflow using Trusted Publishing: no long-lived PyPI token exists anywhere; PyPI trusts the workflow itself (via GitHub OIDC) and hands out a short-lived upload token at run time. Wheels and sdist are uploaded with PEP 740 attestations, so their provenance can be verified on PyPI; the sdist attached to the GitHub release is signed a second time, so that copy can be verified without the index.

The steps to cut a release, to rehearse one on TestPyPI, and the one-time setup each index needs are in RELEASING.md.

Comparison

Wrappers of the same C library cannot honestly differ in what it computes, nor in how fast — the point Design makes above about where the actual work goes, coincurve, secp256k1-py and electrum-ecc included, every one of them the same libsecp256k1 underneath. That does not make the difference unmeasurable, only certain about what it is a difference in: not the cryptography, which is upstream's regardless of which wrapper calls it, but the boundary each one places around the same calls — how much a caller pays to cross it. Measuring that honestly, and publishing the run rather than a claim, is what btclib-benchmarks is for, and the libsecp256k1 wrappers table is where this project's own boundary is timed against the others', one run kept whole rather than reduced to a single figure — an order of magnitude to read there, never a number to quote here.

The btclib organization and its projects are actively supported by DGI and CheckSig.