api.hpp

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 <array>
#include <concepts>
#include <span>
#include <type_traits>
#include <utility>
 
#include "purify/bulletproof.hpp"
#include "purify/secret.hpp"
 
namespace purify {
 
struct GeneratedKey {
    SecretKey secret;
    UInt512 public_key;
};
 
using KeySeed = SpanAtLeast<16, const unsigned char>;
 
struct Bip340Key {
    Bip340Key() = default;
    Bip340Key(const Bip340Key&) = delete;
    Bip340Key& operator=(const Bip340Key&) = delete;
 
    Bip340Key(Bip340Key&& other) noexcept
        : seckey(other.seckey), xonly_pubkey(other.xonly_pubkey) {
        other.clear();
    }
 
    Bip340Key& operator=(Bip340Key&& other) noexcept {
        if (this != &other) {
            clear();
            seckey = other.seckey;
            xonly_pubkey = other.xonly_pubkey;
            other.clear();
        }
        return *this;
    }
 
    ~Bip340Key() {
        clear();
    }
 
    std::array<unsigned char, 32> seckey{};
    std::array<unsigned char, 32> xonly_pubkey{};
 
private:
    void clear() noexcept {
        detail::secure_clear_bytes(seckey.data(), seckey.size());
        xonly_pubkey.fill(0);
    }
};
 
struct BulletproofWitnessData {
    UInt512 public_key;
    FieldElement output;
    BulletproofAssignmentData assignment;
};
 
Result<GeneratedKey> derive_key(const SecretKey& secret);
 
Result<GeneratedKey> derive_key(SecretKey&& secret);
 
Result<Bip340Key> derive_bip340_key(const SecretKey& secret, purify_secp_context* secp_context);
 
inline UInt512 key_space_size() {
    return packed_secret_key_space_size();
}
 
template <typename FillRandom>
concept NoexceptByteFill = requires(FillRandom&& fill, std::span<unsigned char> bytes) {
    { std::forward<FillRandom>(fill)(bytes) } noexcept -> std::same_as<void>;
};
 
template <typename FillRandom>
concept NoexceptCheckedByteFill = requires(FillRandom&& fill, std::span<unsigned char> bytes) {
    { std::forward<FillRandom>(fill)(bytes) } noexcept -> std::same_as<Status>;
};
 
Status fill_secure_random(std::span<unsigned char> bytes) noexcept;
 
template <typename FillRandom>
requires NoexceptCheckedByteFill<FillRandom>
Result<UInt512> random_below(const UInt512& range, FillRandom&& fill_random) {
    if (range.is_zero()) {
        return unexpected_error(ErrorCode::RangeViolation, "random_below:zero_range");
    }
    std::size_t bits = range.bit_length();
    std::size_t bytes_needed = (bits + 7) / 8;
    std::array<unsigned char, 64> bytes{};
    std::span<unsigned char> out(bytes.data(), bytes_needed);
    while (true) {
        PURIFY_RETURN_IF_ERROR(std::forward<FillRandom>(fill_random)(out), "random_below:fill_random");
        UInt512 candidate = UInt512::from_bytes_be(bytes.data(), bytes_needed);
        candidate.mask_bits(bits);
        if (candidate.compare(range) < 0) {
            return candidate;
        }
    }
}
 
template <typename FillRandom>
requires NoexceptByteFill<FillRandom>
Result<UInt512> random_below(const UInt512& range, FillRandom&& fill_random) {
    if (range.is_zero()) {
        return unexpected_error(ErrorCode::RangeViolation, "random_below:zero_range");
    }
    std::size_t bits = range.bit_length();
    std::size_t bytes_needed = (bits + 7) / 8;
    std::array<unsigned char, 64> bytes{};
    std::span<unsigned char> out(bytes.data(), bytes_needed);
    while (true) {
        std::forward<FillRandom>(fill_random)(out);
        UInt512 candidate = UInt512::from_bytes_be(bytes.data(), bytes_needed);
        candidate.mask_bits(bits);
        if (candidate.compare(range) < 0) {
            return candidate;
        }
    }
}
 
Result<UInt512> random_below(const UInt512& range);
 
Result<GeneratedKey> generate_key();
 
Result<GeneratedKey> generate_key(KeySeed seed);
 
inline Result<GeneratedKey> generate_key(std::span<const unsigned char> seed) {
    PURIFY_ASSIGN_OR_RETURN(auto checked, KeySeed::try_from(seed), "generate_key:seed_too_short");
    return generate_key(checked);
}
 
template <typename FillRandom>
requires(NoexceptByteFill<FillRandom> || NoexceptCheckedByteFill<FillRandom>)
Result<GeneratedKey> generate_key(FillRandom&& fill_random) {
    PURIFY_ASSIGN_OR_RETURN(const auto& secret, random_below(key_space_size(), std::forward<FillRandom>(fill_random)),
                            "generate_key:random_below_custom");
    PURIFY_ASSIGN_OR_RETURN(auto owned_secret, SecretKey::from_packed(secret), "generate_key:from_packed_secret");
    return derive_key(std::move(owned_secret));
}
 
Result<FieldElement> eval(const SecretKey& secret, const Bytes& message);
 
Result<std::string> verifier(const Bytes& message, const UInt512& pubkey);
 
Result<NativeBulletproofCircuit> verifier_circuit(const Bytes& message, const UInt512& pubkey);
 
Result<BulletproofWitnessData> prove_assignment_data(const Bytes& message, const SecretKey& secret);
 
Result<bool> evaluate_verifier_circuit(const Bytes& message, const BulletproofWitnessData& witness);
 
Result<bool> evaluate_verifier_circuit(const Bytes& message, const SecretKey& secret);
 
Result<Bytes> prove_assignment(const Bytes& message, const SecretKey& secret);
 
}  // namespace purify