API Documentation - p8k.mleku.dev

Complete API reference for the libsecp256k1 Go bindings.

Table of Contents

1. Context Management
2. Public Key Operations
3. ECDSA Signatures
4. Schnorr Signatures
5. ECDH
6. Recovery
7. Utility Functions
8. Constants
9. Types

Context Management

NewContext

Creates a new secp256k1 context.

func NewContext(flags uint32) (c *Context, err error)

Parameters:

• flags: Context flags (ContextSign, ContextVerify, or combined with |)

Returns:

• c: Context pointer
• err: Error if context creation failed

Example:

ctx, err := secp.NewContext(secp.ContextSign | secp.ContextVerify)
if err != nil {
    log.Fatal(err)
}
defer ctx.Destroy()

Context.Destroy

Destroys the context and frees resources.

func (c *Context) Destroy()

Note: Contexts are automatically destroyed via finalizer, but explicit cleanup is recommended.

Context.Randomize

Randomizes the context with entropy for additional security.

func (c *Context) Randomize(seed32 []byte) (err error)

Parameters:

• seed32: 32 bytes of random data

Returns:

• err: Error if randomization failed

---

Public Key Operations

Context.CreatePublicKey

Creates a public key from a private key.

func (c *Context) CreatePublicKey(seckey []byte) (pubkey []byte, err error)

Parameters:

• seckey: 32-byte private key

Returns:

• pubkey: 64-byte internal public key representation
• err: Error if key creation failed

Context.SerializePublicKey

Serializes a public key to compressed or uncompressed format.

func (c *Context) SerializePublicKey(pubkey []byte, compressed bool) (output []byte, err error)

Parameters:

• pubkey: 64-byte internal public key
• compressed: true for compressed (33 bytes), false for uncompressed (65 bytes)

Returns:

• output: Serialized public key
• err: Error if serialization failed

Context.ParsePublicKey

Parses a serialized public key.

func (c *Context) ParsePublicKey(input []byte) (pubkey []byte, err error)

Parameters:

• input: Serialized public key (33 or 65 bytes)

Returns:

• pubkey: 64-byte internal public key representation
• err: Error if parsing failed

---

ECDSA Signatures

Context.Sign

Creates an ECDSA signature.

func (c *Context) Sign(msg32 []byte, seckey []byte) (sig []byte, err error)

Parameters:

• msg32: 32-byte message hash
• seckey: 32-byte private key

Returns:

• sig: 64-byte internal signature representation
• err: Error if signing failed

Context.Verify

Verifies an ECDSA signature.

func (c *Context) Verify(msg32 []byte, sig []byte, pubkey []byte) (valid bool, err error)

Parameters:

• msg32: 32-byte message hash
• sig: 64-byte internal signature
• pubkey: 64-byte internal public key

Returns:

• valid: true if signature is valid
• err: Error if verification failed

Context.SerializeSignatureDER

Serializes a signature to DER format.

func (c *Context) SerializeSignatureDER(sig []byte) (output []byte, err error)

Parameters:

• sig: 64-byte internal signature

Returns:

• output: DER-encoded signature (variable length, max 72 bytes)
• err: Error if serialization failed

Context.ParseSignatureDER

Parses a DER-encoded signature.

func (c *Context) ParseSignatureDER(input []byte) (sig []byte, err error)

Parameters:

• input: DER-encoded signature

Returns:

• sig: 64-byte internal signature representation
• err: Error if parsing failed

Context.SerializeSignatureCompact

Serializes a signature to compact format (64 bytes).

func (c *Context) SerializeSignatureCompact(sig []byte) (output []byte, err error)

Parameters:

• sig: 64-byte internal signature

Returns:

• output: 64-byte compact signature
• err: Error if serialization failed

Context.ParseSignatureCompact

Parses a compact (64-byte) signature.

func (c *Context) ParseSignatureCompact(input64 []byte) (sig []byte, err error)

Parameters:

• input64: 64-byte compact signature

Returns:

• sig: 64-byte internal signature representation
• err: Error if parsing failed

Context.NormalizeSignature

Normalizes a signature to lower-S form.

func (c *Context) NormalizeSignature(sig []byte) (normalized []byte, wasNormalized bool, err error)

Parameters:

• sig: 64-byte internal signature

Returns:

• normalized: Normalized signature
• wasNormalized: true if signature was modified
• err: Error if normalization failed

---

Schnorr Signatures

Context.CreateKeypair

Creates a keypair for Schnorr signatures.

func (c *Context) CreateKeypair(seckey []byte) (keypair Keypair, err error)

Parameters:

• seckey: 32-byte private key

Returns:

• keypair: 96-byte keypair structure
• err: Error if creation failed

Context.KeypairXOnlyPub

Extracts the x-only public key from a keypair.

func (c *Context) KeypairXOnlyPub(keypair Keypair) (xonly XOnlyPublicKey, pkParity int32, err error)

Parameters:

• keypair: 96-byte keypair

Returns:

• xonly: 32-byte x-only public key
• pkParity: Public key parity (0 or 1)
• err: Error if extraction failed

Context.SchnorrSign

Creates a Schnorr signature (BIP-340).

func (c *Context) SchnorrSign(msg32 []byte, keypair Keypair, auxRand32 []byte) (sig []byte, err error)

Parameters:

• msg32: 32-byte message hash
• keypair: 96-byte keypair
• auxRand32: 32 bytes of auxiliary random data (can be nil)

Returns:

• sig: 64-byte Schnorr signature
• err: Error if signing failed

Context.SchnorrVerify

Verifies a Schnorr signature (BIP-340).

func (c *Context) SchnorrVerify(sig64 []byte, msg []byte, xonlyPubkey []byte) (valid bool, err error)

Parameters:

• sig64: 64-byte Schnorr signature
• msg: Message (any length)
• xonlyPubkey: 32-byte x-only public key

Returns:

• valid: true if signature is valid
• err: Error if verification failed

Context.ParseXOnlyPublicKey

Parses a 32-byte x-only public key.

func (c *Context) ParseXOnlyPublicKey(input32 []byte) (xonly []byte, err error)

Parameters:

• input32: 32-byte x-only public key

Returns:

• xonly: 64-byte internal representation
• err: Error if parsing failed

Context.SerializeXOnlyPublicKey

Serializes an x-only public key to 32 bytes.

func (c *Context) SerializeXOnlyPublicKey(xonly []byte) (output32 []byte, err error)

Parameters:

• xonly: 64-byte internal x-only public key

Returns:

• output32: 32-byte serialized x-only public key
• err: Error if serialization failed

Context.XOnlyPublicKeyFromPublicKey

Converts a regular public key to an x-only public key.

func (c *Context) XOnlyPublicKeyFromPublicKey(pubkey []byte) (xonly []byte, pkParity int32, err error)

Parameters:

• pubkey: 64-byte internal public key

Returns:

• xonly: 64-byte internal x-only public key
• pkParity: Public key parity
• err: Error if conversion failed

---

ECDH

Context.ECDH

Computes an EC Diffie-Hellman shared secret.

func (c *Context) ECDH(pubkey []byte, seckey []byte) (output []byte, err error)

Parameters:

• pubkey: 64-byte internal public key
• seckey: 32-byte private key

Returns:

• output: 32-byte shared secret
• err: Error if computation failed

---

Recovery

Context.SignRecoverable

Creates a recoverable ECDSA signature.

func (c *Context) SignRecoverable(msg32 []byte, seckey []byte) (sig []byte, err error)

Parameters:

• msg32: 32-byte message hash
• seckey: 32-byte private key

Returns:

• sig: 65-byte recoverable signature
• err: Error if signing failed

Context.SerializeRecoverableSignatureCompact

Serializes a recoverable signature.

func (c *Context) SerializeRecoverableSignatureCompact(sig []byte) (output64 []byte, recid int32, err error)

Parameters:

• sig: 65-byte recoverable signature

Returns:

• output64: 64-byte compact signature
• recid: Recovery ID (0-3)
• err: Error if serialization failed

Context.ParseRecoverableSignatureCompact

Parses a compact recoverable signature.

func (c *Context) ParseRecoverableSignatureCompact(input64 []byte, recid int32) (sig []byte, err error)

Parameters:

• input64: 64-byte compact signature
• recid: Recovery ID (0-3)

Returns:

• sig: 65-byte recoverable signature
• err: Error if parsing failed

Context.Recover

Recovers a public key from a recoverable signature.

func (c *Context) Recover(sig []byte, msg32 []byte) (pubkey []byte, err error)

Parameters:

• sig: 65-byte recoverable signature
• msg32: 32-byte message hash

Returns:

• pubkey: 64-byte internal public key
• err: Error if recovery failed

---

Utility Functions

Convenience functions that manage contexts automatically.

GeneratePrivateKey

func GeneratePrivateKey() (privKey []byte, err error)

Generates a random 32-byte private key.

PublicKeyFromPrivate

func PublicKeyFromPrivate(privKey []byte, compressed bool) (pubKey []byte, err error)

Generates a serialized public key from a private key.

SignMessage

func SignMessage(msgHash []byte, privKey []byte) (sig []byte, err error)

Signs a message and returns compact signature (64 bytes).

VerifyMessage

func VerifyMessage(msgHash []byte, compactSig []byte, serializedPubKey []byte) (valid bool, err error)

Verifies a compact signature.

SignMessageDER

func SignMessageDER(msgHash []byte, privKey []byte) (derSig []byte, err error)

Signs a message and returns DER-encoded signature.

VerifyMessageDER

func VerifyMessageDER(msgHash []byte, derSig []byte, serializedPubKey []byte) (valid bool, err error)

Verifies a DER-encoded signature.

SchnorrSign

func SchnorrSign(msgHash []byte, privKey []byte, auxRand []byte) (sig []byte, err error)

Creates a Schnorr signature (64 bytes).

SchnorrVerifyWithPubKey

func SchnorrVerifyWithPubKey(msgHash []byte, sig []byte, xonlyPubKey []byte) (valid bool, err error)

Verifies a Schnorr signature.

XOnlyPubKeyFromPrivate

func XOnlyPubKeyFromPrivate(privKey []byte) (xonly []byte, pkParity int32, err error)

Generates x-only public key from private key.

ComputeECDH

func ComputeECDH(serializedPubKey []byte, privKey []byte) (secret []byte, err error)

Computes ECDH shared secret.

SignRecoverableCompact

func SignRecoverableCompact(msgHash []byte, privKey []byte) (sig []byte, recID int32, err error)

Signs with recovery information.

RecoverPubKey

func RecoverPubKey(msgHash []byte, compactSig []byte, recID int32, compressed bool) (pubKey []byte, err error)

Recovers public key from signature.

ValidatePrivateKey

func ValidatePrivateKey(privKey []byte) (valid bool, err error)

Checks if a private key is valid.

IsPublicKeyValid

func IsPublicKeyValid(serializedPubKey []byte) (valid bool, err error)

Checks if a serialized public key is valid.

---

Constants

Context Flags

const (
    ContextNone       = 1
    ContextVerify     = 257
    ContextSign       = 513
    ContextDeclassify = 1025
)

EC Flags

const (
    ECCompressed   = 258
    ECUncompressed = 2
)

Size Constants

const (
    PublicKeySize              = 64
    CompressedPublicKeySize    = 33
    UncompressedPublicKeySize  = 65
    SignatureSize              = 64
    CompactSignatureSize       = 64
    PrivateKeySize             = 32
    SharedSecretSize           = 32
    SchnorrSignatureSize       = 64
    RecoverableSignatureSize   = 65
)

---

Types

Context

type Context struct {
    ctx uintptr
}

Opaque context handle.

Keypair

type Keypair [96]byte

Schnorr keypair structure.

XOnlyPublicKey

type XOnlyPublicKey [64]byte

64-byte x-only public key (internal representation).

---

Error Handling

All functions return errors. Common error conditions:

• Library not loaded or not found
• Invalid parameter sizes
• Invalid keys or signatures
• Module not available (Schnorr, ECDH, Recovery)

Always check returned errors:

result, err := secp.SomeFunction(...)
if err != nil {
    // Handle error
    return err
}

---

Thread Safety

Context objects are NOT thread-safe. Each goroutine should create its own context.

Utility functions are safe to use concurrently as they create temporary contexts.

Memory Management

Contexts are automatically cleaned up via finalizers, but explicit cleanup with Destroy() is recommended:

ctx, _ := secp.NewContext(secp.ContextSign)
defer ctx.Destroy()

All byte slices returned by the library are copies and safe to use/modify.