zkTLS Proofs
Cryptographic verification of web data
What is zkTLS?
zkTLS (zero-knowledge TLS) is a cryptographic technique that allows proving facts about data received over HTTPS (TLS) connections without revealing the full session data.
For zkGrants, this means we can prove that GitHub's API returned specific data (like "PR #123 was merged") without trusting any intermediary — the proof is verifiable by anyone, including onchain smart contracts.
Key insight: zkTLS bridges Web2 data (GitHub) to Web3 verification (smart contracts) without oracles or trusted third parties.
How zkTLS Works
1. TLS Session Capture
When you authenticate with GitHub and request API data, the TLS handshake and encrypted response are captured. The server certificate proves the data came from GitHub.
2. Zero-Knowledge Circuit Execution
A ZK circuit verifies the TLS certificate chain, decrypts the relevant portion of the response, and extracts the specific data needed (e.g., merge status, workflow result) without exposing the full response.
3. Proof Generation
The circuit produces a succinct proof (a few hundred bytes) that can be verified in constant time. This proof attests to specific claims about the GitHub data.
4. Onchain Verification
The proof is submitted to the smart contract along with public inputs (grant ID, recipient address, etc.). The contract verifies the proof and releases funds if valid.
What zkGrants Proves
A zkGrants claim proof attests to multiple facts simultaneously:
1Data Authenticity
The data was received from GitHub's servers (verified via TLS certificate chain to GitHub's root certificate).
2GitHub Outcome
A specific event occurred: PR was merged, workflow passed successfully, or checks completed with expected status.
3Grant Binding
The outcome matches grant parameters: correct repository, target branch, required workflow, and within deadline if applicable.
4Identity Binding
The claimant controls the GitHub account (via OAuth session) that authored the qualifying PR.
5Recipient Commitment
The payout address is cryptographically bound to the proof, preventing front-running or substitution attacks.
Supported Claim Types
PR Merged
Proves a pull request was merged into the target branch by a repo maintainer.
API endpoint: /repos/:owner/:repo/pulls/:number
Verified field: merged = true
Workflow Passed
Proves a GitHub Actions workflow completed successfully for a specific commit.
API endpoint: /repos/:owner/:repo/actions/runs/:run_id
Verified field: conclusion = success
Security Properties
✓ What zkTLS Guarantees
- Data came from GitHub (certificate verification)
- Data wasn't modified (TLS integrity)
- Proof is unforgeable (ZK soundness)
- No trust in zkGrants or any third party
⚠ Trust Assumptions
- GitHub's API returns accurate data
- TLS/PKI infrastructure is secure
- ZK proving system is sound (well-audited)
- Verifier contract is correctly implemented
Implementation
zkGrants uses SP1 ZKVM by Succinct Labs as the proving engine. SP1 enables writing ZK programs in Rust that can be verified onchain.
SP1 ZKVM
SP1 is a performant, open-source zero-knowledge virtual machine that allows developers to write provable programs in Rust. The zkTLS verification logic runs inside SP1, generating succinct proofs of GitHub API responses.
Prover Infrastructure
Proof generation runs on GPU-enabled instances for performance. The prover service is separate from the main application for scalability.
Chain Support
On Ethereum, SP1 proofs are verified via standard Groth16/PLONK verifier contracts. On Solana, we use Light Protocol's Groth16 verifier for efficient onchain verification.
Permissionless Proving
Anyone can run the prover independently. The system is designed so zkGrants is not a required intermediary — proofs can be generated and submitted directly to the chain.
Learn More
Understand the smart contracts that verify proofs and manage escrow.