> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluton.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposit screening

> Why every deposit into the pool carries a signed screening of the depositor, how one is obtained and checked, and what happens when screening is unavailable.

Every unit of value enters into the pool through one of two pulls, and each one needs a **screening** of the depositor: a signed statement, by the address the pool trusts, that this wallet may deposit.

* `deposit(proof, extData, screening)` for a TOKEN deposit;
* `requestDeposit(asset, amount, screening)` for an eTOKEN deposit. Verifying and finalizing that receipt need nothing more, because the receipt belongs to the depositor alone.

Nothing else is screened. `transact`, the entry point for private transfers and withdrawals, refuses any positive `extAmount` with `DepositRequiresScreening`, so relayed jobs never carry a screening and the relayer never has to handle one. Screening sits at the entry to the anonymity set and nowhere else.

## What a screening is

A screening is three fields — a random `nonce`, an expiry `expiresAt` and a `signature` — and that signature is the pool's `screeningSigner`'s EIP-712 signature of this message:

```text theme={null}
DepositScreening(address depositor, bytes32 nonce, uint64 expiresAt)
```

in the pool's own domain: name `PrivacyPool`, version `1`, this chain id, the pool's own address. Referral bonuses are signed in the same domain, under a different type.

Before the proof is checked and before anything is pulled, the pool recovers the signature with `msg.sender` as the `depositor`, and requires that

* the signer is the address the pool names as `screeningSigner` now (otherwise `InvalidScreeningSignature`, or `ScreeningSignerUnset` when the pool names nobody);
* the screening has not expired, and does not expire more than `MAX_SCREENING_TTL` — one hour — from now (`ScreeningExpired`);
* its `nonce` has not been spent yet (`ScreeningUsed`).

It then spends the `nonce` (`screeningUsed(nonce)`) and logs `DepositScreened(depositor, nonce)`.

So one screening is good **once, from one wallet, into this pool, on this chain, under the signer the pool trusts**. Nobody else can use yours, because the depositor is `msg.sender` rather than a field anyone chooses. It is deliberately not part of the zero-knowledge proof: swapping it for another screening of the same depositor changes nothing, and because a spent nonce is undone when the surrounding transaction reverts, a deposit that fails later leaves its screening unspent and reusable. Only a 65-byte signature in canonical (low-s) form counts.

## The flow through the API

The browser never talks to the screening provider and never holds its credentials. It names its wallet to Fluton's backend API:

```text theme={null}
POST /screening/attestations   { "depositor": "0x…" }
```

The API screens that address with **CipherOwl** and answers one of three things: `status: "screened"` with the signed screening, `status: "refused"` with a reason code, or HTTP 503 when it could not get a clear answer at all. Anything short of a clear answer — a network error, a timeout, an HTTP error, a malformed body, an answer about another address or given under another configuration — becomes that 503, and nothing is signed. Screening never fails open.

A refusal says only that the address cannot deposit into the pool. What the screener found stays on the server, in the decision record the API keeps for every answer it gives.

The API does not ask CipherOwl for every request. It reuses CipherOwl's latest answer about an address for up to a day by default, counted from the moment CipherOwl gave it, and concurrent requests about the same address share one call. A reused answer still buys a screening of its own, with a new `nonce` and the full validity. Reuse has a price: an address that CipherOwl flags after it was answered clear keeps getting screenings until that answer ages out. The API's operator sets how long an answer is reused, and can cap the calls made in a day and in a month. Once a cap is spent, an address without a reusable answer gets the same 503 until earlier calls age out.

The operator can also answer for an address itself. An address on the operator's denylist is always refused, and one on its allowlist always gets a screening. Neither is sent to CipherOwl. The allowlist is the operator's own word that an address may deposit, so it carries the same trust as the signing key.

The SDK asks **first**, before rebuilding the tree, proving anything or approving any token, so a refused wallet learns it at once and spends nothing on gas or proving time. It then checks who signed the screening against the pool's current `screeningSigner`, so a screening service whose key the pool does not trust is caught there too, rather than by a reverted deposit. A screening is valid for 30 minutes by default. Just before sending, the SDK fetches a new one if less than a minute of validity is left by the chain's own clock, and once more if the pool calls the screening stale during simulation. Stale means expired, or spent in the meantime. A refusal is a different thing: it is shown as screening's answer rather than as a failure, and it is final for that wallet.

> [!NOTE]
>
> A refusal is about the depositing address, not about the amount or the token. The only way past it
> is a wallet that screening accepts.

## Trust and failure modes

The pool takes the screening signer's verdict as it is, so screening is as strong as two keys: the signer's, and the owner's, which names it with `setScreeningSigner`. The signer's key never sends a transaction and cannot move funds, but whoever holds it can let any address deposit. The owner **cannot switch screening off**: the signer may never be the zero address. Naming a new signer refuses, at once, every screening the old one signed. A pool upgraded from code that predates screening names nobody and refuses every deposit until its owner names a signer.

If the API or CipherOwl is unreachable, deposits stop and nothing else does. Transfers, withdrawals, `verifyDeposit` and `finalizeDeposit` never need a screening, so money already inside the pool keeps moving. And because screening applies at entry only, a depositor flagged after depositing is already in the anonymity set.

**What the screener learns** is what a deposit makes public anyway: the depositor's address, the pool and the chain. Each screening a deposit spends is logged on-chain as `DepositScreened`, naming the depositor and the nonce, and the API records every decision (screened, refused or unavailable), together with the screening it signed and whether it asked CipherOwl, reused an earlier answer or took the answer from one of its lists, in its own database for the audit trail. [What stays public](https://docs.fluton.io/concepts/privacy-model.md) puts that next to everything else a deposit reveals.

Screening is the first thing the deposit flow does, so it shows up in every deposit path: see [TOKEN and eTOKEN](https://docs.fluton.io/concepts/token-formats.md) for the two-step eTOKEN route it guards and [Contracts](https://docs.fluton.io/reference/contracts.md) for the exact signatures and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.