Ringdiff

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.

Terminal
# 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:

From source
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.

Publicly visible

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.

Encrypted

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.

Unknown

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:

ringdiff.policy.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

Terminal
# 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:

.github/workflows/payment-privacy.yml
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.

  1. Your wallet shares its public address.
  2. 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.
  3. Your wallet signs the message with solana:signMessage. Ringdiff never asks for a transaction signature, so sign-in cannot move funds.
  4. 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.