ufsecp_gpu.h

Go to the documentation of this file.

/* ============================================================================
 * UltrafastSecp256k1 -- GPU Acceleration C ABI
 * ============================================================================
 *
 * Backend-neutral C ABI for GPU-accelerated batch secp256k1 operations.
 *
 * ## Design principles
 *
 *   1. Opaque GPU context (`ufsecp_gpu_ctx*`) -- backend, device, queue state.
 *   2. Every function returns `ufsecp_error_t` (0 = OK).
 *   3. Backend-neutral: CUDA / OpenCL / Metal are implementation details.
 *   4. No internal GPU types leak -- all I/O is `uint8_t[]` with fixed strides.
 *   5. Thread safety: each gpu_ctx is single-thread. Create one per thread or
 *      protect externally.
 *   6. On the stable public GPU C ABI declared in this header, most operations
 *      are PUBLIC-DATA ONLY. ECDH and BIP-324 AEAD encrypt/decrypt are
 *      secret-bearing and documented as such.
 *
 * ## Feature maturity
 *
 *   This header defines the stable GPU API surface. The stable batch-op
 *   surface currently includes 13 backend-neutral operations: 8 core ops
 *   (generator_mul, ECDSA verify, Schnorr verify, ECDH, Hash160, MSM,
 *   FROST partial verify, ecrecover) plus 5 extended ZK/BIP-324 ops.
 *   Internal kernels, benchmarks, or backend test code may cover broader
 *   primitives; that does not by itself make those primitives part of the
 *   stable production GPU ABI.
 *
 *     CUDA   -- all 13 stable GPU batch ops implemented
 *     OpenCL -- all 13 stable GPU batch ops implemented
 *     Metal  -- all 13 stable GPU batch ops implemented
 *
 *   Operations that a backend does not implement return
 *   UFSECP_ERR_GPU_UNSUPPORTED (104). This is no longer expected for the
 *   stable 13-op GPU C ABI on compiled CUDA/OpenCL/Metal backends.
 *
 *   Guarantees:
 *     - Discovery + lifecycle functions work on all compiled backends.
 *     - Per-item results for batch ops are well-defined even on partial failure.
 *     - ECDH is the only secret-bearing GPU operation. All others are public-data.
 *     - ABI layout (function signatures, strides, error codes) is stable.
 *     - Backend additions do not break existing calling code.
 *
 * ## Memory
 *
 *   Caller owns all input/output buffers. Library manages device memory
 *   internally and copies results back on return.
 *
 * ## Batch layout
 *
 *   All batch inputs/outputs use flat contiguous arrays with fixed per-item
 *   strides documented in each function.
 *
 * ============================================================================ */
#ifndef UFSECP_GPU_H
#define UFSECP_GPU_H
 
#include "ufsecp_version.h"
#include "ufsecp_error.h"
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
#  define UFSECP_NOEXCEPT noexcept
extern "C" {
#else
#  define UFSECP_NOEXCEPT
#endif
 
/* ============================================================================
 * GPU-specific error codes (start at 100 to avoid conflict with CPU codes)
 * ============================================================================ */
 
#define UFSECP_ERR_GPU_UNAVAILABLE  100  
#define UFSECP_ERR_GPU_DEVICE       101  
#define UFSECP_ERR_GPU_LAUNCH       102  
#define UFSECP_ERR_GPU_MEMORY       103  
#define UFSECP_ERR_GPU_UNSUPPORTED  104  
#define UFSECP_ERR_GPU_BACKEND      105  
#define UFSECP_ERR_GPU_QUEUE        106  
/* ============================================================================
 * GPU backend identifiers
 * ============================================================================ */
 
#define UFSECP_GPU_BACKEND_NONE     0
#define UFSECP_GPU_BACKEND_CUDA     1
#define UFSECP_GPU_BACKEND_OPENCL   2
#define UFSECP_GPU_BACKEND_METAL    3
 
/* ============================================================================
 * Opaque GPU context
 * ============================================================================ */
 
typedef struct ufsecp_gpu_ctx ufsecp_gpu_ctx;
 
/* ============================================================================
 * Backend & device discovery
 * ============================================================================ */
 
UFSECP_API uint32_t ufsecp_gpu_backend_count(uint32_t* backend_ids, uint32_t max_ids) UFSECP_NOEXCEPT;
 
UFSECP_API const char* ufsecp_gpu_backend_name(uint32_t backend_id);
 
UFSECP_API int ufsecp_gpu_is_available(uint32_t backend_id) UFSECP_NOEXCEPT;
 
UFSECP_API uint32_t ufsecp_gpu_device_count(uint32_t backend_id) UFSECP_NOEXCEPT;
 
typedef struct {
    char     name[128];              
    uint64_t global_mem_bytes;       
    uint32_t compute_units;          
    uint32_t max_clock_mhz;         
    uint32_t max_threads_per_block;  
    uint32_t backend_id;             
    uint32_t device_index;           
} ufsecp_gpu_device_info_t;
 
UFSECP_API ufsecp_error_t ufsecp_gpu_device_info(
    uint32_t backend_id,
    uint32_t device_index,
    ufsecp_gpu_device_info_t* info_out);
 
/* ============================================================================
 * GPU context lifecycle
 * ============================================================================ */
 
UFSECP_API ufsecp_error_t ufsecp_gpu_ctx_create(
    ufsecp_gpu_ctx** ctx_out,
    uint32_t backend_id,
    uint32_t device_index);
 
UFSECP_API void ufsecp_gpu_ctx_destroy(ufsecp_gpu_ctx* ctx);
 
UFSECP_API int ufsecp_gpu_is_ready(const ufsecp_gpu_ctx* ctx) UFSECP_NOEXCEPT;
 
UFSECP_API ufsecp_error_t ufsecp_gpu_last_error(const ufsecp_gpu_ctx* ctx);
 
UFSECP_API const char* ufsecp_gpu_last_error_msg(const ufsecp_gpu_ctx* ctx);
 
/* ============================================================================
 * First-wave GPU batch operations
 * ============================================================================ */
 
UFSECP_API ufsecp_error_t ufsecp_gpu_generator_mul_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* scalars32,
    size_t count,
    uint8_t* out_pubkeys33);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_ecdsa_verify_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* msg_hashes32,
    const uint8_t* pubkeys33,
    const uint8_t* sigs64,
    size_t count,
    uint8_t* out_results);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_schnorr_verify_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* msg_hashes32,
    const uint8_t* pubkeys_x32,
    const uint8_t* sigs64,
    size_t count,
    uint8_t* out_results);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_ecdh_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* privkeys32,
    const uint8_t* peer_pubkeys33,
    size_t count,
    uint8_t* out_secrets32);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_hash160_pubkey_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* pubkeys33,
    size_t count,
    uint8_t* out_hash160);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_msm(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* scalars32,
    const uint8_t* points33,
    size_t n,
    uint8_t* out_result33);
 
/* ============================================================================
 * GPU error string extension
 * ============================================================================ */
 
UFSECP_API ufsecp_error_t ufsecp_gpu_frost_verify_partial_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* z_i32,
    const uint8_t* D_i33,
    const uint8_t* E_i33,
    const uint8_t* Y_i33,
    const uint8_t* rho_i32,
    const uint8_t* lambda_ie32,
    const uint8_t* negate_R,
    const uint8_t* negate_key,
    size_t count,
    uint8_t* out_results);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_ecrecover_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* msg_hashes32,
    const uint8_t* sigs64,
    const int*     recids,
    size_t count,
    uint8_t* out_pubkeys33,
    uint8_t* out_valid);
 
UFSECP_API const char* ufsecp_gpu_error_str(ufsecp_error_t err);
 
/* ============================================================================
 * ZK proof batch operations (GPU)
 * ============================================================================ */
 
UFSECP_API ufsecp_error_t ufsecp_gpu_zk_knowledge_verify_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* proofs64,
    const uint8_t* pubkeys65,
    const uint8_t* messages32,
    size_t count,
    uint8_t* out_results);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_zk_dleq_verify_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* proofs64,
    const uint8_t* G_pts65,
    const uint8_t* H_pts65,
    const uint8_t* P_pts65,
    const uint8_t* Q_pts65,
    size_t count,
    uint8_t* out_results);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_bulletproof_verify_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t* proofs324,
    const uint8_t* commitments65,
    const uint8_t* H_generator65,
    size_t count,
    uint8_t* out_results);
 
/* ============================================================================
 * BIP-324 transport batch operations (GPU)
 * ============================================================================ */
 
UFSECP_API ufsecp_error_t ufsecp_gpu_bip324_aead_encrypt_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t*  keys32,
    const uint8_t*  nonces12,
    const uint8_t*  plaintexts,
    const uint32_t* sizes,
    uint32_t max_payload,
    size_t count,
    uint8_t* wire_out);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_bip324_aead_decrypt_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t*  keys32,
    const uint8_t*  nonces12,
    const uint8_t*  wire_in,
    const uint32_t* sizes,
    uint32_t max_payload,
    size_t count,
    uint8_t*  plaintext_out,
    uint8_t*  out_valid);
 
/* -- ECDSA SNARK witness batch (eprint 2025/695) ------------------------------ */
 
#define UFSECP_ECDSA_SNARK_WITNESS_BYTES 760
 
UFSECP_API ufsecp_error_t ufsecp_gpu_zk_ecdsa_snark_witness_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t*  msg_hashes32,
    const uint8_t*  pubkeys33,
    const uint8_t*  sigs64,
    size_t          count,
    uint8_t*        out_witnesses);
 
/* -- BIP340 Schnorr SNARK witness batch --------------------------------------- */
 
#define UFSECP_SCHNORR_SNARK_WITNESS_BYTES 472
 
UFSECP_API ufsecp_error_t ufsecp_gpu_zk_schnorr_snark_witness_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t*  msgs32,
    const uint8_t*  pubkeys_x32,
    const uint8_t*  sigs64,
    size_t          count,
    uint8_t*        out_witnesses);
 
/* ============================================================================
 * BIP-352 Silent Payment scanning (GPU + CPU plan utility)
 * ============================================================================ */
 
#define UFSECP_BIP352_SCAN_PLAN_BYTES 264
 
UFSECP_API ufsecp_error_t ufsecp_bip352_prepare_scan_plan(
    const uint8_t scan_privkey32[32],
    uint8_t       plan264_out[264]);
 
UFSECP_API ufsecp_error_t ufsecp_gpu_bip352_scan_batch(
    ufsecp_gpu_ctx* ctx,
    const uint8_t   scan_privkey32[32],
    const uint8_t   spend_pubkey33[33],
    const uint8_t*  tweak_pubkeys33,
    size_t          n_tweaks,
    uint64_t*       prefix64_out);
 
#ifdef __cplusplus
}
#endif
 
#endif /* UFSECP_GPU_H */