SECP256K1(3em)

📦 version 0.5.1, in nixos 26.05, nixpkgs unstable

secp256k1 💅

okay so this is the secp256k1 manual page from section 3em, and it's literally the libsecp256k1 bindings for Emilua. Bestie, we are in cryptographic group-chat territory now. ✨

✨ NAME ✨

secp256k1 — libsecp256k1 bindings for Emilua. That's the whole name vibe, no cap.

🌸 SYNOPSIS 🌸

local secp256k1 = require 'secp256k1'

💖 FUNCTIONS 💖

Every function below is exactly as listed. If a length or value is specified, it's mandatory — not a suggestion, bestie. 🫶

new() → context

Constructor. Periodt.

clone(self) → context

Copy a context object. Lowkey straightforward.

randomize(self[, seed32: byte_span]) → integer

If provided, seed32 must have length=32.

ec_pubkey_parse(self, pubkey: byte_span, input: byte_span) → integer

pubkey must have length=64.

input must have length>0.

ec_pubkey_serialize(self, output: byte_span, pubkey: byte_span, format: "compressed"|"uncompressed") → integer, integer

output must have length=65 if format=uncompressed or length=33 if format=compressed.

pubkey must have length=64.

ec_pubkey_cmp(self, pubkey1: byte_span, pubkey2: byte_span) → integer

pubkey1 must have length=64.

pubkey2 must have length=64.

ecdsa_signature_parse_compact(self, sig: byte_span, input64: byte_span) → integer

sig must have length=64.

input64 must have length=64.

ecdsa_signature_parse_der(self, sig: byte_span, input: byte_span) → integer

sig must have length=64.

input must have length>0.

ecdsa_signature_serialize_der(self, output: byte_span, sig: byte_span) → integer, integer

output must have length>0.

sig must have length=64.

ecdsa_signature_serialize_compact(self, output64: byte_span, sig: byte_span) → integer

output64 must have length=64.

sig must have length=64.

ecdsa_verify(self, sig: byte_span, msghash32: byte_span, pubkey: byte_span) → integer

sig must have length=64.

msghash32 must have length=32.

pubkey must have length=64.

ecdsa_signature_normalize(self, sigout: byte_span|nil, sigin: byte_span) → integer

If provided, sigout must have length=64.

sigin must have length=64.

ecdsa_sign(self, sig: byte_span, msghash32: byte_span, seckey: byte_span, nonce: "rfc6979"|nil, ndata: byte_span|nil) → integer

sig must have length=64.

msghash32 must have length=32.

seckey must have length=32.

If provided, ndata must have a length that depends on nonce's value:

  • nonce = nil → ndata length = 32
  • nonce = "rfc6979" → ndata length = 32

ec_seckey_verify(self, seckey: byte_span) → integer

seckey must have length=32.

ec_pubkey_create(self, pubkey: byte_span, seckey: byte_span) → integer

pubkey must have length=64.

seckey must have length=32.

ec_seckey_negate(self, seckey: byte_span) → integer

seckey must have length=32.

ec_pubkey_negate(self, pubkey: byte_span) → integer

pubkey must have length=64.

ec_seckey_tweak_add(self, seckey: byte_span, tweak32: byte_span) → integer

seckey must have length=32.

tweak32 must have length=32.

ec_pubkey_tweak_add(self, pubkey: byte_span, tweak32: byte_span) → integer

pubkey must have length=64.

tweak32 must have length=32.

ec_seckey_tweak_mul(self, seckey: byte_span, tweak32: byte_span) → integer

seckey must have length=32.

tweak32 must have length=32.

ec_pubkey_tweak_mul(self, pubkey: byte_span, tweak32: byte_span) → integer

pubkey must have length=64.

tweak32 must have length=32.

ec_pubkey_combine(self, out: byte_span, ins: byte_span[]) → integer

out must have length=64.

ins must contain at least 1 element. Each element must have length=64.

tagged_sha256(self, hash32: byte_span, tag: byte_span, msg: byte_span) → integer

hash32 must have length=32.

tag must have length>0.

msg must have length>0.

ecdh(self, output: byte_span, pubkey: byte_span, seckey: byte_span, hash: "sha256"|nil) → integer

output must have a length that depends on hash's value:

  • hash = nil → output length = 32
  • hash = "sha256" → output length = 32

pubkey must have length=64.

seckey must have length=32.

ecdsa_recoverable_signature_parse_compact(self, sig: byte_span, input64: byte_span, recid: integer) → integer

sig must have length=65.

input64 must have length=64.

ecdsa_recoverable_signature_convert(self, sig: byte_span, sigin: byte_span) → integer

sig must have length=64.

sigin must have length=65.

ecdsa_recoverable_signature_serialize_compact(self, output64: byte_span, sig: byte_span) → integer, integer

output64 must have length=64.

sig must have length=65.

ecdsa_sign_recoverable(self, sig: byte_span, msghash32: byte_span, seckey: byte_span, nonce: "rfc6979"|nil, ndata: byte_span|nil) → integer

sig must have length=65.

msghash32 must have length=32.

seckey must have length=32.

If provided, ndata must have a length that depends on nonce's value:

  • nonce = nil → ndata length = 32
  • nonce = "rfc6979" → ndata length = 32

ecdsa_recover(self, pubkey: byte_span, sig: byte_span, msghash32: byte_span) → integer

pubkey must have length=64.

sig must have length=65.

msghash32 must have length=32.

xonly_pubkey_parse(self, pubkey: byte_span, input32: byte_span) → integer

pubkey must have length=64.

input32 must have length=32.

xonly_pubkey_serialize(self, output32: byte_span, pubkey: byte_span) → integer

output32 must have length=32.

pubkey must have length=64.

xonly_pubkey_cmp(self, pk1: byte_span, pk2: byte_span) → integer

pk1 must have length=64.

pk2 must have length=64.

xonly_pubkey_from_pubkey(self, xonly_pubkey: byte_span, pubkey: byte_span) → integer, integer

xonly_pubkey must have length=64.

pubkey must have length=64.

xonly_pubkey_tweak_add(self, output_pubkey: byte_span, internal_pubkey: byte_span, tweak32: byte_span) → integer

output_pubkey must have length=64.

internal_pubkey must have length=64.

tweak32 must have length=32.

xonly_pubkey_tweak_add_check(self, tweaked_pubkey32: byte_span, tweaked_pk_parity: integer, internal_pubkey: byte_span, tweak32: byte_span) → integer

tweaked_pubkey32 must have length=32.

internal_pubkey must have length=64.

tweak32 must have length=32.

keypair_create(self, keypair: byte_span, seckey: byte_span) → integer

keypair must have length=96.

seckey must have length=32.

keypair_sec(self, seckey: byte_span, keypair: byte_span) → integer

seckey must have length=32.

keypair must have length=96.

keypair_pub(self, pubkey: byte_span, keypair: byte_span) → integer

pubkey must have length=64.

keypair must have length=96.

keypair_xonly_pub(self, pubkey: byte_span, keypair: byte_span) → integer, integer

pubkey must have length=64.

keypair must have length=96.

keypair_xonly_tweak_add(self, keypair: byte_span, tweak32: byte_span) → integer

keypair must have length=96.

tweak32 must have length=32.

schnorrsig_sign32(self, sig64: byte_span, msg32: byte_span, keypair: byte_span, aux_rand32: byte_span|nil) → integer

sig64 must have length=64.

msg32 must have length=32.

keypair must have length=96.

If provided, aux_rand32 must have length=32.

schnorrsig_sign_custom(self, sig64: byte_span, msg: byte_span|nil, keypair: byte_span, extraparams: { magic: byte_span|nil, nonce: "bip340"|nil, ndata: byte_span|nil }|nil) → integer

sig64 must have length=64.

keypair must have length=96.

extraparams.magic: byte_span = byte_span.append("\xDA\x6F\xB3\x8C")

If provided, magic must have length=4.

extraparams.nonce: "bip340"|nil — nonce generation function.

extraparams.ndata: byte_span|nil — if provided, ndata must have a length that depends on nonce's value:

  • nonce = nil → ndata length = 32
  • nonce = "bip340" → ndata length = 32

schnorrsig_verify(self, sig64: byte_span, msg: byte_span|nil, pubkey: byte_span) → integer

sig64 must have length=64.

pubkey must have length=64.

ellswift_encode(self, ell64: byte_span, pubkey: byte_span, rnd32: byte_span) → integer

ell64 must have length=64.

pubkey must have length=64.

rnd32 must have length=32.

ellswift_decode(self, pubkey: byte_span, ell64: byte_span) → integer

pubkey must have length=64.

ell64 must have length=64.

ellswift_create(self, ell64: byte_span, seckey32: byte_span, auxrnd32: byte_span|nil) → integer

ell64 must have length=64.

seckey32 must have length=32.

If provided, auxrnd32 must have length=32.

ellswift_xdh(self, output: byte_span, ell_a64: byte_span, ell_b64: byte_span,
             seckey32: byte_span, party: boolean, hash: "prefix"|"bip324",
             data: byte_span|nil) → integer

okay bestie so this one is the ElligatorSwift ✨Diffie-Hellman✨ moment — and it hands you back an integer 💖

🌸 the parameter glow-up checklist

  • output — the buffer where the shared secret lands. Its length is not a free-for-all, it depends on what hash you passed 👀 (see the lil table below).
  • ell_a64 — must have length=64. no exceptions, she's measured 💅
  • ell_b64 — must have length=64 too. twin energy 🎀
  • seckey32 — must have length=32. your secret key stays snatched 🗝️
  • party — a boolean, telling the function which side of the handshake you are 💫
  • hash — one of "prefix" or "bip324". pick your fighter ⚔️
  • data — a byte_span or nil, and its length also depends on hash. when the field is unused, data must be nil — like, actually nil, not "nil-ish" 🙈

🦋 output's length, by hash

  • "prefix" → 32
  • "bip324" → 32

(both 32! cute, consistent, no notes 👑)

🍓 data's length, by hash

  • "prefix" → 64
  • "bip324" → unused → so data must be nil
⚠️ fr fr do not get cute with these lengths. If hash is "bip324" and you hand over a non-nil data, that's you ignoring the spec, not the spec ignoring you 😭

and that's the whole page, bestie!! 🫶 this lil beauty ships as part of Emilua 0.12.1, dated the extremely iconic 1980-01-01 — yes that date is real, yes it's a whole vibe ⭐💜 go forth and do your elliptic-curve thing 🌈✨

📦 where this page comes from