purify.h

Go to the documentation of this file.

// Copyright (c) 2026 Judica, Inc.
// Distributed under the MIT software license, see the accompanying
// file COPYING or https://opensource.org/license/mit/.
 
#pragma once
 
#include <stddef.h>
#include <stdint.h>
 
#include "purify/secp_context.h"
 
#define PURIFY_SECRET_KEY_BYTES 64u
#define PURIFY_PUBLIC_KEY_BYTES 64u
#define PURIFY_FIELD_ELEMENT_BYTES 32u
#define PURIFY_BIP340_SECRET_KEY_BYTES 32u
#define PURIFY_BIP340_XONLY_PUBKEY_BYTES 32u
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum purify_error_code {
    PURIFY_ERROR_OK = 0,
    PURIFY_ERROR_INVALID_HEX,
    PURIFY_ERROR_INVALID_HEX_LENGTH,
    PURIFY_ERROR_INVALID_FIXED_SIZE,
    PURIFY_ERROR_OVERFLOW,
    PURIFY_ERROR_UNDERFLOW,
    PURIFY_ERROR_NARROWING_OVERFLOW,
    PURIFY_ERROR_DIVISION_BY_ZERO,
    PURIFY_ERROR_BIT_INDEX_OUT_OF_RANGE,
    PURIFY_ERROR_RANGE_VIOLATION,
    PURIFY_ERROR_EMPTY_INPUT,
    PURIFY_ERROR_SIZE_MISMATCH,
    PURIFY_ERROR_MISSING_VALUE,
    PURIFY_ERROR_INVALID_SYMBOL,
    PURIFY_ERROR_UNSUPPORTED_SYMBOL,
    PURIFY_ERROR_UNINITIALIZED_STATE,
    PURIFY_ERROR_INDEX_OUT_OF_RANGE,
    PURIFY_ERROR_INVALID_DIMENSIONS,
    PURIFY_ERROR_NON_BOOLEAN_VALUE,
    PURIFY_ERROR_EQUATION_MISMATCH,
    PURIFY_ERROR_BINDING_MISMATCH,
    PURIFY_ERROR_IO_OPEN_FAILED,
    PURIFY_ERROR_IO_WRITE_FAILED,
    PURIFY_ERROR_ENTROPY_UNAVAILABLE,
    PURIFY_ERROR_BACKEND_REJECTED_INPUT,
    PURIFY_ERROR_HASH_TO_CURVE_EXHAUSTED,
    PURIFY_ERROR_UNEXPECTED_SIZE,
    PURIFY_ERROR_GENERATOR_ORDER_CHECK_FAILED,
    PURIFY_ERROR_INTERNAL_MISMATCH,
    PURIFY_ERROR_TRANSCRIPT_CHECK_FAILED,
} purify_error_code;
 
typedef struct purify_generated_key {
    unsigned char secret_key[PURIFY_SECRET_KEY_BYTES];
    unsigned char public_key[PURIFY_PUBLIC_KEY_BYTES];
} purify_generated_key;
 
typedef struct purify_bip340_key {
    unsigned char secret_key[PURIFY_BIP340_SECRET_KEY_BYTES];
    unsigned char xonly_public_key[PURIFY_BIP340_XONLY_PUBKEY_BYTES];
} purify_bip340_key;
 
const char* purify_error_name(purify_error_code code);
 
const char* purify_error_message(purify_error_code code);
 
purify_error_code purify_fill_secure_random(unsigned char* bytes, size_t bytes_len);
 
purify_error_code purify_validate_secret_key(const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES]);
 
purify_error_code purify_validate_public_key(const unsigned char public_key[PURIFY_PUBLIC_KEY_BYTES]);
 
purify_error_code purify_generate_key(purify_generated_key* out);
 
purify_error_code purify_generate_key_from_seed(purify_generated_key* out, const unsigned char* seed, size_t seed_len);
 
purify_error_code purify_derive_public_key(unsigned char out_public_key[PURIFY_PUBLIC_KEY_BYTES],
                                           const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES]);
 
purify_error_code purify_derive_bip340_key(purify_bip340_key* out,
                                           const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES],
                                           purify_secp_context* secp_context);
 
purify_error_code purify_eval(unsigned char out_field_element[PURIFY_FIELD_ELEMENT_BYTES],
                              const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES],
                              const unsigned char* message,
                              size_t message_len);
 
#ifdef __cplusplus
}
#endif