Tells

A privacy checkup for Zcash wallets. Shielded transactions hide who paid whom and how much. How you enter and leave the shielded pool can still link your addresses together. Tells reads a wallet's history through its viewing key, on your own machine, and shows what an outside observer can connect. Run it before a withdrawal and it proposes a safer way to make it.

Live: https://luoy16002-svg.github.io/tells/

Why

The first studies of the Zcash chain found that simple patterns undo most of the privacy people think they have:

• Matching amounts that go into the shielded pool with amounts that come out paired up 31.5% of the coins sent into the pool, and 96% of those round trips left within two hours (Quesnelle, 2017).
• A handful of such heuristics shrinks the anonymity set considerably (Kappos, Yousaf, Maller, Meiklejohn, USENIX Security 2018).

Wallets today warn about transparent addresses, but nothing tells a user "this withdrawal will link you to the deposit you made an hour ago." Tells does, before the transaction exists.

What it checks

Only three things cross the pool boundary in public: an amount, a block time and a transparent address. Every rule uses nothing else, so every finding is something anyone reading the chain can also find.

Rule	What it catches	Severity
Round trip	An exit within a fee (or 0.1%) of an earlier entry	Critical under 2 h, high under a day; up for unique amounts, down for round ones
Sum match	An exit equal to two or three recent entries added together	Like round trips
Quick exit	Leaving the pool within a day of entering, even with different amounts	High under 1 h
Fingerprint amounts	Crossings with four or more decimals (round amounts minus a fee count as round)	Low to medium
Address reuse	One transparent address on several crossings	Low to medium
Transparent payments	Transparent-to-transparent spends	Low to medium
Pool migrations	Sapling, Orchard and Ironwood moves publish their amount	Low
Crowd size	Other people's look-alike entries and exits in the same window: exits from compact blocks, entry amounts by resolving each shielding transaction's transparent inputs	Lowers a link by one or two levels

Measured on mainnet blocks 3,504,400–3,504,495 (about two hours), Tells resolved all 50 shielding transactions: 36 had no look-alike entry, 10 had one and 4 had three. The first run fetched 162 transactions in 45 seconds; a repeat run reads them from the on-disk cache in under a second.

Pre-flight takes a planned withdrawal (amount, time, destination), runs the same rules as if it had happened, and if it is risky proposes alternatives: wait, send a round amount and keep the remainder shielded, split, or use a fresh address. Every alternative is re-checked before it is shown.

Use it

In the browser

Open the live page, look at the sample wallets, try the pre-flight, or drop your own history.json (made below). The page runs entirely client-side.

On your own wallet

You need a unified full viewing key (uview1...), which can see your history but cannot spend, and the wallet's birthday height. With Node 22 or newer:

npx github:luoy16002-svg/tells scan --ufvk uview1... --birthday 2726400 --out history.json

This creates a view-only wallet in a temporary folder, syncs it from lightwalletd (zec.rocks by default) with zcash-devtool, prints the checkup and writes history.json for the web page. If zcash-devtool is not on your PATH and you pass no --devtool, Tells downloads a build of the pinned upstream commit made by this repository's public scanner workflow, and checks it against the release's SHA256SUMS. Behind a proxy, set HTTPS_PROXY and NODE_USE_ENV_PROXY=1.

Other commands:

tells report  <wallet-dir | history.json>
tells preflight <wallet-dir | history.json> --amount 0.75 --at 2026-10-04T12:00Z --to t1...
tells export  <wallet-dir> --out history.json

In a wallet

The rules are a dependency-free TypeScript package (packages/core) that runs in a browser, Node or a mobile JavaScript engine:

import { preflight } from '@tells/core';

const check = preflight(history, { amount: 54_311_000, time: Date.now() / 1000, address: recipient });
if (check.verdict === 'risky') showWarning(check.findings[0].title, check.alternatives);

How it is built

packages/core   rules, scoring, pre-flight (TypeScript, no dependencies, tested with vitest)
packages/cli    reads a zcash_client_sqlite wallet (Node's built-in SQLite), drives zcash-devtool for scans
apps/web        the checkup page (Vite, plain TypeScript, hand-drawn SVG timeline)
demo/           testnet histories made with real transactions

The CLI reads v_received_outputs, v_received_output_spends and sent_notes from the wallet database to rebuild, per transaction, what the account spent and received in each pool (transparent, Sapling, Orchard, Ironwood). Crossings are derived from those flows the way an observer sees them: value entering or leaving the shielded pools, and moves between them.

Privacy model

• Tells never asks for a seed phrase or a spending key.
• The viewing key goes to zcash-devtool on your machine, which talks to a lightwalletd server like any light wallet does. Use --server to choose one you trust, or route over Tor with zcash-devtool's --connection tor.
• The web page has no backend. history.json is read in the browser and never sent anywhere.

Limits

• Entry amounts are not in compact blocks, so Tells fetches each shielding transaction in the window, plus the outputs it spends, from lightwalletd and caches them by txid. Each window is capped (1,152 blocks and 200 transactions by default, --entry-crowd-max-blocks and --entry-crowd-max-transactions). A window that hits a cap or a fetch error is reported as incomplete and never lowers a severity.
• Amount matching assumes standard fees (ZIP 317). Unusual fees can hide or create matches.
• It flags patterns that link transactions; it cannot prove that nobody linked them some other way (network-level metadata, exchange records).

Business

• Users check for free: the page and the CLI stay open source.
• Wallets and exchanges integrate the pre-flight check, where it prevents the leak instead of reporting it. Integration support and an SLA-backed SDK are the paid product; custodial exchanges get a version that warns their customers before a TEX or transparent withdrawal.
• Funds, OTC desks and journalists' organisations that hold ZEC for privacy buy periodic audits of their treasury wallets, run on their own machines.
• The open core is a natural fit for Zcash ecosystem grants, which fund the first wallet integrations.

Roadmap

• A mainnet dashboard of how linkable crossings are overall, built on the same entry and exit crowd counts.
• WebAssembly scanning in the browser (WebZjs), so the whole checkup works without a terminal.
• Wallet integrations: a pre-flight hook for Zashi, Zingo and YWallet before they build a transaction to a transparent or TEX address.

License

MIT. Built by Kai Chen for the Colosseum Crypto World's Fair (Zcash track).