TruthTable

TruthTable is a verifiable query engine for committed databases. Instead of asking clients to either trust a database server blindly or re-execute queries locally, TruthTable lets a server return a SQL query result together with a succinct cryptographic proof that the result was computed correctly with respect to a committed database snapshot.

TruthTable is built as a wrapper around the DataFusion query engine. In practice, that means it is not tied to SQL alone: any query language or frontend that can be lowered to DataFusion abstractions such as logical plans, expressions, and schemas can use TruthTable’s proving pipeline.

Quick start

A working end-to-end proof on a synthetic TPC-H lineitem table, no external downloads, no Python:

git clone https://github.com/alireza-shirzad/truth-table
cd truth-table
cargo run --release -p tt-exec --example quickstart

The example runs setup, commit, prove, and verify in sequence and prints Proof verified successfully. on success. First run generates the TPC-H test data into artifacts/test-data/ and caches the proving / verifying keys, so subsequent runs are faster.

Source of the example: crates/tt-exec/examples/quickstart.rs.

Example — bring your own Parquet

Suppose you want to perform verifiable queries on a sample table located in this link. Download the sample parquet into artifacts/ from the repo root:

1. Data generation and sanitization

This step prepares the input data that the rest of the pipeline will use. For this example, the sample Parquet file above is already the raw input and lives under artifacts/.

mkdir -p artifacts

curl -L https://www.timestored.com/data/sample/userdata.parquet -o artifacts/userdata.parquet

Preprocess the parquet file into the same padded/augmented shape used by the Rust pipeline:

python tt-scripts/preprocess.py artifacts/userdata.parquet -o artifacts/userdata_preprocessed.parquet

2. Setup

This step generates the proving and verifying keys that will later be used by the commitment, proving, and verification stages.

cargo run --release -p tt-exec --bin tt -- \
  setup \
  --size 16

3. Commitment

This step turns the source Parquet file into a committed .oracle artifact that the verifier can later use without having direct access to the raw table.

cargo run --release -p tt-exec --bin tt -- \
  commit \
  --parquet-path artifacts/userdata_preprocessed.parquet \
  --pk-path artifacts/tt_pk_16.pk \
  --output-path artifacts

4. Proving

This step runs the prover on a SQL query, producing both a proof artifact and the prover-computed query result.

cargo run --release -p tt-exec --bin tt -- \
  prove \
  --query "SELECT first_name FROM userdata_preprocessed WHERE salary<=100000" \
  --parquet-path artifacts/userdata_preprocessed.parquet \
  --oracle artifacts/userdata_preprocessed.oracle \
  --pk-path artifacts/tt_pk_16.pk \
  --output-path artifacts

5. Verification

This step checks that the proof is valid against the query, the committed table oracle, and the prover-produced result. Use the exact same query and the fresh proof.pi / proof.result.parquet generated by the preceding prove command.

cargo run --release -p tt-exec --bin tt -- \
  verify \
  --query "SELECT first_name FROM userdata_preprocessed WHERE salary<=100000" \
  --oracle artifacts/userdata_preprocessed.oracle \
  --proof artifacts/proof.pi \
  --result-path artifacts/proof.result.parquet \
  --vk-path artifacts/tt_vk_16.vk

Benchmarking

The repository ships a unified benchmark pipeline that produces every figure in the paper. It's organized as three suites × three stages:

	run (and dump)	parse (to CSV)	plot
TT TPC-H	run_tt_tpch.sh	parse_tt_tpch.py	plot_tt_tpch.py
PGN compare	run_pgn.sh	parse_pgn.py	plot_pgn.py
Micro	run_micro.sh	parse_micro.py	plot_micro.py

All scripts live in tt-results/scripts/. Each row is independent — you can re-plot from existing CSVs, or re-parse from existing raw outputs, without re-running benchmarks.

What each suite measures

• TT TPC-H — TruthTable proving the regular TPC-H queries (the _tt bench variants) across the full SF / thread matrix: SF=0.01/0.02/0.04 at 1 thread, SF=0.05/0.1 at 1 and 4 threads.
• PGN compare — head-to-head between two systems on Poneglyph-style queries: TruthTable on the _pgn variants AND PoneglyphDB on its KZG circuits, both single-threaded at matching dataset sizes (TPC-H SF=0.01/0.02/0.04 ↔ PoneglyphDB k=16/17/18).
• Micro — TruthTable vs sxt-proof-of-sql vs QEDB on the shared Filter / Aggregate / Join / Join_PK_FK / Limit micro-benchmarks. Requires the three pinned forks fetched via the third-party-bench/ git deps; see third-party-bench/README.md.

End-to-end (one command)

./bench_all.sh

runs all three suites, rebuilds all three CSVs in tt-results/tidy/, and renders every figure in tt-results/figures/. Stage-level helpers are also available:

./tt-results/scripts/run_all.sh      # only run + dump
./tt-results/scripts/parse_all.sh    # only rebuild CSVs from existing raw files
./tt-results/scripts/plot_all.sh     # only render figures from existing CSVs

Running a single suite

# TT TPC-H
./tt-results/scripts/run_tt_tpch.sh
python3 tt-results/scripts/parse_tt_tpch.py
python3 tt-results/scripts/plot_tt_tpch.py

# Poneglyph comparison
./tt-results/scripts/run_pgn.sh
python3 tt-results/scripts/parse_pgn.py
python3 tt-results/scripts/plot_pgn.py

# Micro
./tt-results/scripts/run_micro.sh
python3 tt-results/scripts/parse_micro.py
python3 tt-results/scripts/plot_micro.py

Outputs

Suite	Raw (tt-results/raw/)	CSV (tt-results/tidy/)	Figures (tt-results/figures/)
TT TPC-H	benches_tt_*.json, bench_stats_tt_*.jsonl	tpch.csv	tpch_tt_*.pdf
PGN compare	benches_pgn_*.json, bench_stats_pgn_*.jsonl, poneglyph_q*_k*.log	tpch_pgn.csv	tpch_pgn_*.pdf
Micro	third_party_*.log, third_party_*.json	micro.csv	micro_*.pdf

The CSVs are the single source of truth that the plot scripts read from — inspect them directly to sanity-check numbers before publishing figures.

Plot prerequisites

The plot scripts need Python 3.12 with matplotlib, numpy, pandas:

cd tt-results
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

See tt-results/readme.md for more detail on the plotting setup and the Streamlit bench dashboard.

License

TruthTable is released under the PolyForm Noncommercial 1.0.0 license: free for academic, research, personal, and nonprofit use; commercial use requires a separate license. See the LICENSE file for the full terms and a contact address for commercial licensing enquiries.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for how to set up a development environment, our PR expectations, and the test commands CI enforces. Security issues should be reported privately; see SECURITY.md.

Papers

This repository is based on the following paper:

• TruthTable: A Verifiable Query Engine (link will be updated when the paper is publicly available)

Cite

If you use this project, please cite:

@article{namboothiry2026truthtable,
  title={TruthTable: A Verifiable Query Engine},
  author={Namboothiry, Bharath and Shirzad, Alireza and Solit, Spencer and Marcus, Ryan and Mishra, Pratyush},
  year={2026}
}