Getting started
VEILOPS is a TypeScript monorepo of small packages with no runtime services. Everything (encryption, policy evaluation, proving and verification) runs in your process or your user's browser. Cryptographic primitives come from the audited @noble/curves and @noble/hashes libraries and WebCrypto; the VEILOPS protocol code built on them is not audited.
Repository: veilops-protocol/veilops.
Installation
git clone https://github.com/veilops-protocol/veilops.git
cd veilops
nvm use # Node 22 LTS (20.10+ works)
npm install
npm test # unit, integration and security tests
npm run dev # website on http://localhost:3700The packages are not yet published to npm. Inside the monorepo they resolve through npm workspaces as @veilops/*.
Quick start
import { createClient, encryption } from '@veilops/sdk';
import { definePolicy } from '@veilops/policy-engine';
const auditor = encryption.generateViewingKeyPair(); // X25519, held by the auditor
const veil = createClient({ viewers: [auditor.publicKey] });
const policy = definePolicy({ name: 'contributors', maxAmount: 25_000_00, rangeBits: 24 });
const res = await veil.process({
name: 'November payout',
category: 'payroll',
recipient: 'alice.sol',
amount: 4_825_00, // integer minor units
asset: 'USDC',
policyLimit: 25_000_00,
mode: 'amount-and-recipient',
}, policy, { onStage: e => console.log(e.stage, e.detail) });
res.record; // PublicRecord: safe to publish
res.envelope; // encrypted payload for owner + auditor
veil.verify(res.record); // { valid: true, checks: [...] }Concepts
- Operation: what the application wants to do: name, category, recipient, amount, asset, policy limit, confidentiality mode.
- Envelope: the encrypted operation (AES-256-GCM), readable by the owner and explicitly authorized viewers.
- Policy: content-addressed rules. Public rules are checkable by anyone; the amount limit is enforced in zero knowledge.
- Public record: commitment + proof + public metadata + Ed25519 attestation. Contains no plaintext amount.
- Modes:
amount-onlypublishes the recipient;amount-and-recipientandfulldo not.fullcurrently produces the same record asamount-and-recipientand exists to satisfy stricter policy minimums.
@veilops/sdk
createClient(opts?: { signingKey?, owner?, viewers?: string[] }){ process, verify, signingPublicKey, ownerPublicKey }. Generates ephemeral keys if none are given; never persists them.process(input, policy, { onStage? }) → Promise<ProcessResult>PolicyViolation (with the failing checks) instead of producing a proof for a violation.pseudonym(recipient, salt) → string@veilops/encryption
generateViewingKeyPair() → { publicKey: hex, secretKey: Uint8Array }seal(plaintext, recipients: hex[], aad) → Promise<Envelope>open(envelope, secretKey) / openText(...)grantAccess(envelope, ownerSecret, newRecipient) → Promise<Envelope>envelopeDigest(envelope) → hex@veilops/policy-engine
definePolicy({ name, maxAmount, rangeBits?, allowedCategories?, allowedAssets?, minimumMode? })maxAmount must be < 2^rangeBits; rangeBits ≤ 48.evaluate(policy, input) → PolicyResultevaluatePublic(policy, record) → PolicyCheck[]policyId(policy) → 'pol_…'@veilops/proof-engine
experimental Real zero-knowledge proofs; unaudited.
provePolicy({ operationId, policyId, maxAmount, rangeBits, asset, category, amount }){ publicInputs, proof, proofId, opening, timings }. Refuses amounts above the limit.verifyPolicy(publicInputs, proof) → VerifyReportverifyRecord(record) → RecordVerificationcommit(v, r) · verifyOpening(C, v, r) · proveRange / verifyRangeattest(record, key) · verifyAttestation(record) · generateSigningKey()@veilops/solana-adapter
experimental Untested on any cluster. Sends nothing.
anchorMemo(record) → string · buildAnchorInstruction(record, signer)veilops:<version>:<proofId>:<digest> for your wallet to sign.parseAnchorMemo(memo)Record format
{
"version": "veilops/0.1",
"operationId": "op_4f1c9a02b7e3d815",
"proofId": "prf_91d0a3c4e5f6a7b8c9d0",
"createdAt": "2026-11-04T14:02:11.000Z",
"category": "payroll", "asset": "USDC", "mode": "amount-and-recipient",
"policy": { "id": "pol_3c…", "maxAmount": 2500000, "rangeBits": 24 },
"amountCommitment": "6a1f…09bd", // ristretto255 point, hex
"envelopeDigest": "e3b0…b855", // sha-256 of the envelope
"proofSystem": "veilops-range-v1",
"proof": "eyJzeXN0ZW0iOi…", // base64
"attestation": { "publicKey": "…", "signature": "…" } // ed25519
}HTTP API
| Method | Path | Description |
|---|---|---|
| GET | /api/health | Versions; states that no chain is connected. |
| GET | /api/records | Sample index without proof blobs. |
| GET | /api/records/:id | Full record by operation id or proof id. |
| POST | /api/verify | Verify a record (JSON, ≤ 256 KB). Stateless, nothing stored. |
Examples
examples/basic-operation.ts: process, publish, verify, tamper, policy violation.npx tsx examples/basic-operation.tsexamples/selective-disclosure.ts: auditor access withgrantAccessand commitment opening.- Server verification:
curl -X POST /api/verify --data @record.json - The verification playground and dashboard are themselves integrations of the SDK in a Next.js app.
Security model
| Data | Who can see it |
|---|---|
| Amount | Owner and authorized viewers (envelope); everyone else sees a commitment. |
| Recipient | Public in amount-only mode; otherwise owner and viewers only. |
| Name, memo | Owner and viewers only. |
| Category, asset, mode, timestamp, policy limit | Everyone (metadata). |
| That an operation happened, and how often | Everyone. VEILOPS does not provide anonymity. |
Report vulnerabilities privately through GitHub security advisories on the main repository once it is published. Please do not open public issues for security reports.
Trust assumptions
- The operator's Ed25519 key authenticates records. A stolen key allows publishing fake within-policy records, never over-limit proofs.
- Discrete-log hardness on ristretto255 and SHA-512 as a random oracle.
- The client device: plaintext exists in the browser before sealing.
- No blockchain anchoring is live; existence and ordering depend on the publisher.
- Policy contents beyond id, limit and bit length are not published; verifiers cannot recompute the policy id from a record alone.
Implementation status
| Component | Status | Notes |
|---|---|---|
| Envelope encryption | implemented | AES-256-GCM + X25519/HKDF key wrapping, runs in your browser. Unit-tested, not externally reviewed. |
| Policy engine | implemented | Public rules + a confidential amount limit that is enforced by the range proof. |
| Range proof (veilops-range-v1) | experimental | Real zero-knowledge proof of 0 ≤ amount ≤ limit on a Pedersen commitment. Not audited, not succinct. |
| Record attestation | implemented | Ed25519 signature by the publishing operator. Proves origin, not privacy. |
| Public proof explorer | implemented | Real verification in your browser over a SAMPLE dataset. No live network indexer yet. |
| Solana anchoring | experimental | Builds an SPL Memo anchor instruction. Not tested on devnet or mainnet; sends nothing. |
| Token-2022 confidential transfers | planned | Integration with the confidential transfer extension where supported. |
| On-chain verifier program | planned | An Anchor program for record registration. Not written yet. |
| Wallet connection | planned | Hidden until there is something real for a wallet to sign. |