purify
C++ Purify implementation with native circuit and BPP support
Loading...
Searching...
No Matches
construction_receipt.cpp
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
8
9#include <algorithm>
10#include <array>
11#include <cassert>
12#include <limits>
13#include <utility>
14#include <vector>
15
16#include "purify/curve.hpp"
17
18namespace purify::accountable {
19namespace {
20
21const TaggedHash kConstructionReceiptStatementHash(
22 "Purify/Accountable/ConstructionReceiptStatement/v5");
23
24Status validate_ciphertext(const AnchorEscrowCiphertext& ciphertext) {
25 return validate_public_points(ciphertext.ephemeral_key);
26}
27
28Status validate_circuit_precommitment(
29 const bppp::ScalarBytes& circuit_precommitment) {
31 const auto& scalar,
32 FieldElement::try_from_bytes32(circuit_precommitment),
33 "construction_receipt:circuit_precommitment");
34 if (scalar.is_zero()) {
35 return unexpected_error(
37 "construction_receipt:circuit_precommitment_zero");
38 }
39 return {};
40}
41
42Status validate_anchor_entries(
43 std::span<const ConstructionReceiptAnchorEntry> entries) {
44 if (entries.empty()) {
46 "construction_receipt:anchor_entries");
47 }
48 if (!size_fits_u32(entries.size())) {
50 "construction_receipt:anchor_count");
51 }
52 for (const ConstructionReceiptAnchorEntry& entry : entries) {
53 PURIFY_RETURN_IF_ERROR(validate_ciphertext(entry.ciphertext),
54 "construction_receipt:ciphertext");
56 validate_circuit_precommitment(
57 entry.circuit_precommitment),
58 "construction_receipt:circuit_precommitment");
59 }
60 return {};
61}
62
63Status validate_setup_entries(
64 const UInt512& recovery_root,
65 std::span<const ConstructionReceiptSetupEntry> entries) {
66 if (entries.empty()) {
68 "construction_receipt:setup_entries");
69 }
70 if (!size_fits_u32(entries.size())) {
72 "construction_receipt:setup_count");
73 }
74 std::vector<RecoveryRootShare> shares;
75 shares.reserve(entries.size());
76 for (const ConstructionReceiptSetupEntry& entry : entries) {
78 validate_circuit_precommitment(
79 entry.circuit_precommitment),
80 "construction_receipt:setup_precommitment");
81 shares.push_back(entry.share);
82 }
84 const auto aggregate,
86 "construction_receipt:setup_aggregate");
87 if (aggregate.recovery_root() != recovery_root) {
88 return unexpected_error(
90 "construction_receipt:setup_recovery_root");
91 }
92 return {};
93}
94
95void append_u32_be(Bytes& out, std::uint32_t value) {
96 out.push_back(static_cast<unsigned char>((value >> 24) & 0xffU));
97 out.push_back(static_cast<unsigned char>((value >> 16) & 0xffU));
98 out.push_back(static_cast<unsigned char>((value >> 8) & 0xffU));
99 out.push_back(static_cast<unsigned char>(value & 0xffU));
100}
101
102std::uint32_t read_u32_be(std::span<const unsigned char, 4> encoded) {
103 return (static_cast<std::uint32_t>(encoded[0]) << 24) |
104 (static_cast<std::uint32_t>(encoded[1]) << 16) |
105 (static_cast<std::uint32_t>(encoded[2]) << 8) |
106 static_cast<std::uint32_t>(encoded[3]);
107}
108
109template <std::size_t Size>
110void append_array(Bytes& out, const std::array<unsigned char, Size>& value) {
111 out.insert(out.end(), value.begin(), value.end());
112}
113
114void append_ciphertext(Bytes& out,
115 const AnchorEscrowCiphertext& ciphertext) {
116 append_array(out, ciphertext.ephemeral_key.to_bytes_be());
117 append_array(out, ciphertext.masked_scalar.to_bytes_be());
118}
119
120Result<AnchorEscrowCiphertext> parse_ciphertext(
121 std::span<const unsigned char, AnchorEscrowCiphertext::kSerializedSize>
122 encoded) {
123 AnchorEscrowCiphertext ciphertext;
124 std::size_t offset = 0;
125 ciphertext.ephemeral_key =
126 UInt512::from_bytes_be(encoded.data() + offset, 64);
127 offset += 64;
128 std::array<unsigned char, 32> encoded_scalar{};
129 std::copy_n(encoded.data() + offset,
130 encoded_scalar.size(), encoded_scalar.begin());
132 ciphertext.masked_scalar,
133 FieldElement::try_from_bytes32(encoded_scalar),
134 "construction_receipt:masked_scalar");
135 offset += 32;
136 assert(offset == encoded.size());
137 PURIFY_RETURN_IF_ERROR(validate_ciphertext(ciphertext),
138 "construction_receipt:ciphertext");
139 return ciphertext;
140}
141
142Result<std::size_t> encoded_size_for_counts(
143 std::size_t setup_count, std::size_t anchor_count) {
144 std::size_t entry_count = 0;
145 if (!size_fits_u32(setup_count) ||
146 !size_fits_u32(anchor_count) ||
147 !checked_add_size(setup_count, anchor_count, entry_count) ||
148 !size_fits_u32(entry_count)) {
150 "construction_receipt:entry_count");
151 }
152 std::size_t setup_size = 0;
153 std::size_t anchor_size = 0;
154 std::size_t entries_size = 0;
155 std::size_t encoded_size = 0;
156 if (!checked_mul_size(
157 setup_count,
159 setup_size) ||
161 anchor_count,
163 anchor_size) ||
164 !checked_add_size(setup_size, anchor_size, entries_size) ||
166 entries_size,
167 encoded_size)) {
169 "construction_receipt:encoded_size");
170 }
171 return encoded_size;
172}
173
174} // namespace
175
179 if (std::all_of(digest.begin(), digest.end(),
180 [](unsigned char byte) { return byte == 0; })) {
181 return unexpected_error(
183 "construction_receipt:resolved_setup_digest_zero");
184 }
185 return ResolvedConstructionSetupDigest(digest);
186}
187
190 std::vector<ConstructionReceiptSetupEntry> setup_entries,
191 std::vector<ConstructionReceiptAnchorEntry> anchor_entries) {
194 "construction_receipt:recovery_root");
196 const auto encoded_size,
197 encoded_size_for_counts(setup_entries.size(),
198 anchor_entries.size()),
199 "construction_receipt:encoded_size");
200 (void)encoded_size;
202 validate_setup_entries(recovery_root, setup_entries),
203 "construction_receipt:setup_entries");
205 validate_anchor_entries(anchor_entries),
206 "construction_receipt:anchor_entries");
207 return ConstructionReceiptPayload(
208 recovery_root, std::move(setup_entries),
209 std::move(anchor_entries));
210}
211
213 Bytes encoded;
214 encoded.reserve(serialized_size());
215 encoded.push_back(kSerializationVersion);
216 append_array(encoded, recovery_root_.to_bytes_be());
217 assert(size_fits_u32(setup_entries_.size()));
218 assert(size_fits_u32(anchor_entries_.size()));
219 append_u32_be(
220 encoded, static_cast<std::uint32_t>(setup_entries_.size()));
221 append_u32_be(
222 encoded, static_cast<std::uint32_t>(anchor_entries_.size()));
223 for (const ConstructionReceiptSetupEntry& entry : setup_entries_) {
224 const auto share = entry.share.serialize();
225 encoded.insert(encoded.end(), share.begin(), share.end());
226 append_array(encoded, entry.circuit_precommitment);
227 }
228 for (const ConstructionReceiptAnchorEntry& entry : anchor_entries_) {
229 append_ciphertext(encoded, entry.ciphertext);
230 append_array(encoded, entry.circuit_precommitment);
231 }
232 assert(encoded.size() == serialized_size());
233 return encoded;
234}
235
237 std::span<const unsigned char> encoded) {
238 if (encoded.size() < kFixedHeaderSize) {
240 "construction_receipt:header");
241 }
242 if (encoded[0] != kSerializationVersion) {
244 "construction_receipt:version");
245 }
246
247 std::size_t offset = 1;
249 UInt512::from_bytes_be(encoded.data() + offset, 64);
250 offset += 64;
253 "construction_receipt:recovery_root");
254
255 const std::span<const unsigned char, 4> encoded_setup_count(
256 encoded.data() + offset, 4);
257 const std::uint32_t setup_count =
258 read_u32_be(encoded_setup_count);
259 offset += 4;
260 const std::span<const unsigned char, 4> encoded_anchor_count(
261 encoded.data() + offset, 4);
262 const std::uint32_t anchor_count =
263 read_u32_be(encoded_anchor_count);
264 offset += 4;
265 if (setup_count == 0 || anchor_count == 0) {
267 "construction_receipt:entry_count");
268 }
270 const std::size_t expected_size,
271 encoded_size_for_counts(
272 static_cast<std::size_t>(setup_count),
273 static_cast<std::size_t>(anchor_count)),
274 "construction_receipt:encoded_size");
275 if (encoded.size() != expected_size) {
277 "construction_receipt:encoded_size");
278 }
279
280 std::vector<ConstructionReceiptSetupEntry> setup_entries;
281 setup_entries.reserve(setup_count);
282 for (std::uint32_t i = 0; i < setup_count; ++i) {
284 auto share,
286 encoded.subspan(offset,
288 "construction_receipt:setup_share");
290 bppp::ScalarBytes precommitment{};
291 std::copy_n(encoded.begin() + offset,
292 precommitment.size(), precommitment.begin());
293 offset += precommitment.size();
295 validate_circuit_precommitment(precommitment),
296 "construction_receipt:setup_precommitment");
297 setup_entries.emplace_back(std::move(share), precommitment);
298 }
299
300 std::vector<ConstructionReceiptAnchorEntry> anchor_entries;
301 anchor_entries.reserve(anchor_count);
302 for (std::uint32_t i = 0; i < anchor_count; ++i) {
304 const std::span<const unsigned char,
306 encoded_ciphertext(encoded.data() + offset,
309 parse_ciphertext(encoded_ciphertext),
310 "construction_receipt:ciphertext");
312 std::copy_n(
313 encoded.begin() + offset,
314 entry.circuit_precommitment.size(),
315 entry.circuit_precommitment.begin());
316 offset += entry.circuit_precommitment.size();
318 validate_circuit_precommitment(
320 "construction_receipt:circuit_precommitment");
321 anchor_entries.push_back(std::move(entry));
322 }
323 assert(offset == encoded.size());
325 validate_setup_entries(recovery_root, setup_entries),
326 "construction_receipt:setup_entries");
328 validate_anchor_entries(anchor_entries),
329 "construction_receipt:anchor_entries");
330 return ConstructionReceiptPayload(
331 recovery_root, std::move(setup_entries),
332 std::move(anchor_entries));
333}
334
337 const ConstructionReceiptPayload& payload,
338 const ResolvedConstructionSetupDigest& resolved_setup,
339 std::span<const ResolvedConstructionReceiptEntry> resolved_entries) {
340 if (resolved_entries.size() != payload.anchor_entries().size()) {
342 "construction_receipt:resolved_count");
343 }
344
345 Bytes statement = payload.serialize();
346 statement.reserve(statement.size() +
348 resolved_entries.size() * (32 + 64 + 33 + 32));
349 append_array(statement, resolved_setup.bytes());
350 for (std::size_t i = 0; i < resolved_entries.size(); ++i) {
351 const ResolvedConstructionReceiptEntry& resolved =
352 resolved_entries[i];
353 for (std::size_t prior = 0; prior < i; ++prior) {
354 if (resolved_entries[prior].anchor_reference ==
355 resolved.anchor_reference) {
356 return unexpected_error(
358 "construction_receipt:duplicate_anchor_reference");
359 }
360 if (resolved_entries[prior].anchor_root ==
361 resolved.anchor_root) {
362 return unexpected_error(
364 "construction_receipt:duplicate_anchor_root");
365 }
366 if (resolved_entries[prior].punishment_key ==
367 resolved.punishment_key) {
368 return unexpected_error(
370 "construction_receipt:duplicate_punishment_key");
371 }
372 }
375 "construction_receipt:anchor_root");
376 append_array(statement, resolved.anchor_reference);
377 append_array(statement, resolved.anchor_root.to_bytes_be());
378 std::array<unsigned char, 33> punishment{};
379 punishment[0] = 0x02;
380 std::copy(resolved.punishment_key.xonly().begin(),
381 resolved.punishment_key.xonly().end(),
382 punishment.begin() + 1);
383 append_array(statement, punishment);
384 append_array(statement, resolved.context_digest);
385 }
386 return kConstructionReceiptStatementHash.digest(statement);
387}
388
389} // namespace purify::accountable
390
391namespace purify::accountable {
392
393Result<ConstructionReceiptAccumulator>
395 purify_secp_context* secp_context) {
398 "construction_accumulation:leaf_basis");
399 return ConstructionReceiptAccumulator(std::move(leaves));
400}
401
408 if (roster.members().empty() ||
409 !size_fits_u32(roster.members().size())) {
410 return unexpected_error(
412 "construction_setup:roster_count");
413 }
416 "construction_setup:recovery_root");
417 if (formation.core_digest() != roster.coalition_core_digest()) {
418 return unexpected_error(
420 "construction_setup:formation_core");
421 }
423 std::move(roster), std::move(formation), recovery_root,
424 std::move(resolved_digest));
425}
426
430 if (parent_proof.size() != kParentProofSize) {
432 "construction_envelope:parent_proof");
433 }
434 return ConstructionReceiptEnvelope(std::move(payload),
435 std::move(parent_proof));
436}
437
440 std::span<const unsigned char> encoded) {
441 constexpr std::size_t minimum_size =
444 if (encoded.size() < minimum_size) {
446 "construction_envelope:encoded_size");
447 }
448 const std::size_t payload_size =
449 encoded.size() - kParentProofSize;
451 auto payload,
453 encoded.first(payload_size)),
454 "construction_envelope:payload");
455 Bytes parent_proof(encoded.begin() + payload_size, encoded.end());
456 return create(std::move(payload), std::move(parent_proof));
457}
458
460 Bytes encoded = payload_.serialize();
461 encoded.reserve(serialized_size());
462 encoded.insert(encoded.end(), parent_proof_.begin(),
463 parent_proof_.end());
464 assert(encoded.size() == serialized_size());
465 return encoded;
466}
467
469 return payload_.serialized_size() + parent_proof_.size();
470}
471
472} // namespace purify::accountable
static Result< FieldElement > try_from_bytes32(const std::array< unsigned char, 32 > &bytes)
Decodes a canonical 32-byte big-endian field element.
Definition numeric.cpp:53
const std::array< unsigned char, 32 > & xonly() const noexcept
static Result< ConstructionLeafAccumulator > create(purify_secp_context *secp_context)
ConstructionReceiptAccumulator(const ConstructionReceiptAccumulator &)=delete
const ConstructionLeafAccumulator & leaves() const noexcept
static Result< ConstructionReceiptAccumulator > create(purify_secp_context *secp_context)
static Result< ConstructionReceiptEnvelope > create(ConstructionReceiptPayload payload, Bytes parent_proof)
static Result< ConstructionReceiptEnvelope > deserialize(std::span< const unsigned char > encoded)
const ConstructionReceiptPayload & payload() const noexcept
Canonical public payload for a coalition construction receipt.
std::span< const ConstructionReceiptSetupEntry > setup_entries() const noexcept
std::span< const ConstructionReceiptAnchorEntry > anchor_entries() const noexcept
static Result< ConstructionReceiptPayload > create(UInt512 recovery_root, std::vector< ConstructionReceiptSetupEntry > setup_entries, std::vector< ConstructionReceiptAnchorEntry > anchor_entries)
static Result< ConstructionReceiptPayload > deserialize(std::span< const unsigned char > encoded)
An ordered signing roster bound to one core and nonce-host list.
static Result< RecoveryRootShare > deserialize(std::span< const unsigned char > encoded)
static constexpr std::size_t kSerializedSize
Immutable registry-record digest selected by a recovery root.
static Result< ResolvedConstructionSetupDigest > create(const ResolvedConstructionSetupDigestBytes &digest)
const ResolvedConstructionSetupDigestBytes & bytes() const noexcept
static Result< ResolvedConstructionSetup > create(NonceHostBoundSigningRoster roster, CoalitionFormation formation, UInt512 recovery_root, ResolvedConstructionSetupDigest resolved_digest)
ResolvedConstructionSetup(const ResolvedConstructionSetup &)=delete
const ResolvedConstructionSetupDigest & resolved_digest() const noexcept
const NonceHostBoundSigningRoster & roster() const noexcept
Canonical public statement for a coalition construction receipt.
Canonical transport for a construction receipt parent proof.
Elliptic-curve helpers, fixed parameters, and hash-to-curve utilities for Purify.
#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
std::array< unsigned char, 32 > ResolvedConstructionSetupDigestBytes
Result< RecoveryRootShareAggregate > aggregate_recovery_root_shares(std::span< const RecoveryRootShare > ordered_shares)
Result< ConstructionReceiptStatementDigest > construction_receipt_statement_digest(const ConstructionReceiptPayload &payload, const ResolvedConstructionSetupDigest &resolved_setup, std::span< const ResolvedConstructionReceiptEntry > resolved_entries)
Bind a canonical payload to its ordered, resolved anchor inputs.
std::array< unsigned char, 32 > ScalarBytes
Big-endian 32-byte scalar encoding.
Definition bppp.hpp:30
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
BigUInt< 8 > UInt512
512-bit unsigned integer used for private and packed public keys.
Definition numeric.hpp:821
bool checked_mul_size(std::size_t lhs, std::size_t rhs, std::size_t &out) noexcept
Definition common.hpp:71
Expected< T, Error > Result
Expected-returning convenience alias for Purify value-producing APIs.
Definition error.hpp:99
Expected< void, Error > Status
Expected-returning convenience alias for Purify status-only APIs.
Definition error.hpp:102
std::vector< unsigned char > Bytes
Dynamically sized byte string used for messages, serialized witnesses, and proofs.
Definition common.hpp:99
bool size_fits_u32(std::size_t value) noexcept
Definition common.hpp:79
bool checked_add_size(std::size_t lhs, std::size_t rhs, std::size_t &out) noexcept
Definition common.hpp:63
Status validate_public_points(const UInt512 &packed)
Validates both curve points in a packed public key.
Definition curve.cpp:393
static BigUInt from_bytes_be(const unsigned char *data, std::size_t size)
Definition numeric.hpp:238
std::array< unsigned char, Words *8 > to_bytes_be() const
Serializes the value to a fixed-width big-endian byte array.
Definition numeric.hpp:640
static constexpr std::size_t kSerializedSize
Registry-resolved public inputs for one ordered anchor entry.