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
}

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
}

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;
}

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;
}

union ValidationUnion {
  BlockValidation,
  ModelValidation
}

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.