ufsecp.h

Go to the documentation of this file.

/* ============================================================================
 * UltrafastSecp256k1 -- Stable C ABI
 * ============================================================================
 *
 * SINGLE HEADER that exposes the entire public C API.
 * Include only this file from application / binding code.
 *
 * ## Design principles
 *
 *   1. Opaque context (`ufsecp_ctx*`) -- all state lives here.
 *   2. Every function returns `ufsecp_error_t` (0 = OK).
 *   3. No internal types leak -- all I/O is `uint8_t[]` with documented sizes.
 *   4. ABI version checked at link time via `ufsecp_abi_version()`.
 *      Full policy: docs/ABI_VERSIONING.md
 *   5. Thread safety: each ctx is single-thread; create one per thread or
 *      protect externally. Blinding state (ufsecp_context_randomize) is
 *      thread-local and orthogonal to context ownership.
 *      Full policy: docs/THREAD_SAFETY.md
 *   6. Dual-layer constant-time: secret-dependent operations (scalar mul,
 *      nonce gen, key tweak) ALWAYS use the CT layer; public operations
 *      (verification, point serialisation) ALWAYS use the fast layer.
 *      Both layers are architecturally wired -- no flag, no opt-in.
 *      This removes flag-based routing mistakes inside the core ABI.
 *      Bindings and callers must still enforce context ownership, buffer
 *      lifetime, and secret-handling discipline.
 *
 * ## Naming
 *
 *   ufsecp_<noun>_<verb>()   e.g. ufsecp_ecdsa_sign()
 *   UFSECP_<CONSTANT>        e.g. UFSECP_PUBKEY_COMPRESSED_LEN
 *
 * ## Memory
 *
 *   Caller always owns output buffers.
 *   Library never allocates on behalf of caller (except ctx create/clone).
 *
 * ============================================================================ */
 
#ifndef UFSECP_H
#define UFSECP_H
 
#include "ufsecp_version.h"
#include "ufsecp_error.h"
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* -- Size constants --------------------------------------------------------- */
 
#define UFSECP_PRIVKEY_LEN          32
#define UFSECP_PUBKEY_COMPRESSED_LEN 33
#define UFSECP_PUBKEY_UNCOMPRESSED_LEN 65
#define UFSECP_PUBKEY_XONLY_LEN     32
#define UFSECP_SIG_COMPACT_LEN      64  /* R||S for ECDSA, r||s for Schnorr */
#define UFSECP_SIG_DER_MAX_LEN      72
#define UFSECP_HASH_LEN             32
#define UFSECP_HASH160_LEN          20
#define UFSECP_SHARED_SECRET_LEN    32
#define UFSECP_BIP32_SERIALIZED_LEN 78
 
/* -- Network constants ------------------------------------------------------ */
 
#define UFSECP_NET_MAINNET  0
#define UFSECP_NET_TESTNET  1
 
/* ===========================================================================
 * Context
 * ===========================================================================
 *
 * Constant-time safety is architectural, NOT flag-based.
 *
 *   +-------------------------------------------------------------+
 *   |  Layer 1 -- FAST:  public operations (verify, point arith)  |
 *   |  Layer 2 -- CT  :  secret operations (sign, nonce, tweak)   |
 *   |  Both layers are ALWAYS ACTIVE simultaneously.              |
 *   |  No opt-in / opt-out in the core ABI.                       |
 *   +-------------------------------------------------------------+
 *
 * CT layer guarantees:
 *   - Complete addition formula (branchless, 12M+2S)
 *   - Fixed-trace scalar multiplication (no early exit)
 *   - CT table lookup (scans all entries)
 *   - Valgrind/MSAN verifiable (SECP256K1_CLASSIFY / DECLASSIFY)
 *
 * =========================================================================== */
 
typedef struct ufsecp_ctx ufsecp_ctx;
 
UFSECP_API ufsecp_error_t ufsecp_ctx_create(ufsecp_ctx** ctx_out);
 
UFSECP_API ufsecp_error_t ufsecp_ctx_clone(const ufsecp_ctx* src,
                                           ufsecp_ctx** ctx_out);
 
UFSECP_API void ufsecp_ctx_destroy(ufsecp_ctx* ctx);
 
UFSECP_API ufsecp_error_t ufsecp_last_error(const ufsecp_ctx* ctx);
 
UFSECP_API const char* ufsecp_last_error_msg(const ufsecp_ctx* ctx);
 
UFSECP_API size_t ufsecp_ctx_size(void);
 
UFSECP_API ufsecp_error_t ufsecp_context_randomize(ufsecp_ctx*    ctx,
                                                    const uint8_t* seed32);
 
/* ===========================================================================
 * Private key utilities
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_seckey_verify(const ufsecp_ctx* ctx,
                                               const uint8_t privkey[32]);
 
UFSECP_API ufsecp_error_t ufsecp_seckey_negate(ufsecp_ctx* ctx,
                                               uint8_t privkey[32]);
 
UFSECP_API ufsecp_error_t ufsecp_seckey_tweak_add(ufsecp_ctx* ctx,
                                                  uint8_t privkey[32],
                                                  const uint8_t tweak[32]);
 
UFSECP_API ufsecp_error_t ufsecp_seckey_tweak_mul(ufsecp_ctx* ctx,
                                                  uint8_t privkey[32],
                                                  const uint8_t tweak[32]);
 
/* ===========================================================================
 * Public key
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_create(ufsecp_ctx* ctx,
                                               const uint8_t privkey[32],
                                               uint8_t pubkey33_out[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_create_uncompressed(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    uint8_t pubkey65_out[65]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_parse(ufsecp_ctx* ctx,
                                              const uint8_t* input,
                                              size_t input_len,
                                              uint8_t pubkey33_out[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_xonly(ufsecp_ctx* ctx,
                                              const uint8_t privkey[32],
                                              uint8_t xonly32_out[32]);
 
/* ===========================================================================
 * ECDSA (secp256k1, RFC 6979 deterministic nonce)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sign(ufsecp_ctx* ctx,
                                            const uint8_t msg32[32],
                                            const uint8_t privkey[32],
                                            uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sign_verified(ufsecp_ctx* ctx,
                                                     const uint8_t msg32[32],
                                                     const uint8_t privkey[32],
                                                     uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_verify(ufsecp_ctx* ctx,
                                              const uint8_t msg32[32],
                                              const uint8_t sig64[64],
                                              const uint8_t pubkey33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sig_to_der(ufsecp_ctx* ctx,
                                                   const uint8_t sig64[64],
                                                   uint8_t* der_out,
                                                   size_t* der_len);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sig_from_der(ufsecp_ctx* ctx,
                                                    const uint8_t* der,
                                                    size_t der_len,
                                                    uint8_t sig64_out[64]);
 
/* -- ECDSA recovery --------------------------------------------------------- */
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sign_recoverable(
    ufsecp_ctx* ctx,
    const uint8_t msg32[32],
    const uint8_t privkey[32],
    uint8_t sig64_out[64],
    int* recid_out);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_recover(ufsecp_ctx* ctx,
                                               const uint8_t msg32[32],
                                               const uint8_t sig64[64],
                                               int recid,
                                               uint8_t pubkey33_out[33]);
 
/* ===========================================================================
 * Schnorr / BIP-340
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_sign(ufsecp_ctx* ctx,
                                              const uint8_t msg32[32],
                                              const uint8_t privkey[32],
                                              const uint8_t aux_rand[32],
                                              uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_sign_verified(ufsecp_ctx* ctx,
                                                       const uint8_t msg32[32],
                                                       const uint8_t privkey[32],
                                                       const uint8_t aux_rand[32],
                                                       uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_verify(ufsecp_ctx* ctx,
                                                const uint8_t msg32[32],
                                                const uint8_t sig64[64],
                                                const uint8_t pubkey_x[32]);
 
/* ===========================================================================
 * Batch signing (CPU constant-time dispatch -- private keys never leave host)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_sign_batch(
    ufsecp_ctx* ctx,
    size_t count,
    const uint8_t* msgs32,
    const uint8_t* privkeys32,
    uint8_t* sigs64_out);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_sign_batch(
    ufsecp_ctx* ctx,
    size_t count,
    const uint8_t* msgs32,
    const uint8_t* privkeys32,
    const uint8_t* aux_rands32,
    uint8_t* sigs64_out);
 
/* ===========================================================================
 * ECDH (Diffie-Hellman key agreement)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_ecdh(ufsecp_ctx* ctx,
                                      const uint8_t privkey[32],
                                      const uint8_t pubkey33[33],
                                      uint8_t secret32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdh_xonly(ufsecp_ctx* ctx,
                                            const uint8_t privkey[32],
                                            const uint8_t pubkey33[33],
                                            uint8_t secret32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdh_raw(ufsecp_ctx* ctx,
                                          const uint8_t privkey[32],
                                          const uint8_t pubkey33[33],
                                          uint8_t secret32_out[32]);
 
/* ===========================================================================
 * Hashing
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_sha256(const uint8_t* data, size_t len,
                                        uint8_t digest32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_hash160(const uint8_t* data, size_t len,
                                         uint8_t digest20_out[20]);
 
UFSECP_API ufsecp_error_t ufsecp_tagged_hash(const char* tag,
                                             const uint8_t* data, size_t len,
                                             uint8_t digest32_out[32]);
 
/* ===========================================================================
 * Bitcoin addresses
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_addr_p2pkh(ufsecp_ctx* ctx,
                                            const uint8_t pubkey33[33],
                                            int network,
                                            char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_addr_p2wpkh(ufsecp_ctx* ctx,
                                             const uint8_t pubkey33[33],
                                             int network,
                                             char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_addr_p2tr(ufsecp_ctx* ctx,
                                           const uint8_t internal_key_x[32],
                                           int network,
                                           char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_addr_p2sh(
    const uint8_t* redeem_script, size_t redeem_script_len,
    int network,
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_addr_p2sh_p2wpkh(
    ufsecp_ctx* ctx,
    const uint8_t pubkey33[33],
    int network,
    char* addr_out, size_t* addr_len);
 
/* ===========================================================================
 * WIF (Wallet Import Format)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_wif_encode(ufsecp_ctx* ctx,
                                            const uint8_t privkey[32],
                                            int compressed, int network,
                                            char* wif_out, size_t* wif_len);
 
UFSECP_API ufsecp_error_t ufsecp_wif_decode(ufsecp_ctx* ctx,
                                            const char* wif,
                                            uint8_t privkey32_out[32],
                                            int* compressed_out,
                                            int* network_out);
 
/* ===========================================================================
 * BIP-32 (HD key derivation)
 * =========================================================================== */
 
typedef struct {
    uint8_t data[UFSECP_BIP32_SERIALIZED_LEN];
    uint8_t is_private;   
    uint8_t _pad[3];      
} ufsecp_bip32_key;
 
UFSECP_API ufsecp_error_t ufsecp_bip32_master(ufsecp_ctx* ctx,
                                              const uint8_t* seed, size_t seed_len,
                                              ufsecp_bip32_key* key_out);
 
UFSECP_API ufsecp_error_t ufsecp_bip32_derive(ufsecp_ctx* ctx,
                                              const ufsecp_bip32_key* parent,
                                              uint32_t index,
                                              ufsecp_bip32_key* child_out);
 
UFSECP_API ufsecp_error_t ufsecp_bip32_derive_path(ufsecp_ctx* ctx,
                                                   const ufsecp_bip32_key* master,
                                                   const char* path,
                                                   ufsecp_bip32_key* key_out);
 
UFSECP_API ufsecp_error_t ufsecp_bip32_privkey(ufsecp_ctx* ctx,
                                               const ufsecp_bip32_key* key,
                                               uint8_t privkey32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_bip32_pubkey(ufsecp_ctx* ctx,
                                              const ufsecp_bip32_key* key,
                                              uint8_t pubkey33_out[33]);
 
/* ===========================================================================
 * Taproot (BIP-341)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_taproot_output_key(
    ufsecp_ctx* ctx,
    const uint8_t internal_x[32],
    const uint8_t* merkle_root,
    uint8_t output_x_out[32],
    int* parity_out);
 
UFSECP_API ufsecp_error_t ufsecp_taproot_tweak_seckey(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t* merkle_root,
    uint8_t tweaked32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_taproot_verify(
    ufsecp_ctx* ctx,
    const uint8_t output_x[32], int output_parity,
    const uint8_t internal_x[32],
    const uint8_t* merkle_root, size_t merkle_root_len);
 
/* ===========================================================================
 * BIP-143: SegWit v0 Sighash
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_bip143_sighash(
    ufsecp_ctx* ctx,
    uint32_t version,
    const uint8_t hash_prevouts[32],
    const uint8_t hash_sequence[32],
    const uint8_t outpoint_txid[32], uint32_t outpoint_vout,
    const uint8_t* script_code, size_t script_code_len,
    uint64_t value,
    uint32_t sequence,
    const uint8_t hash_outputs[32],
    uint32_t locktime,
    uint32_t sighash_type,
    uint8_t sighash_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_bip143_p2wpkh_script_code(
    const uint8_t pubkey_hash[20],
    uint8_t script_code_out[25]);
 
/* ===========================================================================
 * BIP-144: Witness Transaction Serialization
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_bip144_txid(
    ufsecp_ctx* ctx,
    const uint8_t* raw_tx, size_t raw_tx_len,
    uint8_t txid_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_bip144_wtxid(
    ufsecp_ctx* ctx,
    const uint8_t* raw_tx, size_t raw_tx_len,
    uint8_t wtxid_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_bip144_witness_commitment(
    const uint8_t witness_root[32],
    const uint8_t witness_nonce[32],
    uint8_t commitment_out[32]);
 
/* ===========================================================================
 * BIP-141: Segregated Witness — Witness Programs
 * =========================================================================== */
 
UFSECP_API int ufsecp_segwit_is_witness_program(
    const uint8_t* script, size_t script_len);
 
UFSECP_API ufsecp_error_t ufsecp_segwit_parse_program(
    const uint8_t* script, size_t script_len,
    int* version_out,
    uint8_t* program_out, size_t* program_len_out);
 
UFSECP_API ufsecp_error_t ufsecp_segwit_p2wpkh_spk(
    const uint8_t pubkey_hash[20],
    uint8_t spk_out[22]);
 
UFSECP_API ufsecp_error_t ufsecp_segwit_p2wsh_spk(
    const uint8_t script_hash[32],
    uint8_t spk_out[34]);
 
UFSECP_API ufsecp_error_t ufsecp_segwit_p2tr_spk(
    const uint8_t output_key[32],
    uint8_t spk_out[34]);
 
UFSECP_API ufsecp_error_t ufsecp_segwit_witness_script_hash(
    const uint8_t* script, size_t script_len,
    uint8_t hash_out[32]);
 
/* ===========================================================================
 * BIP-342: Tapscript Sighash
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_taproot_keypath_sighash(
    ufsecp_ctx* ctx,
    uint32_t version, uint32_t locktime,
    size_t input_count,
    const uint8_t* prevout_txids,   /* input_count*32 bytes, flattened */
    const uint32_t* prevout_vouts,
    const uint64_t* input_amounts,
    const uint32_t* input_sequences,
    const uint8_t* const* input_spks,
    const size_t* input_spk_lens,
    size_t output_count,
    const uint64_t* output_values,
    const uint8_t* const* output_spks,
    const size_t* output_spk_lens,
    size_t input_index,
    uint8_t hash_type,
    const uint8_t* annex, size_t annex_len,
    uint8_t sighash_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_tapscript_sighash(
    ufsecp_ctx* ctx,
    uint32_t version, uint32_t locktime,
    size_t input_count,
    const uint8_t* prevout_txids,
    const uint32_t* prevout_vouts,
    const uint64_t* input_amounts,
    const uint32_t* input_sequences,
    const uint8_t* const* input_spks,
    const size_t* input_spk_lens,
    size_t output_count,
    const uint64_t* output_values,
    const uint8_t* const* output_spks,
    const size_t* output_spk_lens,
    size_t input_index,
    uint8_t hash_type,
    const uint8_t tapleaf_hash[32],
    uint8_t key_version,
    uint32_t code_separator_pos,
    const uint8_t* annex, size_t annex_len,
    uint8_t sighash_out[32]);
 
/* ===========================================================================
 * Ethereum (conditional: SECP256K1_BUILD_ETHEREUM)
 * =========================================================================== */
 
/* ===========================================================================
 * Public key arithmetic
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_add(ufsecp_ctx* ctx,
                                            const uint8_t a33[33],
                                            const uint8_t b33[33],
                                            uint8_t out33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_negate(ufsecp_ctx* ctx,
                                               const uint8_t pubkey33[33],
                                               uint8_t out33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_tweak_add(ufsecp_ctx* ctx,
                                                  const uint8_t pubkey33[33],
                                                  const uint8_t tweak[32],
                                                  uint8_t out33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_tweak_mul(ufsecp_ctx* ctx,
                                                  const uint8_t pubkey33[33],
                                                  const uint8_t tweak[32],
                                                  uint8_t out33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pubkey_combine(ufsecp_ctx* ctx,
                                                const uint8_t* pubkeys,
                                                size_t n,
                                                uint8_t out33[33]);
 
/* ===========================================================================
 * BIP-39 (Mnemonic seed phrases)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_bip39_generate(ufsecp_ctx* ctx,
                                                size_t entropy_bytes,
                                                const uint8_t* entropy_in,
                                                char* mnemonic_out,
                                                size_t* mnemonic_len);
 
UFSECP_API ufsecp_error_t ufsecp_bip39_validate(const ufsecp_ctx* ctx,
                                                const char* mnemonic);
 
UFSECP_API ufsecp_error_t ufsecp_bip39_to_seed(ufsecp_ctx* ctx,
                                               const char* mnemonic,
                                               const char* passphrase,
                                               uint8_t seed64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_bip39_to_entropy(ufsecp_ctx* ctx,
                                                  const char* mnemonic,
                                                  uint8_t* entropy_out,
                                                  size_t* entropy_len);
 
/* ===========================================================================
 * Batch verification
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_batch_verify(
    ufsecp_ctx* ctx,
    const uint8_t* entries, size_t n);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_batch_verify(
    ufsecp_ctx* ctx,
    const uint8_t* entries, size_t n);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_batch_identify_invalid(
    ufsecp_ctx* ctx,
    const uint8_t* entries, size_t n,
    size_t* invalid_out, size_t* invalid_count);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_batch_identify_invalid(
    ufsecp_ctx* ctx,
    const uint8_t* entries, size_t n,
    size_t* invalid_out, size_t* invalid_count);
 
/* ===========================================================================
 * SHA-512
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_sha512(const uint8_t* data, size_t len,
                                        uint8_t digest64_out[64]);
 
/* ===========================================================================
 * Multi-scalar multiplication
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_shamir_trick(
    ufsecp_ctx* ctx,
    const uint8_t a[32], const uint8_t P33[33],
    const uint8_t b[32], const uint8_t Q33[33],
    uint8_t out33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_multi_scalar_mul(
    ufsecp_ctx* ctx,
    const uint8_t* scalars, const uint8_t* points, size_t n,
    uint8_t out33[33]);
 
/* ===========================================================================
 * MuSig2 (BIP-327 multi-signatures)
 * =========================================================================== */
 
#define UFSECP_MUSIG2_PUBNONCE_LEN   66  
#define UFSECP_MUSIG2_AGGNONCE_LEN   66
#define UFSECP_MUSIG2_KEYAGG_LEN     165 
#define UFSECP_MUSIG2_SESSION_LEN    165 
#define UFSECP_MUSIG2_SECNONCE_LEN   64  
UFSECP_API ufsecp_error_t ufsecp_musig2_key_agg(
    ufsecp_ctx* ctx,
    const uint8_t* pubkeys, size_t n,
    uint8_t keyagg_out[UFSECP_MUSIG2_KEYAGG_LEN],
    uint8_t agg_pubkey32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_nonce_gen(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t pubkey32[32],
    const uint8_t agg_pubkey32[32],
    const uint8_t msg32[32],
    const uint8_t extra_in[32],
    uint8_t secnonce_out[UFSECP_MUSIG2_SECNONCE_LEN],
    uint8_t pubnonce_out[UFSECP_MUSIG2_PUBNONCE_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_nonce_agg(
    ufsecp_ctx* ctx,
    const uint8_t* pubnonces, size_t n,
    uint8_t aggnonce_out[UFSECP_MUSIG2_AGGNONCE_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_start_sign_session(
    ufsecp_ctx* ctx,
    const uint8_t aggnonce[UFSECP_MUSIG2_AGGNONCE_LEN],
    const uint8_t keyagg[UFSECP_MUSIG2_KEYAGG_LEN],
    const uint8_t msg32[32],
    uint8_t session_out[UFSECP_MUSIG2_SESSION_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_partial_sign(
    ufsecp_ctx* ctx,
    uint8_t secnonce[UFSECP_MUSIG2_SECNONCE_LEN],
    const uint8_t privkey[32],
    const uint8_t keyagg[UFSECP_MUSIG2_KEYAGG_LEN],
    const uint8_t session[UFSECP_MUSIG2_SESSION_LEN],
    size_t signer_index,
    uint8_t partial_sig32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_partial_verify(
    ufsecp_ctx* ctx,
    const uint8_t partial_sig32[32],
    const uint8_t pubnonce[UFSECP_MUSIG2_PUBNONCE_LEN],
    const uint8_t pubkey32[32],
    const uint8_t keyagg[UFSECP_MUSIG2_KEYAGG_LEN],
    const uint8_t session[UFSECP_MUSIG2_SESSION_LEN],
    size_t signer_index);
 
UFSECP_API ufsecp_error_t ufsecp_musig2_partial_sig_agg(
    ufsecp_ctx* ctx,
    const uint8_t* partial_sigs, size_t n,
    const uint8_t session[UFSECP_MUSIG2_SESSION_LEN],
    uint8_t sig64_out[64]);
 
/* ===========================================================================
 * FROST (Threshold signatures)
 * =========================================================================== */
 
#define UFSECP_FROST_SHARE_LEN         36   
#define UFSECP_FROST_KEYPKG_LEN        141  
#define UFSECP_FROST_NONCE_LEN         64   
#define UFSECP_FROST_NONCE_COMMIT_LEN  70   
UFSECP_API ufsecp_error_t ufsecp_frost_keygen_begin(
    ufsecp_ctx* ctx,
    uint32_t participant_id, uint32_t threshold, uint32_t num_participants,
    const uint8_t seed[32],
    uint8_t* commits_out, size_t* commits_len,
    uint8_t* shares_out, size_t* shares_len);
 
UFSECP_API ufsecp_error_t ufsecp_frost_keygen_finalize(
    ufsecp_ctx* ctx,
    uint32_t participant_id,
    const uint8_t* all_commits, size_t commits_len,
    const uint8_t* received_shares, size_t shares_len,
    uint32_t threshold, uint32_t num_participants,
    uint8_t keypkg_out[UFSECP_FROST_KEYPKG_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_frost_sign_nonce_gen(
    ufsecp_ctx* ctx,
    uint32_t participant_id,
    const uint8_t nonce_seed[32],
    uint8_t nonce_out[UFSECP_FROST_NONCE_LEN],
    uint8_t nonce_commit_out[UFSECP_FROST_NONCE_COMMIT_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_frost_sign(
    ufsecp_ctx* ctx,
    const uint8_t keypkg[UFSECP_FROST_KEYPKG_LEN],
    uint8_t nonce[UFSECP_FROST_NONCE_LEN],
    const uint8_t msg32[32],
    const uint8_t* nonce_commits, size_t n_signers,
    uint8_t partial_sig_out[36]);
 
UFSECP_API ufsecp_error_t ufsecp_frost_verify_partial(
    ufsecp_ctx* ctx,
    const uint8_t partial_sig[36],
    const uint8_t verification_share33[33],
    const uint8_t* nonce_commits, size_t n_signers,
    const uint8_t msg32[32],
    const uint8_t group_pubkey33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_frost_aggregate(
    ufsecp_ctx* ctx,
    const uint8_t* partial_sigs, size_t n,
    const uint8_t* nonce_commits, size_t n_signers,
    const uint8_t group_pubkey33[33],
    const uint8_t msg32[32],
    uint8_t sig64_out[64]);
 
/* ===========================================================================
 * Adaptor signatures (Atomic swaps / DLCs)
 * =========================================================================== */
 
#define UFSECP_SCHNORR_ADAPTOR_SIG_LEN 97  
#define UFSECP_ECDSA_ADAPTOR_SIG_LEN   130 
UFSECP_API ufsecp_error_t ufsecp_schnorr_adaptor_sign(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t msg32[32],
    const uint8_t adaptor_point33[33],
    const uint8_t aux_rand[32],
    uint8_t pre_sig_out[UFSECP_SCHNORR_ADAPTOR_SIG_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_adaptor_verify(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_SCHNORR_ADAPTOR_SIG_LEN],
    const uint8_t pubkey_x[32],
    const uint8_t msg32[32],
    const uint8_t adaptor_point33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_adaptor_adapt(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_SCHNORR_ADAPTOR_SIG_LEN],
    const uint8_t adaptor_secret[32],
    uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_adaptor_extract(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_SCHNORR_ADAPTOR_SIG_LEN],
    const uint8_t sig64[64],
    uint8_t secret32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_adaptor_sign(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t msg32[32],
    const uint8_t adaptor_point33[33],
    uint8_t pre_sig_out[UFSECP_ECDSA_ADAPTOR_SIG_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_adaptor_verify(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_ECDSA_ADAPTOR_SIG_LEN],
    const uint8_t pubkey33[33],
    const uint8_t msg32[32],
    const uint8_t adaptor_point33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_adaptor_adapt(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_ECDSA_ADAPTOR_SIG_LEN],
    const uint8_t adaptor_secret[32],
    uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_ecdsa_adaptor_extract(
    ufsecp_ctx* ctx,
    const uint8_t pre_sig[UFSECP_ECDSA_ADAPTOR_SIG_LEN],
    const uint8_t sig64[64],
    uint8_t secret32_out[32]);
 
/* ===========================================================================
 * Pedersen commitments
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_pedersen_commit(
    ufsecp_ctx* ctx,
    const uint8_t value[32],
    const uint8_t blinding[32],
    uint8_t commitment33_out[33]);
 
UFSECP_API ufsecp_error_t ufsecp_pedersen_verify(
    ufsecp_ctx* ctx,
    const uint8_t commitment33[33],
    const uint8_t value[32],
    const uint8_t blinding[32]);
 
UFSECP_API ufsecp_error_t ufsecp_pedersen_verify_sum(
    ufsecp_ctx* ctx,
    const uint8_t* pos, size_t n_pos,
    const uint8_t* neg, size_t n_neg);
 
UFSECP_API ufsecp_error_t ufsecp_pedersen_blind_sum(
    ufsecp_ctx* ctx,
    const uint8_t* blinds_in, size_t n_in,
    const uint8_t* blinds_out, size_t n_out,
    uint8_t sum32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_pedersen_switch_commit(
    ufsecp_ctx* ctx,
    const uint8_t value[32],
    const uint8_t blinding[32],
    const uint8_t switch_blind[32],
    uint8_t commitment33_out[33]);
 
/* ===========================================================================
 * Zero-knowledge proofs
 * =========================================================================== */
 
#define UFSECP_ZK_KNOWLEDGE_PROOF_LEN  64  
#define UFSECP_ZK_DLEQ_PROOF_LEN       64  
#define UFSECP_ZK_RANGE_PROOF_MAX_LEN  688 
UFSECP_API ufsecp_error_t ufsecp_zk_knowledge_prove(
    ufsecp_ctx* ctx,
    const uint8_t secret[32],
    const uint8_t pubkey33[33],
    const uint8_t msg32[32],
    const uint8_t aux_rand[32],
    uint8_t proof_out[UFSECP_ZK_KNOWLEDGE_PROOF_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_zk_knowledge_verify(
    ufsecp_ctx* ctx,
    const uint8_t proof[UFSECP_ZK_KNOWLEDGE_PROOF_LEN],
    const uint8_t pubkey33[33],
    const uint8_t msg32[32]);
 
UFSECP_API ufsecp_error_t ufsecp_zk_dleq_prove(
    ufsecp_ctx* ctx,
    const uint8_t secret[32],
    const uint8_t G33[33], const uint8_t H33[33],
    const uint8_t P33[33], const uint8_t Q33[33],
    const uint8_t aux_rand[32],
    uint8_t proof_out[UFSECP_ZK_DLEQ_PROOF_LEN]);
 
UFSECP_API ufsecp_error_t ufsecp_zk_dleq_verify(
    ufsecp_ctx* ctx,
    const uint8_t proof[UFSECP_ZK_DLEQ_PROOF_LEN],
    const uint8_t G33[33], const uint8_t H33[33],
    const uint8_t P33[33], const uint8_t Q33[33]);
 
UFSECP_API ufsecp_error_t ufsecp_zk_range_prove(
    ufsecp_ctx* ctx,
    uint64_t value,
    const uint8_t blinding[32],
    const uint8_t commitment33[33],
    const uint8_t aux_rand[32],
    uint8_t* proof_out, size_t* proof_len);
 
UFSECP_API ufsecp_error_t ufsecp_zk_range_verify(
    ufsecp_ctx* ctx,
    const uint8_t commitment33[33],
    const uint8_t* proof, size_t proof_len);
 
typedef struct {
    uint64_t limbs[5];  
} ufsecp_ff_limbs_t;
 
typedef struct {
    /* ── public inputs ─────────────────────────────────────────────────── */
    uint8_t msg[32];       
    uint8_t sig_r[32];     
    uint8_t sig_s[32];     
    uint8_t pub_x[32];     
    uint8_t pub_y[32];     
    /* ── private witness (circuit signals) ─────────────────────────────── */
    uint8_t s_inv[32];             
    uint8_t u1[32];                
    uint8_t u2[32];                
    uint8_t result_x[32];          
    uint8_t result_y[32];          
    uint8_t result_x_mod_n[32];    
    /* ── 5×52-bit foreign-field limb decompositions ─────────────────────── */
    ufsecp_ff_limbs_t lmb_sig_r;           
    ufsecp_ff_limbs_t lmb_sig_s;           
    ufsecp_ff_limbs_t lmb_pub_x;           
    ufsecp_ff_limbs_t lmb_pub_y;           
    ufsecp_ff_limbs_t lmb_s_inv;           
    ufsecp_ff_limbs_t lmb_u1;              
    ufsecp_ff_limbs_t lmb_u2;              
    ufsecp_ff_limbs_t lmb_result_x;        
    ufsecp_ff_limbs_t lmb_result_y;        
    ufsecp_ff_limbs_t lmb_result_x_mod_n;  
    /* ── verdict ──────────────────────────────────────────────────────── */
    int valid;  
} ufsecp_ecdsa_snark_witness_t;
 
UFSECP_API ufsecp_error_t ufsecp_zk_ecdsa_snark_witness(
    ufsecp_ctx* ctx,
    const uint8_t msg_hash32[32],
    const uint8_t pubkey33[33],
    const uint8_t sig64[64],
    ufsecp_ecdsa_snark_witness_t* out);
 
/* ===========================================================================
 * BIP340 Schnorr-in-SNARK Foreign-Field Witness
 * =========================================================================== */
 
typedef struct {
    /* ── public inputs ─────────────────────────────────────────────────── */
    uint8_t msg[32];       
    uint8_t sig_r[32];     
    uint8_t sig_s[32];     
    uint8_t pub_x[32];     
    /* ── private witness (circuit signals) ─────────────────────────────── */
    uint8_t r_y[32];       
    uint8_t pub_y[32];     
    uint8_t e[32];         
    /* ── 5×52-bit foreign-field limb decompositions ─────────────────────── */
    ufsecp_ff_limbs_t lmb_sig_r;           
    ufsecp_ff_limbs_t lmb_sig_s;           
    ufsecp_ff_limbs_t lmb_pub_x;           
    ufsecp_ff_limbs_t lmb_r_y;             
    ufsecp_ff_limbs_t lmb_pub_y;           
    ufsecp_ff_limbs_t lmb_e;               
    /* ── verdict ──────────────────────────────────────────────────────── */
    int valid;  
} ufsecp_schnorr_snark_witness_t;
 
UFSECP_API ufsecp_error_t ufsecp_zk_schnorr_snark_witness(
    ufsecp_ctx* ctx,
    const uint8_t msg32[32],
    const uint8_t pubkey_x32[32],
    const uint8_t sig64[64],
    ufsecp_schnorr_snark_witness_t* out);
 
/* ===========================================================================
 * Multi-coin wallet infrastructure
 * =========================================================================== */
 
#define UFSECP_COIN_ADDR_MAX_LEN 128
 
#define UFSECP_COIN_BITCOIN      0
#define UFSECP_COIN_LITECOIN     2
#define UFSECP_COIN_DOGECOIN     3
#define UFSECP_COIN_DASH         5
#define UFSECP_COIN_ETHEREUM     60
#define UFSECP_COIN_BITCOIN_CASH 145
#define UFSECP_COIN_TRON         195
 
UFSECP_API ufsecp_error_t ufsecp_coin_address(
    ufsecp_ctx* ctx,
    const uint8_t pubkey33[33],
    uint32_t coin_type, int testnet,
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_coin_derive_from_seed(
    ufsecp_ctx* ctx,
    const uint8_t* seed, size_t seed_len,
    uint32_t coin_type, uint32_t account, int change, uint32_t index,
    int testnet,
    uint8_t* privkey32_out,
    uint8_t* pubkey33_out,
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_coin_wif_encode(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    uint32_t coin_type, int testnet,
    char* wif_out, size_t* wif_len);
 
UFSECP_API ufsecp_error_t ufsecp_btc_message_sign(
    ufsecp_ctx* ctx,
    const uint8_t* msg, size_t msg_len,
    const uint8_t privkey[32],
    char* base64_out, size_t* base64_len);
 
UFSECP_API ufsecp_error_t ufsecp_btc_message_verify(
    ufsecp_ctx* ctx,
    const uint8_t* msg, size_t msg_len,
    const uint8_t pubkey33[33],
    const char* base64_sig);
 
UFSECP_API ufsecp_error_t ufsecp_btc_message_hash(
    const uint8_t* msg, size_t msg_len,
    uint8_t digest32_out[32]);
 
/* ===========================================================================
 * BIP-352 Silent Payments
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_silent_payment_address(
    ufsecp_ctx* ctx,
    const uint8_t scan_privkey[32],
    const uint8_t spend_privkey[32],
    uint8_t scan_pubkey33_out[33],
    uint8_t spend_pubkey33_out[33],
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_silent_payment_create_output(
    ufsecp_ctx* ctx,
    const uint8_t* input_privkeys, size_t n_inputs,
    const uint8_t scan_pubkey33[33],
    const uint8_t spend_pubkey33[33],
    uint32_t k,
    uint8_t output_pubkey33_out[33],
    uint8_t* tweak32_out);
 
UFSECP_API ufsecp_error_t ufsecp_silent_payment_scan(
    ufsecp_ctx* ctx,
    const uint8_t scan_privkey[32],
    const uint8_t spend_privkey[32],
    const uint8_t* input_pubkeys33, size_t n_input_pubkeys,
    const uint8_t* output_xonly32, size_t n_outputs,
    uint32_t* found_indices_out,
    uint8_t* found_privkeys_out,
    size_t* n_found);
 
/* ===========================================================================
 * ECIES (Elliptic Curve Integrated Encryption Scheme)
 * =========================================================================== */
 
#define UFSECP_ECIES_OVERHEAD 81
 
UFSECP_API ufsecp_error_t ufsecp_ecies_encrypt(
    ufsecp_ctx* ctx,
    const uint8_t recipient_pubkey33[33],
    const uint8_t* plaintext, size_t plaintext_len,
    uint8_t* envelope_out, size_t* envelope_len);
 
UFSECP_API ufsecp_error_t ufsecp_ecies_decrypt(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t* envelope, size_t envelope_len,
    uint8_t* plaintext_out, size_t* plaintext_len);
 
/* ========================================================================== */
/* BIP-324: Version 2 P2P Encrypted Transport (conditional: SECP256K1_BIP324) */
/* ========================================================================== */
#ifdef SECP256K1_BIP324
 
typedef struct ufsecp_bip324_session ufsecp_bip324_session;
 
UFSECP_API ufsecp_error_t ufsecp_bip324_create(
    ufsecp_ctx* ctx,
    int initiator,
    ufsecp_bip324_session** session_out,
    uint8_t ellswift64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_bip324_handshake(
    ufsecp_bip324_session* session,
    const uint8_t peer_ellswift64[64],
    uint8_t session_id32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_bip324_encrypt(
    ufsecp_bip324_session* session,
    const uint8_t* plaintext, size_t plaintext_len,
    uint8_t* out, size_t* out_len);
 
UFSECP_API ufsecp_error_t ufsecp_bip324_decrypt(
    ufsecp_bip324_session* session,
    const uint8_t* encrypted, size_t encrypted_len,
    uint8_t* plaintext_out, size_t* plaintext_len);
 
UFSECP_API void ufsecp_bip324_destroy(ufsecp_bip324_session* session);
 
UFSECP_API ufsecp_error_t ufsecp_aead_chacha20_poly1305_encrypt(
    const uint8_t key[32], const uint8_t nonce[12],
    const uint8_t* aad, size_t aad_len,
    const uint8_t* plaintext, size_t plaintext_len,
    uint8_t* out, uint8_t tag[16]);
 
UFSECP_API ufsecp_error_t ufsecp_aead_chacha20_poly1305_decrypt(
    const uint8_t key[32], const uint8_t nonce[12],
    const uint8_t* aad, size_t aad_len,
    const uint8_t* ciphertext, size_t ciphertext_len,
    const uint8_t tag[16], uint8_t* out);
 
UFSECP_API ufsecp_error_t ufsecp_ellswift_create(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    uint8_t encoding64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_ellswift_xdh(
    ufsecp_ctx* ctx,
    const uint8_t ell_a64[64],
    const uint8_t ell_b64[64],
    const uint8_t our_privkey[32],
    int initiating,
    uint8_t secret32_out[32]);
 
#endif /* SECP256K1_BIP324 */
 
#ifdef SECP256K1_BUILD_ETHEREUM
 
#define UFSECP_ETH_ADDR_LEN 20
 
UFSECP_API ufsecp_error_t ufsecp_keccak256(const uint8_t* data, size_t len,
                                           uint8_t digest32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_eth_address(ufsecp_ctx* ctx,
                                             const uint8_t pubkey33[33],
                                             uint8_t addr20_out[20]);
 
UFSECP_API ufsecp_error_t ufsecp_eth_address_checksummed(
    ufsecp_ctx* ctx,
    const uint8_t pubkey33[33],
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_eth_personal_hash(const uint8_t* msg, size_t msg_len,
                                                   uint8_t digest32_out[32]);
 
UFSECP_API ufsecp_error_t ufsecp_eth_sign(ufsecp_ctx* ctx,
                                          const uint8_t msg32[32],
                                          const uint8_t privkey[32],
                                          uint8_t r_out[32],
                                          uint8_t s_out[32],
                                          uint64_t* v_out,
                                          uint64_t chain_id);
 
UFSECP_API ufsecp_error_t ufsecp_eth_ecrecover(ufsecp_ctx* ctx,
                                               const uint8_t msg32[32],
                                               const uint8_t r[32],
                                               const uint8_t s[32],
                                               uint64_t v,
                                               uint8_t addr20_out[20]);
 
#endif /* SECP256K1_BUILD_ETHEREUM */
 
/* ===========================================================================
 * BIP-85 — Deterministic Entropy from BIP-32 Keychains
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_bip85_entropy(
    ufsecp_ctx* ctx,
    const ufsecp_bip32_key* master_xprv,
    const char* path,
    uint8_t* entropy_out, size_t entropy_len);
 
UFSECP_API ufsecp_error_t ufsecp_bip85_bip39(
    ufsecp_ctx* ctx,
    const ufsecp_bip32_key* master_xprv,
    uint32_t words, uint32_t language_index, uint32_t index,
    char* mnemonic_out, size_t* mnemonic_len);
 
/* ===========================================================================
 * BIP-340 Variable-Length Schnorr
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_sign_msg(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    const uint8_t* msg, size_t msg_len,
    const uint8_t* aux_rand32,
    uint8_t sig64_out[64]);
 
UFSECP_API ufsecp_error_t ufsecp_schnorr_verify_msg(
    ufsecp_ctx* ctx,
    const uint8_t pubkey_x[32],
    const uint8_t* msg, size_t msg_len,
    const uint8_t sig64[64]);
 
/* ===========================================================================
 * BIP-322 — Generic Message Signing
 * =========================================================================== */
 
typedef enum {
    UFSECP_BIP322_ADDR_P2PKH        = 0,
    UFSECP_BIP322_ADDR_P2WPKH       = 1,
    UFSECP_BIP322_ADDR_P2TR         = 2,
    UFSECP_BIP322_ADDR_P2SH_P2WPKH  = 3,
} ufsecp_bip322_addr_type;
 
UFSECP_API ufsecp_error_t ufsecp_bip322_sign(
    ufsecp_ctx* ctx,
    const uint8_t privkey[32],
    ufsecp_bip322_addr_type addr_type,
    const uint8_t* msg, size_t msg_len,
    uint8_t* sig_out, size_t* sig_len);
 
UFSECP_API ufsecp_error_t ufsecp_bip322_verify(
    ufsecp_ctx* ctx,
    const uint8_t* pubkey, size_t pubkey_len,
    ufsecp_bip322_addr_type addr_type,
    const uint8_t* msg, size_t msg_len,
    const uint8_t* sig, size_t sig_len);
 
/* ===========================================================================
 * BIP-157/158 — Compact Block Filters (Golomb-Coded Set)
 * =========================================================================== */
 
UFSECP_API ufsecp_error_t ufsecp_gcs_build(
    const uint8_t key[16],
    const uint8_t** data, const size_t* data_sizes, size_t count,
    uint8_t* filter_out, size_t* filter_len);
 
UFSECP_API ufsecp_error_t ufsecp_gcs_match(
    const uint8_t key[16],
    const uint8_t* filter, size_t filter_len,
    size_t n_items,
    const uint8_t* item, size_t item_len);
 
UFSECP_API ufsecp_error_t ufsecp_gcs_match_any(
    const uint8_t key[16],
    const uint8_t* filter, size_t filter_len,
    size_t n_items,
    const uint8_t** query, const size_t* query_sizes, size_t query_count);
 
/* ===========================================================================
 * BIP-174/370 — PSBT Signing Helpers
 * =========================================================================== */
 
#define UFSECP_SIGHASH_ALL          0x01
#define UFSECP_SIGHASH_NONE         0x02
#define UFSECP_SIGHASH_SINGLE       0x03
#define UFSECP_SIGHASH_ANYONECANPAY 0x80
#define UFSECP_SIGHASH_DEFAULT      0x00  /* BIP-341 Taproot default */
 
UFSECP_API ufsecp_error_t ufsecp_psbt_sign_legacy(
    ufsecp_ctx* ctx,
    const uint8_t sighash32[32],
    const uint8_t privkey[32],
    uint8_t sighash_type,
    uint8_t* sig_out, size_t* sig_len);
 
UFSECP_API ufsecp_error_t ufsecp_psbt_sign_segwit(
    ufsecp_ctx* ctx,
    const uint8_t sighash32[32],
    const uint8_t privkey[32],
    uint8_t sighash_type,
    uint8_t* sig_out, size_t* sig_len);
 
UFSECP_API ufsecp_error_t ufsecp_psbt_sign_taproot(
    ufsecp_ctx* ctx,
    const uint8_t sighash32[32],
    const uint8_t privkey[32],
    uint8_t sighash_type,
    const uint8_t* aux_rand32,
    uint8_t* sig_out, size_t* sig_len);
 
UFSECP_API ufsecp_error_t ufsecp_psbt_derive_key(
    ufsecp_ctx* ctx,
    const ufsecp_bip32_key* master_xprv,
    const char* key_path,
    uint8_t privkey_out[32]);
 
/* ===========================================================================
 * BIP-380..386 — Output Descriptors (key expression parser)
 * =========================================================================== */
 
typedef enum {
    UFSECP_DESC_PK       = 0,   
    UFSECP_DESC_PKH      = 1,   
    UFSECP_DESC_WPKH     = 2,   
    UFSECP_DESC_TR       = 3,   
    UFSECP_DESC_SH_WPKH  = 4,   
} ufsecp_desc_type;
 
typedef struct {
    ufsecp_desc_type type;
    uint8_t pubkey[33];        
    uint8_t pubkey_len;        
    int network;               
    char path[64];             
} ufsecp_desc_key;
 
UFSECP_API ufsecp_error_t ufsecp_descriptor_parse(
    ufsecp_ctx* ctx,
    const char* descriptor,
    uint32_t index,
    ufsecp_desc_key* key_out,
    char* addr_out, size_t* addr_len);
 
UFSECP_API ufsecp_error_t ufsecp_descriptor_address(
    ufsecp_ctx* ctx,
    const char* descriptor,
    uint32_t index,
    char* addr_out, size_t* addr_len);
 
#ifdef __cplusplus
}
 
/* -- ABI layout guards (C++ only) ------------------------------------------ */
/* These fire at compile time if struct layout changes, preventing silent ABI  */
/* breaks when bindings or cached objects assume a fixed layout.               */
static_assert(sizeof(ufsecp_bip32_key) == 82,
              "ABI break: ufsecp_bip32_key size changed (expected 82)");
static_assert(UFSECP_BIP32_SERIALIZED_LEN == 78,
              "ABI break: UFSECP_BIP32_SERIALIZED_LEN changed (expected 78)");
static_assert(UFSECP_PRIVKEY_LEN == 32,
              "ABI break: UFSECP_PRIVKEY_LEN changed");
static_assert(UFSECP_PUBKEY_COMPRESSED_LEN == 33,
              "ABI break: UFSECP_PUBKEY_COMPRESSED_LEN changed");
static_assert(UFSECP_SIG_COMPACT_LEN == 64,
              "ABI break: UFSECP_SIG_COMPACT_LEN changed");
#else
/* C11 _Static_assert equivalent for pure-C consumers */
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
_Static_assert(sizeof(ufsecp_bip32_key) == 82,
               "ABI break: ufsecp_bip32_key size changed (expected 82)");
#endif
#endif
 
#endif /* UFSECP_H */