purify
C++ Purify implementation with native circuit and BPP support
Loading...
Searching...
No Matches
api.hpp
Go to the documentation of this file.
1// Copyright (c) 2026 Judica, Inc.
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or https://opensource.org/license/mit/.
4
9
10#pragma once
11
12#include <array>
13#include <concepts>
14#include <span>
15#include <type_traits>
16#include <utility>
17
19#include "purify/secret.hpp"
20
21namespace purify {
22
28
31
38struct Bip340Key {
39 Bip340Key() = default;
40 Bip340Key(const Bip340Key&) = delete;
41 Bip340Key& operator=(const Bip340Key&) = delete;
42
43 Bip340Key(Bip340Key&& other) noexcept
44 : seckey(other.seckey), xonly_pubkey(other.xonly_pubkey) {
45 other.clear();
46 }
47
48 Bip340Key& operator=(Bip340Key&& other) noexcept {
49 if (this != &other) {
50 clear();
51 seckey = other.seckey;
52 xonly_pubkey = other.xonly_pubkey;
53 other.clear();
54 }
55 return *this;
56 }
57
59 clear();
60 }
61
62 std::array<unsigned char, 32> seckey{};
63 std::array<unsigned char, 32> xonly_pubkey{};
64
65private:
66 void clear() noexcept {
68 xonly_pubkey.fill(0);
69 }
70};
71
75 FieldElement output_value,
76 BulletproofAssignmentData assignment_value)
77 : public_key(std::move(public_key_value)), output(output_value),
78 assignment(std::move(assignment_value)) {}
79
82
84 : public_key(std::move(other.public_key)), output(other.output),
85 assignment(std::move(other.assignment)) {
86 detail::secure_clear_bytes(&other.output, sizeof(other.output));
87 }
88
90 if (this != &other) {
92 public_key = std::move(other.public_key);
93 output = other.output;
94 assignment = std::move(other.assignment);
95 detail::secure_clear_bytes(&other.output, sizeof(other.output));
96 }
97 return *this;
98 }
99
103
107};
108
115
122
129
134
136template <typename FillRandom>
137concept NoexceptByteFill = requires(FillRandom&& fill, std::span<unsigned char> bytes) {
138 { std::forward<FillRandom>(fill)(bytes) } noexcept -> std::same_as<void>;
139};
140
142template <typename FillRandom>
143concept NoexceptCheckedByteFill = requires(FillRandom&& fill, std::span<unsigned char> bytes) {
144 { std::forward<FillRandom>(fill)(bytes) } noexcept -> std::same_as<Status>;
145};
146
152Status fill_secure_random(std::span<unsigned char> bytes) noexcept;
153
160template <typename FillRandom>
162Result<UInt512> random_below(const UInt512& range, FillRandom&& fill_random) {
163 if (range.is_zero()) {
164 return unexpected_error(ErrorCode::RangeViolation, "random_below:zero_range");
165 }
166 std::size_t bits = range.bit_length();
167 std::size_t bytes_needed = (bits + 7) / 8;
168 std::array<unsigned char, 64> bytes{};
169 std::span<unsigned char> out(bytes.data(), bytes_needed);
170 while (true) {
171 PURIFY_RETURN_IF_ERROR(std::forward<FillRandom>(fill_random)(out), "random_below:fill_random");
172 UInt512 candidate = UInt512::from_bytes_be(bytes.data(), bytes_needed);
173 candidate.mask_bits(bits);
174 if (candidate.compare(range) < 0) {
175 return candidate;
176 }
177 }
178}
179
186template <typename FillRandom>
187requires NoexceptByteFill<FillRandom>
188Result<UInt512> random_below(const UInt512& range, FillRandom&& fill_random) {
189 if (range.is_zero()) {
190 return unexpected_error(ErrorCode::RangeViolation, "random_below:zero_range");
191 }
192 std::size_t bits = range.bit_length();
193 std::size_t bytes_needed = (bits + 7) / 8;
194 std::array<unsigned char, 64> bytes{};
195 std::span<unsigned char> out(bytes.data(), bytes_needed);
196 while (true) {
197 std::forward<FillRandom>(fill_random)(out);
198 UInt512 candidate = UInt512::from_bytes_be(bytes.data(), bytes_needed);
199 candidate.mask_bits(bits);
200 if (candidate.compare(range) < 0) {
201 return candidate;
202 }
203 }
204}
205
212
218
225
231inline Result<GeneratedKey> generate_key(std::span<const unsigned char> seed) {
232 PURIFY_ASSIGN_OR_RETURN(auto checked, KeySeed::try_from(seed), "generate_key:seed_too_short");
233 return generate_key(checked);
234}
235
241template <typename FillRandom>
242requires(NoexceptByteFill<FillRandom> || NoexceptCheckedByteFill<FillRandom>)
243Result<GeneratedKey> generate_key(FillRandom&& fill_random) {
244 PURIFY_ASSIGN_OR_RETURN(const auto& secret, random_below(key_space_size(), std::forward<FillRandom>(fill_random)),
245 "generate_key:random_below_custom");
246 PURIFY_ASSIGN_OR_RETURN(auto owned_secret, SecretKey::from_packed(secret), "generate_key:from_packed_secret");
247 return derive_key(std::move(owned_secret));
248}
249
256Result<FieldElement> eval(const SecretKey& secret, const Bytes& message);
257
264Result<std::string> verifier(const Bytes& message, const UInt512& pubkey);
265
273
280Result<BulletproofWitnessData> prove_assignment_data(const Bytes& message, const SecretKey& secret);
281
288Result<bool> evaluate_verifier_circuit(const Bytes& message, const BulletproofWitnessData& witness);
289
296Result<bool> evaluate_verifier_circuit(const Bytes& message, const SecretKey& secret);
297
304Result<Bytes> prove_assignment(const Bytes& message, const SecretKey& secret);
305
306} // namespace purify
Native Bulletproof-style circuit types and witness serialization helpers.
Field element modulo the backend scalar field used by this implementation.
Definition numeric.hpp:834
Move-only packed Purify secret stored in dedicated heap memory.
Definition secret.hpp:95
static Result< SecretKey > from_packed(const UInt512 &packed)
Constructs a validated secret key from packed Purify secret bytes.
Definition secret.hpp:109
Checked span wrapper that guarantees a minimum runtime length.
Definition common.hpp:129
static Result< SpanAtLeast > try_from(std::span< const unsigned char > span)
Definition common.hpp:138
Callable concept for byte-fill RNG adapters that cannot fail.
Definition api.hpp:137
Callable concept for byte-fill RNG adapters that report failure via Status.
Definition api.hpp:143
#define PURIFY_RETURN_IF_ERROR(expr, context)
Evaluates an expected-like expression and returns the wrapped error on failure.
Definition error.hpp:329
#define PURIFY_ASSIGN_OR_RETURN(lhs, expr, context)
Evaluates an expected-like expression, binds the value to lhs, and propagates errors.
Definition error.hpp:338
void secure_clear_bytes(void *data, std::size_t size) noexcept
Definition secret.hpp:22
constexpr Unexpected< Error > unexpected_error(ErrorCode code, const char *context=nullptr)
Constructs an unexpected Error value from a machine-readable code.
Definition error.hpp:293
Result< std::string > verifier(const Bytes &message, const UInt512 &pubkey)
Builds the legacy serialized verifier description for a message and public key.
Definition api.cpp:197
BigUInt< 8 > UInt512
512-bit unsigned integer used for private and packed public keys.
Definition numeric.hpp:821
Result< BulletproofWitnessData > prove_assignment_data(const Bytes &message, const SecretKey &secret)
Computes the native Purify witness for a message and secret.
Definition api.cpp:243
Result< GeneratedKey > generate_key()
Generates a random Purify keypair using the built-in OS RNG.
Definition api.cpp:117
Result< NativeBulletproofCircuit > verifier_circuit(const Bytes &message, const UInt512 &pubkey)
Builds the native verifier circuit for a message and public key.
Definition api.cpp:211
Result< Bip340Key > derive_bip340_key(const SecretKey &secret, purify_secp_context *secp_context)
Derives a canonical BIP340 signing keypair from an owned Purify secret.
Definition api.cpp:166
Result< Bytes > prove_assignment(const Bytes &message, const SecretKey &secret)
Serializes the witness assignment produced for a message and secret.
Definition api.cpp:301
Result< GeneratedKey > derive_key(const SecretKey &secret)
Derives the packed public key corresponding to a packed secret.
Definition api.cpp:147
Expected< T, Error > Result
Expected-returning convenience alias for Purify value-producing APIs.
Definition error.hpp:99
const UInt512 & packed_secret_key_space_size()
Returns the size of the packed secret-key encoding space.
Definition curve.cpp:229
UInt512 key_space_size()
Returns the size of the packed Purify secret-key space.
Definition api.hpp:131
Result< FieldElement > eval(const SecretKey &secret, const Bytes &message)
Evaluates the Purify PRF for an owned secret key and message.
Definition api.cpp:182
Result< bool > evaluate_verifier_circuit(const Bytes &message, const BulletproofWitnessData &witness)
Evaluates the generated verifier circuit against an explicit witness.
Definition api.cpp:289
Expected< void, Error > Status
Expected-returning convenience alias for Purify status-only APIs.
Definition error.hpp:102
Result< UInt512 > random_below(const UInt512 &range, FillRandom &&fill_random)
Samples a uniformly random packed secret below a range using a checked byte-fill source.
Definition api.hpp:162
std::vector< unsigned char > Bytes
Dynamically sized byte string used for messages, serialized witnesses, and proofs.
Definition common.hpp:99
Status fill_secure_random(std::span< unsigned char > bytes) noexcept
Fills a buffer with operating-system randomness.
Definition api.cpp:108
SpanAtLeast< 16, const unsigned char > KeySeed
Minimum-length checked wrapper for deterministic key-generation seed material.
Definition api.hpp:30
Secret-owning Purify key material wrappers.
std::size_t bit_length() const
Returns the index of the highest set bit plus one.
Definition numeric.hpp:493
static BigUInt from_bytes_be(const unsigned char *data, std::size_t size)
Definition numeric.hpp:238
bool is_zero() const
Returns true when all limbs are zero.
Definition numeric.hpp:290
int compare(const BigUInt &other) const
Compares two fixed-width integers using unsigned ordering.
Definition numeric.hpp:304
void mask_bits(std::size_t bits)
Clears all bits above the requested width.
Definition numeric.hpp:605
Bip340Key(const Bip340Key &)=delete
Bip340Key & operator=(Bip340Key &&other) noexcept
Definition api.hpp:48
std::array< unsigned char, 32 > seckey
Definition api.hpp:62
Bip340Key & operator=(const Bip340Key &)=delete
Bip340Key()=default
std::array< unsigned char, 32 > xonly_pubkey
Definition api.hpp:63
Bip340Key(Bip340Key &&other) noexcept
Definition api.hpp:43
Columnar witness assignment compatible with the native Bulletproof circuit layout.
BulletproofWitnessData & operator=(const BulletproofWitnessData &)=default
BulletproofWitnessData(BulletproofWitnessData &&other) noexcept
Definition api.hpp:83
BulletproofAssignmentData assignment
Definition api.hpp:106
BulletproofWitnessData(UInt512 public_key_value, FieldElement output_value, BulletproofAssignmentData assignment_value)
Definition api.hpp:74
BulletproofWitnessData & operator=(BulletproofWitnessData &&other) noexcept
Definition api.hpp:89
BulletproofWitnessData(const BulletproofWitnessData &)=default
Derived Purify keypair bundle with an owned packed secret and its matching public key.
Definition api.hpp:24
UInt512 public_key
Definition api.hpp:26
SecretKey secret
Definition api.hpp:25