FlatBuffer schemas

// proof.fbs
// FlatBuffers schema for PoW proof with C++ and Python compatibility
namespace proof;

// Wrapper for 1D float arrays (for 2D tensors)
table FloatArray {
  values:[float];      // float32 vector
}

// Wrapper for 1D uint arrays
table UIntArray {
  values:[uint32];     // uint32 vector
}

// Root table representing a single proof
table Proof {
  version:uint8;                 // schema version identifier
  tick:uint64;                 // monotonic tick count
  timestamp:uint64;            // UNIX timestamp

  // Binary fields as raw bytes (more compact than hex strings)
  target:[ubyte];              // target bytes
  vdf:[ubyte];                 // VDF output bytes
  hash:[ubyte];                // proof hash bytes
  block_hash:[ubyte];                // prior block hash bytes
  header_prefix:[ubyte];       // optional, if provided

  is_solution:bool;
  model_identifier : string;    // e.g. "gpt-4"
  compute_precision: string;    // e.g. "fp16"
  ipfs_cid         : string;    // e.g. "cdcdcd"
  extra_flags      : string;    // e.g. ""
  temperature      : float;     // sampling temperature
  top_p            : float;     // nucleus‐sampling p
  top_k            : uint32;    // top‐k sampling
  repetition_penalty: float;    // repetition penalty
  
  // 1D arrays
  chosen_tokens:[uint32];      // selected token IDs
  chosen_probs:[float];        // probabilities
  sampling_u:[float];          // random sampling values
  softmax_normalizers:[float]; // softmax normalizers
  prompt_tokens:[uint32];      // prompt token IDs
  pad_mask:[bool];           // pad mask (0/1)

  // 2D tensors implemented via wrapper tables
  topk_logits:[FloatArray];    // vector of FloatArray
  topk_indices:[UIntArray];    // vector of UIntArray
  logsumexp_stats:[FloatArray]; // vector of FloatArray (2D tensor)
}

root_type Proof;
file_identifier "PROF";  // optional 4-byte identifier

include "proof.fbs";

namespace proof;

enum ValidationType : uint8 {
  Quick = 0,
  Quick_Smell = 1,
  Full = 2,
  Model = 3,
  Challenge = 4,
  // Audit/logits verification: sequence + logits replay only, no block
  // sanity and no mining parameter envelope. Append-only addition —
  // wire-compatible with older readers (they warn on the unknown value).
  Logits = 5,
  // Batched ADVISORY triage of N shares in one request. NOT consensus: the
  // worker answers "which of these are worth a full verify", never a verdict.
  // Append-only addition — wire-compatible with older readers.
  BatchTriage = 6
}

enum ResponseValue : uint8 {
  Quick_OK = 0,
  Quick_Fail = 1,
  Quick_OK_Smell_OK = 2,
  Quick_OK_Smell_Fail = 3,
  Quick_Fail_Smell_OK = 4,
  Quick_Fail_Smell_Fail = 5,
  Full_Green = 6,
  Full_Amber = 7,
  Full_Red = 8,
  Model_OK = 9,
  Model_Fail = 10,
  Challenge_OK = 11,
  Challenge_Fail = 12,
  Model_Pending_Review = 13,
  Logits_OK = 14,
  Logits_Fail = 15,
  // Batch triage outcomes, one response emitted per share in the batch.
  // Triage_Clear means "deprioritised", NOT "verified good".
  Triage_Check = 16,
  Triage_Clear = 17,
  Triage_Error = 18
}

table BlockValidation {
  version: uint32;
  hash: [ubyte];             // 32 bytes
  prev_block_hash: [ubyte];  // 32 bytes
  merkle_root: [ubyte];      // 32 bytes
  timestamp: uint32;
  bits: uint32;
  nonce: uint32;
  pow_blob_hash: [ubyte];
  adjusted_bits: uint32;
  pow_blob: Proof;
  // Registered model difficulty from the ModelRecord active at the block's
  // height. Appended field: wire-compatible with old readers/writers.
  //
  // Option 2 (PROMPT BINDING.md §6) — this field doubles as the verifier's
  // v3-ACTIVE signal, so there is NO separate v3_active field:
  //   difficulty == 0  => v3 admission inactive/unavailable at this height;
  //                       a version>=3 proof is replayed under v2 rules
  //                       (admission nonce NOT folded into the u preimage),
  //                       byte-identical to consensus.
  //   difficulty  > 0  => v3 is ACTIVE; the verifier applies the v3
  //                       nonce/tier/admission semantics and derives the
  //                       admission target from this value.
  // bcore MUST send difficulty > 0 only when Consensus::IsV3Active(height)
  // is true, and remains authoritative for the admission check itself.
  difficulty: int64;
}

table ModelValidation {
  model_name: string;
  model_commit: string;
  difficulty: int64;
  cid: string;
  extra: string;
  txid: [ubyte];             // 32 bytes
  block_hash: [ubyte];        // 32 bytes
  block_height: int32;
}

// One share inside a batch. Carries its own hash_id so each response can be
// correlated back by the caller, exactly like a single-share request, plus the
// share's COMPLETE serialized ValidationRequest bytes. Embedding the encoded
// request (rather than a nested BlockValidation) means both sides reuse the
// existing single-share encode/decode path unchanged -- no cross-buffer table
// copying, and pfunpack parses each share exactly as it always has.
table BatchShare {
  hash_id: [ubyte];            // 32 bytes
  request: [ubyte];            // a complete serialized ValidationRequest
}

// Batched advisory triage request. Appended to ValidationUnion (append-only,
// so existing readers keep their tag numbering).
table BatchValidation {
  shares: [BatchShare];
  chunk: uint32;               // shares per forward pass; 0 = worker default
  rank_ratio: float;           // flag above this x cohort median; 0 = default
  bootstrap: uint32;           // 0 = worker default
}

union ValidationUnion {
  BlockValidation,
  ModelValidation,
  BatchValidation
}

table ValidationRequest {
  hash_id: [ubyte];        // 32 bytes
  validation_type: ValidationType;
  request: ValidationUnion;
}

table ValidationResponse {
  hash_identifier: [ubyte];   
  enum_response: ResponseValue;
}

root_type ValidationRequest;

include "proof.fbs";

namespace proof;

table BlockHeader {
  req_id: uint32;
  version: uint32;
  prev_block_hash: [ubyte];  // 32 bytes
  merkle_root: [ubyte];      // 32 bytes
  timestamp: uint32;
  bits: uint32;
}

table MiningResponse {
  req_id: uint32;
  nonce: uint32;
  adjusted_bits: uint32;
  pow_blob_hash: [ubyte];
  difficulty: uint32;
  pow_blob: Proof;
  completion_id: string;  // OpenAI-style completion ID (e.g., "cmpl-xxxxx")
}

root_type BlockHeader;

Using these from a client

Generate a typed binding with the FlatBuffers compiler:

# C++
flatc --cpp -o gen/ proof.fbs validation.fbs blockheader.fbs

# Python
flatc --python -o gen/ proof.fbs validation.fbs blockheader.fbs

# Rust
flatc --rust -o gen/ proof.fbs validation.fbs blockheader.fbs

# TypeScript
flatc --ts -o gen/ proof.fbs validation.fbs blockheader.fbs

# JSON Schema (already generated; check `/schemas/json/` for the prebuilt files)
flatc --jsonschema -o gen/ proof.fbs validation.fbs blockheader.fbs

For JSON-encoded calls to /v1/verify/*/json, the field names on the wire match the FB table fields directly. For binary calls to /v1/verify/*, build a ValidationRequest and POST the resulting bytes as application/octet-stream.