libsecp256k1:   secp256k1 Keys and ECDSA Signatures
1 Guide
1.1 Keys
1.2 Signing and Verifying
1.3 Public Key Recovery
1.4 Encodings
1.5 Tweaks
2 Reference
2.1 Secret Keys
secret-key?
generate-secret-key
integer->secret-key
bytes->secret-key
secret-key->integer
secret-key->bytes
secret-key->public-key
secret-key-negate
secret-bytes/  c
secret-key/  c
2.2 Public Keys
public-key?
bytes->public-key
public-key->bytes
public-key-negate
public-key-combine
public-key-bytes/  c
2.3 ECDSA Signatures
secp256k1-order
digest/  c
scalar/  c
recovery-id/  c
ecdsa-signature
ecdsa-signature?
ecdsa-signature-r
ecdsa-signature-s
ecdsa-sign
ecdsa-verify
ecdsa-signature-low-s?
ecdsa-signature-normalize
2.3.1 Encodings
ecdsa-signature->compact
compact->ecdsa-signature
compact->ecdsa-recoverable-signature
ecdsa-signature->der
der->ecdsa-signature
compact-bytes/  c
der-bytes/  c
2.3.2 Public Key Recovery
ecdsa-recoverable-signature
ecdsa-recoverable-signature?
ecdsa-recoverable-signature-id
ecdsa-sign-recoverable
ecdsa-recover
2.4 Tweaks
secret-key-tweak-add
public-key-tweak-add
2.5 Errors
exn:  fail:  libsecp256k1
exn:  fail:  libsecp256k1:  load
exn:  fail:  libsecp256k1:  key
exn:  fail:  libsecp256k1:  signature
exn:  fail:  libsecp256k1:  illegal-argument
exn:  fail:  libsecp256k1:  internal
2.6 The C Library
libsecp256k1-origin
9.3

libsecp256k1: secp256k1 Keys and ECDSA Signatures🔗ℹ

bkc

FFI bindings to Bitcoin Core’s libsecp256k1 C library: secret and public keys on the secp256k1 curve, deterministic ECDSA signatures, public key recovery and key tweaks. This is not the pure-Racket secp256k1 package.

This manual has two parts: the Guide works through the library by task, and the Reference documents every binding.

Security. A secret key prints as #<secret-key>. No error from this library shows an argument: a contract violation, a wrong argument count or an unknown keyword names what was expected and the kind and length of what was given, never the value. The named contracts keep that guarantee only inside this library; secret-bytes/c in a caller’s own -> contract prints the value like any other contract. Racket’s memory manager may copy key bytes, so this library cannot erase them from memory.

Installation. The package ships a prebuilt libsecp256k1 0.8.0 for x86_64 Linux (glibc 2.17 or later) and Apple-silicon macOS only, and installing copies it into place; nothing is compiled. On every other platform, including ARM Linux, Intel macOS and Windows, install the operating system’s libsecp256k1 0.2 or later, built with the recovery module, or name a library file with LIBSECP256K1_LIBRARY; see libsecp256k1-origin.

License. This package is distributed under Apache-2.0 OR MIT; the bundled libsecp256k1 library is distributed under MIT, with its notice in "native-libs/LICENSE.libsecp256k1".

Acknowledgements. The libsecp256k1 contributors.

AI Disclosure. This package and its documentation were created with the use of AI tools.

    1 Guide

      1.1 Keys

      1.2 Signing and Verifying

      1.3 Public Key Recovery

      1.4 Encodings

      1.5 Tweaks

    2 Reference

      2.1 Secret Keys

      2.2 Public Keys

      2.3 ECDSA Signatures

        2.3.1 Encodings

        2.3.2 Public Key Recovery

      2.4 Tweaks

      2.5 Errors

      2.6 The C Library

1 Guide🔗ℹ

This guide works through the library by task, one section per task. Each section ends with an example program in the package’s "examples" directory that does the same task end to end; run one with

  racket -l libsecp256k1/examples/01-sign-verify

For the full definition of every binding, see the Reference.

    1.1 Keys

    1.2 Signing and Verifying

    1.3 Public Key Recovery

    1.4 Encodings

    1.5 Tweaks

1.1 Keys🔗ℹ

A secret key is an integer in [1, n), where n is secp256k1-order, stored as 32 big-endian bytes. generate-secret-key draws one from the operating system’s random source; bytes->secret-key and integer->secret-key rebuild a stored one. A secret key prints as #<secret-key>, and secret keys are equal? only when they are the same object, so compare their public keys.

The public key, secret-key->public-key, is safe to share. Its compressed form is 33 bytes and its uncompressed form 65; bytes->public-key reads either. An integer, or bytes of the right length, that is not a valid key raises exn:fail:libsecp256k1:key; bytes of another length are a contract violation. No error from this library shows the value it was given.

Examples:
> (define key (generate-secret-key))
> key

#<secret-key>

> (define public (secret-key->public-key key))
> (define stored (secret-key->bytes key))
> (equal? (bytes->secret-key stored) key)

#f

> (equal? (secret-key->public-key (bytes->secret-key stored)) public)

#t

> (bytes-length (public-key->bytes public))

33

> (bytes-length (public-key->bytes public #:compressed? #f))

65

> (equal? (bytes->public-key (public-key->bytes public #:compressed? #f)) public)

#t

> (bytes->secret-key (make-bytes 32 0))

bytes->secret-key: invalid secret key;

 the value is zero or not less than the curve order

See "examples/00-keys.rkt".

1.2 Signing and Verifying🔗ℹ

ECDSA signs a 32-byte digest, not a message: hash the message first, here with sha256-bytes. ecdsa-sign takes its nonce from RFC 6979, so the same key and digest always give the same signature, and it returns only low-S signatures. ecdsa-verify rejects high-S signatures; pass a signature from elsewhere through ecdsa-signature-normalize first.

Examples:
> (define digest (sha256-bytes #"hello"))
> (define sig (ecdsa-sign digest key))
> (ecdsa-verify sig digest public)

#t

> (ecdsa-verify sig (sha256-bytes #"hello!") public)

#f

> (equal? (ecdsa-sign digest key) sig)

#t

> (ecdsa-signature-low-s? sig)

#t

See "examples/01-sign-verify.rkt".

1.3 Public Key Recovery🔗ℹ

A recoverable signature carries, beside r and s, a recovery id from 0 to 3 that picks the signer’s public key among those the signature and digest allow. ecdsa-recover computes that key, so a signed message need not carry its signer; this is how Ethereum identifies the sender of a transaction. Another digest usually recovers another key rather than failing, so compare the result with the signer you expect. A recoverable signature is also a plain one for ecdsa-verify.

Examples:
> (define rsig (ecdsa-sign-recoverable digest key))
> (equal? (ecdsa-recover rsig digest) public)

#t

> (public-key? (ecdsa-recover rsig (sha256-bytes #"hello!")))

#t

> (equal? (ecdsa-recover rsig (sha256-bytes #"hello!")) public)

#f

> (ecdsa-verify rsig digest public)

#t

"examples/02-recover.rkt" packs a signature as Ethereum’s 65 bytes r ‖ s ‖ v, with v = 27 + id for an id of 0 or 1, and recovers the signer from them. Ethereum signs a Keccak-256 digest; this library takes digests and does not hash.

1.4 Encodings🔗ℹ

The compact form is 64 bytes, r ‖ s as 32-byte big-endian integers; it leaves out a recoverable signature’s id, which is stored beside it. DER is the variable-length form Bitcoin uses, at most 72 bytes, and der->ecdsa-signature accepts strict DER only. Compact bytes of the right length that are not a signature, and bytes that are not strict DER, raise exn:fail:libsecp256k1:signature; compact bytes of another length are a contract violation.

Examples:
> (define compact (ecdsa-signature->compact sig))
> (bytes-length compact)

64

> (equal? (compact->ecdsa-signature compact) sig)

#t

> (equal? (compact->ecdsa-recoverable-signature (ecdsa-signature->compact rsig)
                                                (ecdsa-recoverable-signature-id rsig))
          rsig)

#t

> (define der (ecdsa-signature->der sig))
> (equal? (der->ecdsa-signature der) sig)

#t

> (der->ecdsa-signature (bytes-append der #"\0"))

der->ecdsa-signature: invalid signature;

 not strict DER, or r or s is negative or not less than the curve order

See "examples/03-encodings.rkt".

1.5 Tweaks🔗ℹ

Adding a 32-byte tweak t to a secret key k gives k + t; adding it to the public key P gives P + tG, the public key of k + t. So whoever holds only a public key can compute the public keys of children whose secret keys only its owner can compute. A tweak not less than n, or a result that is zero or the point at infinity, raises exn:fail:libsecp256k1:key.

Examples:
> (define tweak (sha256-bytes (bytes-append (public-key->bytes public) #"\0\0\0\0")))
> (define child (secret-key-tweak-add key tweak))
> (equal? (secret-key->public-key child) (public-key-tweak-add public tweak))

#t

> (public-key-combine public (public-key-negate public))

public-key-combine: the sum is the point at infinity

"examples/04-tweaks.rkt" derives numbered children from a parent key and from its public key, and checks that they agree.

2 Reference🔗ℹ

2.1 Secret Keys🔗ℹ

procedure

(secret-key? v) → boolean?

  v : any/c
Recognizes secret keys. Secret keys are equal? only when they are eq?; compare their bytes or integers instead.

A fresh key from the operating system’s random source.

procedure

(integer->secret-key k) → secret-key?

  k : exact-integer?

procedure

(bytes->secret-key bs) → secret-key?

  bs : secret-bytes/c
The key k, or the key whose big-endian value is bs. Raise exn:fail:libsecp256k1:key when the value is not in [1, n).

Examples:
> (define one (integer->secret-key 1))
> one

#<secret-key>

> (secret-key->integer one)

1

> (equal? one (integer->secret-key 1))

#f

> (integer->secret-key 0)

integer->secret-key: invalid secret key;

 the value is less than 1 or not less than the curve order

procedure

(secret-key->integer key) → exact-positive-integer?

  key : secret-key/c

procedure

(secret-key->bytes key) → secret-bytes/c

  key : secret-key/c
The key’s value, and a fresh, mutable 32-byte big-endian copy of it.

procedure

(secret-key->public-key key) → public-key?

  key : secret-key/c
The public key kG.

procedure

(secret-key-negate key) → secret-key?

  key : secret-key/c
The key n − k.

32 bytes, and secret keys.

2.2 Public Keys🔗ℹ

procedure

(public-key? v) → boolean?

  v : any/c
Public keys are equal? when they are the same point.

procedure

(bytes->public-key bs) → public-key?

  bs : public-key-bytes/c
Parses the compressed form (33 bytes, prefix 02 or 03) or the uncompressed form (65 bytes, prefix 04). Raises exn:fail:libsecp256k1:key for any other prefix or for bytes that are not a point on the curve.

procedure

(public-key->bytes key 
  [#:compressed? compressed?]) 
 → public-key-bytes/c
  key : public-key?
  compressed? : any/c = #t
The compressed or uncompressed form.

Examples:
> (define pk (secret-key->public-key one))
> pk

#<public-key 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798>

> (bytes->hex-string (public-key->bytes pk #:compressed? #f))

"0479be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8"

> (equal? pk (bytes->public-key (public-key->bytes pk #:compressed? #f)))

#t

procedure

(public-key-negate key) → public-key?

  key : public-key?
The point −P.

procedure

(public-key-combine key ...+) → public-key?

  key : public-key?
The sum. Raises exn:fail:libsecp256k1:key when it is the point at infinity.

33 or 65 bytes.

2.3 ECDSA Signatures🔗ℹ

Arguments keep the C library’s order: the thing being signed or checked comes before the key.

The curve order n.

32 bytes; an integer in [0, n); an integer in [0, 3].

procedure

(ecdsa-signature r s) → ecdsa-signature?

  r : scalar/c
  s : scalar/c

procedure

(ecdsa-signature? v) → boolean?

  v : any/c

procedure

(ecdsa-signature-r sig) → scalar/c

  sig : ecdsa-signature?

procedure

(ecdsa-signature-s sig) → scalar/c

  sig : ecdsa-signature?
A signature (r, s). Signatures are equal? when they are the same kind and their fields are equal.

procedure

(ecdsa-sign digest key) → ecdsa-signature?

  digest : digest/c
  key : secret-key/c
Signs a 32-byte digest. The caller hashes the message. The nonce comes from RFC 6979, so the same key and digest always give the same signature, and s is always in the lower half of the order.

Examples:
> (define digest (sha256-bytes #"Satoshi Nakamoto"))
> (define sig (ecdsa-sign digest one))
> sig

#<ecdsa-signature 934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d82442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5>

> (ecdsa-verify sig digest pk)

#t

procedure

(ecdsa-verify sig digest key) → boolean?

  sig : ecdsa-signature?
  digest : digest/c
  key : public-key?
Rejects signatures whose s is in the upper half of the order. Use ecdsa-signature-normalize first to accept them.

procedure

(ecdsa-signature-low-s? sig) → boolean?

  sig : ecdsa-signature?

procedure

(ecdsa-signature-normalize sig) → ecdsa-signature?

  sig : ecdsa-signature?
Whether s is in the lower half of the order, and the signature with n − s in place of a high s. Normalizing keeps the kind; a recoverable signature’s recovery id changes with s, so recovery gives the same key.

Examples:
> (define high (ecdsa-signature (ecdsa-signature-r sig)
                                (- secp256k1-order (ecdsa-signature-s sig))))
> (ecdsa-verify high digest pk)

#f

> (equal? (ecdsa-signature-normalize high) sig)

#t

2.3.1 Encodings🔗ℹ

Compact is r ‖ s as 32-byte big-endian integers; DER is strict. Parsing raises exn:fail:libsecp256k1:signature.

A recoverable signature’s compact form leaves out its recovery id.

procedure

(ecdsa-signature->der sig) → der-bytes/c

  sig : ecdsa-signature?

procedure

(der->ecdsa-signature bs) → ecdsa-signature?

  bs : bytes?

Examples:
> (bytes->hex-string (ecdsa-signature->der sig))

"3045022100934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d802202442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5"

> (equal? (der->ecdsa-signature (ecdsa-signature->der sig)) sig)

#t

64 bytes; at most 72 bytes.

2.3.2 Public Key Recovery🔗ℹ

A signature together with the recovery id that selects its signer among up to four candidates. It is also an ecdsa-signature?.

procedure

(ecdsa-sign-recoverable digest key)

 → ecdsa-recoverable-signature?
  digest : digest/c
  key : secret-key/c
Signs as ecdsa-sign does, with the same r and s.

procedure

(ecdsa-recover sig digest) → (or/c public-key? #f)

  sig : ecdsa-recoverable-signature?
  digest : digest/c
#f when no public key recovers.

Examples:
> (define rsig (ecdsa-sign-recoverable digest one))
> rsig

#<ecdsa-recoverable-signature 934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d82442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5 id=1>

> (equal? (ecdsa-recover rsig digest) pk)

#t

2.4 Tweaks🔗ℹ

procedure

(secret-key-tweak-add key tweak) → secret-key?

  key : secret-key/c
  tweak : secret-bytes/c

procedure

(public-key-tweak-add key tweak) → public-key?

  key : public-key?
  tweak : secret-bytes/c
Add tweak, read as a big-endian integer, to the key: k + t and P + tG respectively. Raise exn:fail:libsecp256k1:key when the tweak is not less than the order or the result is zero or the point at infinity.

A tweak derived only from public data gives the parent’s secret key away to whoever holds a child’s secret key and that data: the parent’s key is the child’s minus the tweak.

Examples:
> (define t (secret-key->bytes one))
> (secret-key->public-key (secret-key-tweak-add one t))

#<public-key 02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5>

> (equal? (public-key-tweak-add pk t) (secret-key->public-key (secret-key-tweak-add one t)))

#t

2.5 Errors🔗ℹ

Contract violations are ordinary exn:fail:contract:blame errors.

The parent of this library’s exceptions.

Raised by every procedure that needs the C library when no usable library was found. The message gives each candidate’s reason and what to do.

Raised for an invalid secret or public key, tweak or sum.

Raised when compact or DER bytes are not a valid signature.

Raised when the C library reports an illegal argument, which this library’s procedures never pass.

Raised when the C library reports an internal error.

2.6 The C Library🔗ℹ

procedure

(libsecp256k1-origin) → (or/c 'bundled 'system 'environment)

Which libsecp256k1 is in use. 'bundled means the library in the package’s "native-libs" directory. Installation puts the prebuilt copy for the platform there, or, when LIBSECP256K1_NATIVE_LIB_PATH is set, the "lib/libsecp256k1" file under it; installing for the running platform refuses that file, with a message, when it does not load or lacks a function this library calls. 'system means the operating system’s libsecp256k1 (0.2 or later, with the recovery module), used where no bundled copy loads; 'environment means the file named by the LIBSECP256K1_LIBRARY environment variable: that file and no other, with a relative path taken from the current directory. If that variable is system, only the system library is used. The system library is found by the operating system’s loader in its own directories (on macOS, also "/opt/homebrew/lib" unless DYLD_FALLBACK_LIBRARY_PATH is set), never in the current directory. Raises exn:fail:libsecp256k1:load when none can be loaded; every other procedure that needs the C library raises it too.

Every procedure may be called from any thread or place. Each call into the C library is atomic: no other Racket thread in the place runs until it returns, so a long batch of calls lets other threads run only between calls.