Ringdiff docs
Ringdiff checks what a payment flow on Solana Privacy Rings exposes to a public observer, compares it with what your app promises, and returns a verdict you can enforce in CI. It reads public Solana mainnet data, never asks for a key or a transaction signature, and is independent of Helius.
Setup
Run Ringdiff with npx ringdiff. The ringdiff package is the CLI. @ringdiff/core holds decoding, classification, policies, diffs and exposure summaries, works in the browser, and is what this site’s lab runs.
# Node.js 22 or newer. Nothing to install:
npx ringdiff inspect 4idXopQ9nwMJby8Jc7kSyuSbyH5rs2unA7amLkxdQCJfNmVpsgMgBRjihDg4myVdwfWhuCdfsBqk8ChhKLKQP9Jv
# Or pin it in your project so CI uses one version
npm install --save-dev ringdiff
npx ringdiff --version
To work on Ringdiff itself, or run this site locally, build from source with pnpm 10:
git clone <this repo> ringdiff && cd ringdiff
pnpm install && pnpm build:packages
pnpm dev # this site on http://localhost:3000
pnpm ringdiff --help # the CLI from source
- SDK
@heliuslabs/zolana@0.8.0-alpha, pinned- Privacy program
ring1GaLCuJnkUMVkX2JeZLTTX17wKsV4fZmPVzXANW- User registry
regy3WAeRXMYuMYxr5iK3Bf9Arr3PcxGxyzAddbiqDQ- SOL pool
CiNmas621VuyofiDSrEPfTXHKrdZuB6jMKECyNiMpLXE- Reads
- Standard Solana JSON-RPC: getTransaction (jsonParsed) and getSignaturesForAddress, finalized commitment only.
- Transactions
- Version 1, up to 4,096 bytes. Fetch with maxSupportedTransactionVersion: 1.
Classifications
Every cell in the visibility matrix gets exactly one of three labels, with an icon and a word, never color alone.
A specific RPC field or decoded plaintext instruction field carries the value. The report cites the exact path, such as transact.interfaceTransfers[0].amount (bytes 60..68) or meta.postTokenBalances[accountIndex=4].mint.
Ringdiff recognized the Ring instruction layout, the field exists there only as a commitment or ciphertext, and no balance change contradicts it. For a transfer: zero interface transfers, no mint account, no token or pool SOL movement.
Evidence is incomplete, the instruction is not supported (for example mergeTransact), or the field is a commitment that might be matchable. A field missing from parsed RPC output does not establish encryption.
Evidence and inference
Direct evidence is a value read at a cited path in the standard RPC response. Inferences are listed separately and phrased as possibilities. For example, a deposit and a withdrawal with matching public amounts minutes apart suggest a link; Ringdiff states the two amounts and the gap as facts and the link as an inference. Inferences never change a classification or a verdict.
Privacy boundaries
- This report covers on-chain exposure to a public observer using standard Solana RPC. It does not use viewing keys, indexer data or wallet state.
- The default Ring is confidential, not anonymous: sender and recipient wallet addresses can be public even when asset and amount are encrypted.
- Proofs come from a remote prover. Ringdiff's SDK client attests the Nitro enclave and encrypts every request to it, but that prover is a separate data-access boundary this report does not measure.
- Inferences are possibilities drawn from public facts. They are listed apart from direct evidence and never change a classification.
- Deposits name their recipient by an owner hash, Poseidon(ownerProofInputHash, nullifierPublicKey). Both inputs are published in User Registry records, so Ringdiff labels the deposit recipient Unknown rather than Encrypted.
- Reports and exports carry only public evidence and derived classifications. Signing seeds, viewing keys, proof witnesses and API credentials never enter a report, log or response, and every report passes a redaction check before it is returned or saved.
Policies
Write a policy as a sentence that names fields (sender, recipient, asset, amount) and a requirement (confidential or public): asset and amount must be confidential for this payment route
. Add a rejection is acceptable
to score an SDK rejection as a pass. Or use JSON:
{
"id": "checkout-confidential",
"statement": "Asset and amount must be confidential for this payment route.",
"appliesTo": "payment",
"require": { "asset": "confidential", "amount": "confidential" },
"onRejected": "inconclusive"
}
onRejected decides how a route the SDK refused before submission is scored. The default is inconclusive: with no transaction there is no evidence either way. A run that did not complete can never pass.
CLI
# Inspect any finalized mainnet transaction as a public observer
npx ringdiff inspect <signature>
# What the chain says about an address; exit 1 if amounts are public
npx ringdiff exposure <address> --limit 12 --fail-on amounts
# Decode base58 Ring instruction data with byte ranges
npx ringdiff decode <instruction-data>
# Score a recorded report (exit 0 pass, 1 violation, 2 inconclusive)
npx ringdiff check reports/checkout.json --policy ringdiff.policy.json --out ringdiff-report.json
# Same, with a plain-language policy
npx ringdiff check reports/checkout.json --require "asset and amount must be confidential"
# Compare main with a pull request: exit 1 if any field became more exposed
npx ringdiff diff reports/main.json reports/pr.json
0- Every required assertion holds.
1- At least one required field is visible when it must be confidential, or the reverse.
2- Inconclusive: unknown evidence, a rejected route under the default policy, a partial run, or the command could not execute.
Report JSON is stable: keys are sorted and the schema is versioned (schemaVersion: 1), so diffs between runs are meaningful and the file works as a GitHub Actions artifact. Fixtures in fixtures/reports cover each exit code.
GitHub Actions
The repo’s own workflow, .github/workflows/ringdiff.yml, runs lint, types, tests and build, then proves all three exit codes against the fixtures, including the public-withdrawal fixture that must fail. Add this job to your app’s repo:
name: payment-privacy
on: [pull_request]
jobs:
ringdiff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
# The confidential route must pass
- run: >
npx --yes ringdiff@0.1 check reports/checkout.json
--policy ringdiff.policy.json
--out ringdiff-report.json
# And must not regress against main
- run: npx --yes ringdiff@0.1 diff reports/main.json ringdiff-report.json
- uses: actions/upload-artifact@v4
if: always()
with:
name: ringdiff-report
path: ringdiff-report.json
Under Actions, Ringdiff writes a Markdown summary to $GITHUB_STEP_SUMMARY and an error, warning or notice annotation for the verdict.
Wallet sign-in
The lab and its APIs need a signed-in wallet, so rate limits follow a wallet instead of an IP address. Sign in from the header with any Wallet Standard Solana wallet, such as Phantom, Solflare or Backpack. The CLI never asks for a wallet.
- Your wallet shares its public address.
- The server writes a sign-in message for that address with a single-use nonce and a five-minute expiry, and pins it in a signed, httpOnly cookie.
- Your wallet signs the message with
solana:signMessage. Ringdiff never asks for a transaction signature, so sign-in cannot move funds. - The server rebuilds the message from its own cookie, verifies the Ed25519 signature against the address, and sets a 12-hour session cookie that holds only the address.
Set RINGDIFF_SESSION_SECRET (32 characters or more) in production so sessions survive new deploys. Without it, each build generates its own key, so every server instance of a deploy agrees and sign-ins end when you redeploy. Signatures and messages are never logged or stored.
Troubleshooting
RPC_NOT_FOUND- Mainnet has no finalized transaction with that signature yet. Check that you copied the whole signature, and wait a few seconds if the transaction was just sent: Ringdiff only reads finalized transactions.
RPC_RATE_LIMITED or RPC_TIMEOUT- The public mainnet RPC throttles bursts. Ringdiff retries within a bounded budget, then reports the read as rate limited or timed out, and the verdict as inconclusive. Set RINGDIFF_MAINNET_RPC_URL to a Helius URL to raise limits; the key stays server-side and is redacted from output.
A field shows Unknown- Ringdiff could not prove the classification from public data. A common case: every output of a transfer names its signer, so a separate recipient cannot be told apart from change. Unknown never satisfies a required confidentiality assertion, so the verdict is inconclusive (exit 2) rather than pass.
WALLET_RECIPIENT_NOT_REGISTERED from the SDK in your app- The SDK refuses a private transfer to an address with no User Registry record, and it does not fall back to a withdrawal. Ask the recipient to finish Ring setup, or offer an explicit, disclosed public withdrawal. Check that route with Ringdiff before you ship it.
SIGN_IN_REQUIRED in the lab- The lab needs a signed-in Solana wallet. Your session lasts 12 hours. Sign in again from the header; it signs a message, never a transaction.
Still stuck? Run npx ringdiff doctor. It checks each service and prints the exact failing code. Then compare with the live lab.