Add privacy advice to your RAILGUN wallet

railcheck tells a user if an amount can link a shield to an unshield. The user gets this advice before they send.

For wallet teams#

• It runs in your wallet. The amount and the answers stay on the device of the user. railcheck receives no data.
• It needs no server from us. Your wallet reads the shields from your own RPC. railcheck runs no server for you.
• It never asks for an address. The wallet gives three answers: yes, no or not sure.
• It is free. The license is MIT. You can use, change and fork the code.
• It works in a real flow. On 17 October 2026, a wallet built its own pool, got advice, and sent a shield and an unshield on Sepolia. Both transactions are confirmed.

This preview covers RAILGUN WETH on Ethereum mainnet and on Sepolia.

Add the check to your wallet#

Install#

npm install @railcheck/core @railcheck/builder @railcheck/kohaku

The packages need Node.js 22 or later, or a modern browser. They have no runtime dependencies.

Step 1: Build the pool#

The builder reads RAILGUN shield events from your RPC. The first run reads 180 days. Each subsequent run reads only the new blocks.

import { buildPool, makeRpc } from "@railcheck/builder";
import { prepare } from "@railcheck/core";

const { deposits, snapshot, asset } = await buildPool({
  chain: "mainnet",
  rpc: makeRpc({ urls: [YOUR_RPC_URL] }),
  store, // { get: async () => state, set: async (state) => {} }
});
const pool = prepare(deposits, { snapshot, asset });

Important: Always give snapshot and asset to prepare. Without them, the engine cannot make sure that the data is recent and on the correct chain.

Where the builder runs#

With the two options, the advice runs in the app. The amount and the answers of the user stay on the device.

On the device, start the build when the app starts. Do not start it when the user opens the send screen.

buildPool options#

buildPool gives { deposits, snapshot, asset }.

Note: The first run needs eth_getLogs for 180 days. Many free RPCs refuse this on mainnet. Use a paid RPC.

Step 2: Get advice#

import { plan, parseAmount } from "@railcheck/core";

const advice = plan(pool, {
  action: "unshield",
  amount: parseAmount("1.0731"),
  constraint: "flexible",
  context: { addressReuse: false, pastTransfer: undefined, restOfDeposit: false },
  balance: parseAmount("5"),
});

plan options#

parseAmount("1.0731") changes an ETH string to wei. formatWei(wei) changes it back.

Context#

The context applies to an unshield only. Give the answers that the wallet knows. Set the other answers to undefined.

The value undefined means "not sure". railcheck does not use it as "no". railcheck does not use it as a link.

Step 3: Use the Kohaku adapter#

The function guard() wraps a Kohaku-style plugin. It gets advice before the plugin prepares the transaction.

import { guard } from "@railcheck/kohaku";

const safe = guard(plugin, {
  pool,
  constraint: "fixed",
  getContext: async (assetAmount, to) => ({ addressReuse: to === shieldAddress }),
  onAdvice: async (advice) => null, // Show the advice. Return a new amount, or null.
});

await safe.prepareUnshield({ asset: { __type: "erc20", contract: WETH }, amount }, to);

guard options#

The plugin prepares the transaction one time, with the amount from onAdvice. The adapter does not change the other plugin functions. An asset that the pool does not cover gives not-checked. It does not stop the call.

What the result contains#

Example result#

plan gives this result. This example is a shield of 1.0731 ETH with constraint: "flexible". Some fields are not shown.

{
  "format": "railcheck.advice/1",
  "action": "shield",
  "constraint": "flexible",
  "assessment": {
    "status": "attention",
    "amounts": { "shieldInput": "1073100000000000000", "poolCredit": "1070417250000000000" },
    "deposits": 0,
    "senders": null,
    "score": 97,
    "band": "Critical",
    "findings": [{ "code": "amount-stands-out" }],
    "unknown": [],
    "notes": ["timing-not-covered", "senders-unknown"],
    "snapshot": { "chainId": 1, "block": 26210554, "time": 1792219379, "grouping": "none" }
  },
  "alternatives": [
    { "status": "clear", "amounts": { "shieldInput": "1000000000000000000" }, "deposits": 71, "score": 1, "band": "Low" }
  ],
  "searched": { "from": "965790000000000000", "to": "1180410000000000000", "candidates": 1, "limited": false }
}

Amounts are bigint values in wei. toJSON(advice) changes them to strings.

Result fields#

Assessment fields#

A not-checked assessment has no score, band or amounts.

Status values#

Finding codes#

Note codes#

How alternatives are chosen#

You get alternatives only with constraint: "flexible", and only when the amount causes the finding. An address link gives no alternatives.

• Shield: common pool amounts within ±10% of the request, nearest first.
• Unshield: common amounts from 70% to 100% of the request, largest first. The engine scores a maximum of budget amounts.

How to show the result#

1. Do not show "clear" or a green color when the status is not-checked.
2. Do not give an answer for the user. If the wallet does not know the answer, set it to undefined.
3. If the constraint is "fixed", show the advice. Do not change the amount.
4. If the user selects a new amount after the plugin prepared the transaction, prepare the transaction again.

What the check does not cover#

• The score is the output of a model. It is not a measured probability of identification.
• The check covers amounts and the three questions only. It does not cover time, IP addresses or data that is not on the chain.
• The check covers 180 days, and sets of a maximum of 3 shields.

For the method and all limits, see How it works.