Sentinel is a cryptographic attestation system that enables users to prove their financial data (bank balance, transaction history) to third parties without exposing credentials. It leverages MPC-TLS (via TLSNotary) and Zero-Knowledge Proofs (via Noir) to create verifiable, privacy-preserving attestations.
Note (March 2026): Sentinel was my initial architecture for Zero-Knowledge financial attestations using zkTLS. While powerful, zkTLS introduces massive latency overhead for real-time AI agents. I have since evolved this architecture into Zemtik, replacing zkTLS with a sub-20-second local state-extraction proxy (Rust + UltraHonk) designed specifically for Enterprise AI compliance.
- Selective Disclosure (v2): Reveal only specific JSON fields (
balance,currency) from a TLS session. The verifier (not the client) commits these to the transcript, ensuring they are cryptographically bound to the bank's response. - Zero-Knowledge Proofs (v3): Prove that a balance exceeds a threshold (e.g.,
balance > 1,000,000 COP) without revealing the exact figure. Uses Noir UltraHonk to generate proofs in the browser and verify them on the backend.
- Proof Origin Binding: Attestations are linked to their originating TLS session via transcript hashes.
- HMAC Webhook Authentication: Secure, replay-protected delivery of proofs from the TLSNotary verifier to the Sentinel backend.
- ECDSA Signatures: All attestations are signed using secp256k1 (the same curve as Ethereum) for easy third-party verification.
User Browser (React + TLSN Extension)
↓
MPC-TLS Session (TLSNotary Protocol)
↓
Local/Remote Verifier (Webhook)
↓
Sentinel Backend (Signature & ZK Verification)
↓
Signed Attestation (secp256k1)
backend/: Attestation REST API and verification logic.app/: Frontend for wallet connection and proof submission.circuit/: Noir ZK circuit for balance threshold proofs.plugin-bancolombia/: TLSNotary plugin for live Bancolombia sessions.plugin-sdk/&tlsn-common/: Shared utilities for building plugins.mock-bank/: (Legacy) HTTPS server for development testing (deprecated).
For v3 ZK proofs, we use a commitment scheme to bind the private balance to the public proof:
commitment = sha256(balance_le_bytes || blinder)
balance_le_bytes: 8-byte little-endian encoding of the floor(balance).blinder: 16 random bytes to prevent brute-force preimage attacks.
- Mock Bank (v2): Default threshold is 1,000 USD.
- Bancolombia (v3): Default threshold is 1,000,000 COP.
- Thresholds are configurable via environment variables or public inputs in the ZK circuit.
- Bun (v1.3.4+): Package management and test runner.
- Nargo (v1.0.0-beta.3+): Noir CLI for compiling circuits.
- Barretenberg CLI (bb): Proving backend for verifying ZK proofs.
- Chrome: Required for the TLSNotary Browser Extension.
git clone https://github.com/yourusername/sentinel.git
cd sentinel
bun installBuild the ZK circuit and the Bancolombia plugin before running the full stack:
# Compile Noir circuit and generate verification key (optional for v2-only flows)
bun run circuit:build
# Build the Bancolombia plugin and copy to app/public/
bun run plugin:buildplugin:build builds plugin-bancolombia and copies ts-plugin-bancolombia.js to app/public/. For local dev, set VERIFIER_URL and PROXY_URL in plugin-bancolombia/.env (see plugin-bancolombia/.env.example). For Vercel, set those variables in the project’s Environment Variables.
- Start Backend:
bun run sentinel:start(Port 3000) - Start Web App:
bun run app:dev(Port 5173) - Configure Extension: Set Notary/Proxy API to
http://localhost:7047and ensure your local TLSNotary verifier is running.
The project includes a comprehensive suite of 146 tests covering the backend, circuits, and plugin SDK.
# Run all tests (requires 'bb' CLI for ZK tests)
bun test
# Run backend tests only
cd backend && bun testNote: Some ZK tests may fail if bb is not in your PATH. Integration tests for the mock bank require the bank server to be running or will be skipped in future updates.
- v2 Selective Disclosure: Path-level extraction of bank data with transcript binding.
- v3 ZK Threshold Proofs: Browser-side Noir proof generation and backend verification.
- Webhook HMAC Auth: Secure delivery of proofs with replay protection.
- PEDERSEN TLS binding: Replace
REVEALwithPEDERSENactions in the TLSNotary plugin to ensure balance values never touch the webhook payload. - On-chain Verification: Solidity verifier for Noir proofs to enable smart contract integration.
- Multi-bank Support: Standardization of plugin outputs for easier bank onboarding.
- Research: Read
docs/ARCHITECTURE.mdanddocs/ZK_CIRCUITS.md. - Implement: Follow the existing TypeScript and Noir patterns.
- Test: Ensure
bun testpasses (including ZK verification). - Document: Update relevant
.mdfiles in/docsfor any architectural changes.
MIT