Skip to content
Developers / documentation

Build on privacy.

Everything you need to run VEILOPS locally, integrate the SDK, and understand exactly what it does and does not protect.

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:3700

The 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-only publishes the recipient; amount-and-recipient and full do not. full currently produces the same record as amount-and-recipient and exists to satisfy stricter policy minimums.

@veilops/sdk

createClient(opts?: { signingKey?, owner?, viewers?: string[] })
Returns { process, verify, signingPublicKey, ownerPublicKey }. Generates ephemeral keys if none are given; never persists them.
process(input, policy, { onStage? }) → Promise<ProcessResult>
Runs created → encrypted → policy → proof → verified. Throws PolicyViolation (with the failing checks) instead of producing a proof for a violation.
pseudonym(recipient, salt) → string
Stable salted pseudonym, for apps that need correlation without publishing identifiers.

@veilops/encryption

generateViewingKeyPair() → { publicKey: hex, secretKey: Uint8Array }
X25519 key pair.
seal(plaintext, recipients: hex[], aad) → Promise<Envelope>
Encrypts once, wraps the data key per recipient.
open(envelope, secretKey) / openText(...)
Decrypts; throws for non-recipients or any tampering.
grantAccess(envelope, ownerSecret, newRecipient) → Promise<Envelope>
Selective disclosure without re-encrypting the payload.
envelopeDigest(envelope) → hex
SHA-256 over ciphertext, nonce and aad; published in the record.

@veilops/policy-engine

definePolicy({ name, maxAmount, rangeBits?, allowedCategories?, allowedAssets?, minimumMode? })
Validates and returns a Policy. maxAmount must be < 2^rangeBits; rangeBits ≤ 48.
evaluate(policy, input) → PolicyResult
All rules on plaintext (operator side).
evaluatePublic(policy, record) → PolicyCheck[]
Only the rules a third party can check.
policyId(policy) → 'pol_…'
Content address of a policy.

@veilops/proof-engine

experimental Real zero-knowledge proofs; unaudited.

provePolicy({ operationId, policyId, maxAmount, rangeBits, asset, category, amount })
Returns { publicInputs, proof, proofId, opening, timings }. Refuses amounts above the limit.
verifyPolicy(publicInputs, proof) → VerifyReport
Checks both range proofs. Never throws on malformed input.
verifyRecord(record) → RecordVerification
Proof + proof-id binding + Ed25519 attestation.
commit(v, r) · verifyOpening(C, v, r) · proveRange / verifyRange
Lower-level primitives.
attest(record, key) · verifyAttestation(record) · generateSigningKey()
Ed25519 publishing signatures.

@veilops/solana-adapter

experimental Untested on any cluster. Sends nothing.

anchorMemo(record) → string · buildAnchorInstruction(record, signer)
Memo-program anchor veilops:<version>:<proofId>:<digest> for your wallet to sign.
parseAnchorMemo(memo)
Parses an anchor back into its fields.

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

MethodPathDescription
GET/api/healthVersions; states that no chain is connected.
GET/api/recordsSample index without proof blobs.
GET/api/records/:idFull record by operation id or proof id.
POST/api/verifyVerify a record (JSON, ≤ 256 KB). Stateless, nothing stored.

Examples

  • examples/basic-operation.ts: process, publish, verify, tamper, policy violation. npx tsx examples/basic-operation.ts
  • examples/selective-disclosure.ts: auditor access with grantAccess and 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

DataWho can see it
AmountOwner and authorized viewers (envelope); everyone else sees a commitment.
RecipientPublic in amount-only mode; otherwise owner and viewers only.
Name, memoOwner and viewers only.
Category, asset, mode, timestamp, policy limitEveryone (metadata).
That an operation happened, and how oftenEveryone. 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

ComponentStatusNotes
Envelope encryptionimplementedAES-256-GCM + X25519/HKDF key wrapping, runs in your browser. Unit-tested, not externally reviewed.
Policy engineimplementedPublic rules + a confidential amount limit that is enforced by the range proof.
Range proof (veilops-range-v1)experimentalReal zero-knowledge proof of 0 ≤ amount ≤ limit on a Pedersen commitment. Not audited, not succinct.
Record attestationimplementedEd25519 signature by the publishing operator. Proves origin, not privacy.
Public proof explorerimplementedReal verification in your browser over a SAMPLE dataset. No live network indexer yet.
Solana anchoringexperimentalBuilds an SPL Memo anchor instruction. Not tested on devnet or mainnet; sends nothing.
Token-2022 confidential transfersplannedIntegration with the confidential transfer extension where supported.
On-chain verifier programplannedAn Anchor program for record registration. Not written yet.
Wallet connectionplannedHidden until there is something real for a wallet to sign.