VEIL — confidential-payments network for stablecoins (research → working prototype)

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install workspace dependencies
+        run: npm install
+
+      - name: Build SDK
+        run: npm run build:sdk
+
+      - name: Build services
+        run: npm run build:services
+
+      - name: Build app
+        run: npm run build:app
+
+      - name: Type-check services / app / solana
+        run: |
+          npm run typecheck:services
+          npm run typecheck:app
+          npm run typecheck:solana
+
+      - name: SDK tests
+        run: npm run test:sdk
+
+      # The real-proof / e2e tests self-skip without the circuit artifacts
+      # (build/*.wasm, *.zkey are gitignored); all other contract tests run.
+      - name: Contract tests
+        run: npm run test:contracts

.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+artifacts/
+cache/
+coverage/
+typechain-types/
+# circuit + snarkjs build outputs (ptau, zkey, wasm, r1cs, sym, witness calc)
+build/
+*.log
+.DS_Store
+.env
+.env.*
+# Solana / circuit build artifacts and local keypairs
+*.zkey
+*.r1cs
+*.wasm
+*-elgamal.json
+auditor-elgamal.json
+# local/ephemeral deployment outputs (testnet/mainnet deployments may be committed)
+deployments/localhost.json
+deployments/hardhat.json

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VEIL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,17 +1,99 @@
-# Cryptonic
+# VEIL
 
-Research and design workspace for a novel cryptocurrency project.
+**A neutral, multi-chain confidential-payments network for stablecoins.**
+Send USDC/USDT without broadcasting every amount to the world — with compliance built in as
+zero-knowledge proofs, not a backdoor. *Confidentiality, not anonymity.*
 
-## Contents
+VEIL targets crypto's one proven market (stablecoins: ~$290B supply, ~$28T quarterly volume)
+and its best-performing narrative (privacy), assembling primitives both major ecosystems
+shipped in 2025–26 into a product that regulated businesses can actually use. See the
+[whitepaper](docs/whitepaper.md) for the full rationale, and
+[`docs/token-ideas.md`](docs/token-ideas.md) for the logic audit that selected VEIL over two
+alternatives.
 
-- [`docs/market-research-2026.md`](docs/market-research-2026.md) — multi-source synthesis
-  of the state of the art (July 2026): macro market, Ethereum, Solana, stablecoins, RWA,
-  AI×crypto, privacy, ZK, MEV, DePIN, interoperability — plus confirmed dead zones and
-  identified whitespace.
-- [`docs/token-ideas.md`](docs/token-ideas.md) — three grounded token concepts (VEIL,
-  MERIDIAN, JOULE), a logic audit against 2026 litmus tests and Vitalik Buterin's recent
-  essays, and a recommendation of which to build.
+## Repository layout
+
+| Path | What |
+|---|---|
+| [`docs/whitepaper.md`](docs/whitepaper.md) | VEIL design, token/value-accrual, threat model, roadmap. |
+| [`docs/market-research-2026.md`](docs/market-research-2026.md) | State-of-the-art crypto/Ethereum/Solana research the design is grounded in. |
+| [`docs/token-ideas.md`](docs/token-ideas.md) | The three candidate concepts and the audit that chose VEIL. |
+| [`packages/contracts`](packages/contracts) | EVM shielded pool, token/buyback-burn/staking module, cross-chain settlers (Solidity + Hardhat), circom withdrawal circuit, tests. |
+| [`packages/sdk`](packages/sdk) | Client SDK: notes, Merkle proofs, association sets, view-key encryption. |
+| [`packages/services`](packages/services) | Off-chain services: relayer (gasless proving) + Association Set Provider (screening). |
+| [`packages/app`](packages/app) | Business payments client + `veil` CLI (shield / pay / audit). |
+| [`packages/web`](packages/web) | Local dashboard at `localhost:3000` that runs & visualizes a real confidential payment. |
+| [`packages/solana`](packages/solana) | Solana Token-2022 confidential-transfer prototype + CLI runbook. |
+
+## How it works (one paragraph)
+
+Deposits are public: you shield `value` tokens under a commitment
+`Poseidon(value, Poseidon(nullifier, secret))` inserted into a Merkle tree, and the note is
+encrypted to a **view key** so you (or an auditor you choose) can later decrypt it. Withdrawals
+are private: a zero-knowledge proof shows your commitment is in the pool tree **and** in an
+approved **association set** (proof of innocence) without revealing which deposit is yours,
+revealing only a nullifier to stop double-spends. A protocol fee on each withdrawal funds an
+on-chain buyback-and-burn; the VEIL token is the slashable bond that keeps the rail
+un-censorable.
+
+## Quick start
+
+```bash
+# from the repo root
+npm install --workspaces
+
+# EVM shielded pool — compiles (offline solc) and runs the full suite
+npm run test:contracts     # 7 passing
+
+# Client SDK — notes, merkle proofs, association sets, view keys
+npm run test:sdk           # 8 passing
+
+# Solana prototype — type-check
+npm run typecheck:solana
+```
+
+## Deploy & run the live demo
+
+```bash
+cd packages/contracts
+npx hardhat node &                                       # local devnet
+npx hardhat run scripts/deploy.ts  --network localhost   # deploy the full stack
+npx hardhat run scripts/demo.ts    --network localhost   # run a real confidential payment
+```
+
+The demo prints the whole flow end-to-end (verified live against a local node with the real
+Groth16 verifier):
+
+```
+1. business shielded 1000.0 USDC (balance now private)
+2. ASP published approved-set root (proof of innocence available)
+3. relayer paid supplier 996.0 USDC privately (business paid no gas)
+   relayer fee: 3.0 USDC · protocol fee -> buyback&burn: 1.0 USDC
+4. auditor decrypted the shielded note with the view key: 1000.0 USDC
+```
+
+Prefer a visual? Run the dashboard instead of the CLI demo — with the node + deploy from above:
+
+```bash
+cd packages/web && npm install && npm start   # -> http://localhost:3000
+```
+
+Click **Run a confidential payment** to execute the real flow and see the public (encrypted)
+view beside the auditor's decrypted view. See [`packages/web`](packages/web).
+
+Point the same scripts at a testnet with `--network sepolia` (set `SEPOLIA_RPC_URL` and
+`DEPLOYER_PRIVATE_KEY`). See [`deployments/`](deployments).
 
 ## Status
 
-Awaiting selection of one of the three concepts to begin whitepaper + prototype work.
+Prototype. Implemented: EVM shielded pool + tests (on-chain Merkle root cross-checked against
+an independent computation); client SDK + tests; withdrawal circuit compiled with a Groth16
+trusted setup into a real verifier; relayer + Association Set Provider services; token +
+buyback-and-burn + staking/slashing module (value-accrual loop tested from a real pool fee);
+cross-chain shielded payments (ERC-7683-style open → fill → claim); a staking-gated relayer;
+and a **business payments app (`shield`/`pay`/`audit`) tested end-to-end with a real proof —
+26/26 contract tests passing**. Remaining before production: a public trusted-setup ceremony,
+a real cross-chain messaging oracle, hardened key storage, and an independent security audit.
+See the whitepaper roadmap.
+
+> Not audited. Not for production use. Research prototype.

deployments/README.md

@@ -0,0 +1,27 @@
+# Deployments
+
+Deployment address books written by `packages/contracts/scripts/deploy.ts`, one JSON per network.
+
+Local/ephemeral outputs (`localhost.json`, `hardhat.json`) are gitignored; testnet/mainnet
+deployments can be committed here for reference.
+
+## Deploy
+
+```bash
+cd packages/contracts
+
+# Local devnet:
+npx hardhat node &                                   # terminal 1
+npx hardhat run scripts/deploy.ts --network localhost
+
+# Sepolia (needs a funded key):
+SEPOLIA_RPC_URL=https://... DEPLOYER_PRIVATE_KEY=0x... \
+  npx hardhat run scripts/deploy.ts --network sepolia
+```
+
+Each file records every contract: the Poseidon hasher, the (real or mock) verifier, the
+stablecoin, the VEIL token, swap router, buyback-burner, staking, association-set registry, the
+pool, and the cross-chain settlers + oracle.
+
+> On a real network, deploy against an existing USDC address and a real DEX router instead of
+> the `MockERC20` / `MockSwapRouter` used for local runs.