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

# Privacy Protocol Screening

> Screen wallets before deposits to prevent tainted funds from entering your privacy protocol on Solana.

Privacy protocols on Solana, including mixers, privacy pools, and confidential
transfer programs, need to prevent sanctioned or stolen funds from entering the protocol
while preserving privacy for legitimate users. Accepting those funds
affects the entire pool and exposes the project to regulatory risk.

Use Range's [Address Risk Score](https://docs.range.org/risk-api/risk/get-address-risk-score.md) to screen
the depositor's wallet before accepting funds. Reject high-risk wallets before
they deposit.

> [!NOTE]
>
> **Prerequisites:** You need a [Risk API key](https://docs.range.org/introduction/quickstart.md)
> and familiarity with the [Address Risk
> Score](https://docs.range.org/risk-api/risk/get-address-risk-score.md) endpoint. For onchain
> enforcement, see the [SigVerify Onchain
> Attestation](https://docs.range.org/risk-api/guides/sigverify-onchain-attestation.md) guide.

***

## Why Screen Deposits?

| Without screening | With screening |
| - | - |
| Stolen funds enter your privacy pool | Stolen funds are rejected before deposit |
| OFAC-sanctioned addresses mix freely | Sanctioned addresses are blocked before deposit |
| Your protocol becomes a laundering vector | Illicit funds are excluded for legitimate users |
| Regulators target your protocol | Demonstrable compliance controls |
| Honest users' funds are tainted by association | Pool integrity is preserved |

Screening depositors while leaving activity inside the pool private lets you
maintain privacy guarantees for legitimate users while blocking bad actors.

***

## Architecture

```
User wants to deposit
      │
      ▼
┌──────────────────────────┐
│  Screen depositor wallet │
│  (Address Risk Score)    │
│                          │
│  riskScore 1-10          │
│  Includes sanctions +    │
│  ML + proximity analysis │
└──────────────────────────┘
      │
      ├── Score ≥ 7 ──────► REJECT deposit
      │                     Show reason
      │
      ├── Score 4-6 ──────► FLAG for review
      │                     Optional: require
      │                     additional verification
      │
      └── Score 1-3 ──────► ALLOW deposit
                            Proceed normally
```

> [!NOTE]
>
> Address Risk Score already includes sanctions and blacklist screening. You do
> not need a separate sanctions check - OFAC-flagged and stablecoin-blacklisted
> addresses are factored into the risk score.

***

## Step 1: Screen the Depositor

Before accepting a deposit, check the wallet's risk score. This single API call
covers malicious proximity, ML-based behavioral analysis, sanctions, and
blacklist screening.

```bash theme={null}
curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=DEPOSITOR_ADDRESS" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```typescript theme={null}
async function screenDepositor(address: string) {
  const params = new URLSearchParams({
    address,
    network: 'solana',
  });

  const response = await fetch(
    `https://api.range.org/v1/risk/address?${params}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );

  return response.json();
}
```

### Example Response - Flagged Wallet

```json theme={null}
{
  "riskScore": 9,
  "riskLevel": "Extremely high risk",
  "numHops": 1,
  "maliciousAddressesFound": [
    {
      "address": "SuspiciousAddr...",
      "distance": 1,
      "name_tag": "Exploit Funds",
      "entity": null,
      "category": "hack_funds"
    }
  ],
  "reasoning": "Address is 1 hop from known exploit funds.",
  "attribution": null
}
```

This wallet is 1 hop from known hack funds - it should be rejected.

***

## Step 2: Make a Deposit Decision

```typescript theme={null}
interface RiskData {
  riskScore: number;
  riskLevel: string;
  reasoning: string;
  attribution: { name_tag: string; entity: string } | null;
}

interface DepositDecision {
  decision: 'allow' | 'reject' | 'flag';
  reason: string;
}

function evaluateDeposit(riskData: RiskData): DepositDecision {
  const { riskScore, reasoning, attribution } = riskData;

  // Known system addresses and verified entities are always safe
  if (attribution) {
    return {
      decision: 'allow',
      reason: `Verified entity: ${attribution.name_tag} (${attribution.entity})`,
    };
  }

  // High risk - reject
  if (riskScore >= 7) {
    return {
      decision: 'reject',
      reason: `Risk score ${riskScore}/10: ${reasoning}`,
    };
  }

  // Medium risk - flag for review or require additional verification
  if (riskScore >= 4) {
    return {
      decision: 'flag',
      reason: `Elevated risk (${riskScore}/10): ${reasoning}`,
    };
  }

  // Low risk - allow
  return {
    decision: 'allow',
    reason: 'Address screening passed',
  };
}
```

***

## Step 3: Integrate into Your Deposit Flow

### Off-Chain (Backend / Frontend)

Screen wallets in your dApp frontend or backend before constructing the deposit
transaction:

```typescript theme={null}
async function handleDeposit(depositorAddress: string, amount: number) {
  // Screen the wallet
  const riskData = await screenDepositor(depositorAddress);
  const evaluation = evaluateDeposit(riskData);

  if (evaluation.decision === 'reject') {
    return {
      status: 'rejected',
      message:
        'This wallet has been flagged for connections to malicious activity. ' +
        'Deposit not permitted.',
    };
  }

  if (evaluation.decision === 'flag') {
    // Optional: require additional verification for medium-risk wallets
    const verified = await requestAdditionalVerification(depositorAddress);
    if (!verified) {
      return {
        status: 'rejected',
        message: 'Additional verification required.',
      };
    }
  }

  // Proceed with deposit
  return await executeDeposit(depositorAddress, amount);
}
```

### Onchain (Solana Program)

For protocol-level enforcement that can't be bypassed by calling the program
directly, use
[Onchain Risk Verifier: SigVerify Attestation](https://docs.range.org/risk-api/guides/sigverify-onchain-attestation.md).
Your backend screens the wallet and signs an attestation, and your Solana
program verifies the Ed25519 signature before it accepts the deposit:

```rust theme={null}
// In your deposit instruction handler, after verifying the attestation's
// signature, signer, and freshness. This assumes you extended the signed
// message to carry the risk score as a fourth field (see "Adding the Risk
// Score Onchain" in the SigVerify guide):
// "{timestamp}_{pubkey}_{riskCallId}_{riskScore}", riskScore on the 1-10 scale.
// `parts` is the verified message split on '_'.
require_eq!(parts.len(), 4, ErrorCode::InvalidMessageFormat);
// An unreadable score fails closed.
let risk_score: u8 = parts[3].parse().unwrap_or(u8::MAX);

// Reject deposits from high-risk wallets
if risk_score >= 7 {
    return Err(ErrorCode::HighRiskDepositor.into());
}

// Proceed with deposit logic
```

> [!TIP]
>
> Onchain enforcement is stronger than off-chain screening alone. Users can
> bypass your frontend, but they can't bypass your program's instruction logic.
> For maximum protection, use both: off-chain screening for UX (show the user
> why they're blocked) and onchain verification as the enforcement layer.

***

## Choosing Your Risk Threshold

The right threshold depends on your protocol's risk tolerance and regulatory
posture:

| Threshold | Rejects | Trade-off |
| :-: | - | - |
| **Score ≥ 8** | Only directly malicious or 1-hop addresses | Permissive - blocks clear threats, allows most users |
| **Score ≥ 7** | Addresses within 2 hops of malicious actors | Balanced - recommended starting point |
| **Score ≥ 6** | Addresses within 2 hops (with multiple malicious connections) | Strict - fewer false negatives, more false positives |
| **Score ≥ 4** | Addresses within 3 hops | Very strict - suitable for regulated environments |

> [!WARNING]
>
> Setting the threshold too low (e.g., ≥ 3) will reject a significant number of
> legitimate users. Many clean addresses are naturally within 4-5 hops of
> flagged addresses through shared exchange or program interactions. Start with
> ≥ 7 and adjust based on your data.

***

## Handling Edge Cases

### What If the Risk Check Fails?

Network errors or API timeouts shouldn't block legitimate deposits indefinitely.
Implement a fallback policy:

```typescript theme={null}
async function screenWithFallback(address: string) {
  try {
    const result = await Promise.race([
      screenDepositor(address),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('timeout')), 5000),
      ),
    ]);
    return evaluateDeposit(result);
  } catch (error) {
    // Fallback: allow with logging for manual review
    console.warn(`Risk check failed for ${address}: ${error}`);
    return {
      decision: 'allow',
      reason: 'Risk check unavailable - allowed with manual review flag',
      requiresReview: true,
    };
  }
}
```

### Known System Addresses

Some addresses that interact with your protocol will be system programs, token
programs, or exchange hot wallets. These will have an `attribution` field in the
response - use it to fast-path known entities:

```typescript theme={null}
if (riskData.attribution) {
  // Verified non-malicious entity - skip further checks
  console.log(`Known entity: ${riskData.attribution.name_tag}`);
  return { decision: 'allow' };
}
```

### Rate Limits

If you're processing high deposit volume, see
[Rate Limits & Plans](https://docs.range.org/resources/errors-and-rate-limits.md) for scaling options.

***

## Compliance Considerations

Screening deposits demonstrates that your protocol has taken reasonable steps to
prevent misuse. Document your screening policy and keep records:

* **Policy document** - Define your risk threshold and what happens when a
  deposit is rejected
* **Audit log** - Store the risk score, reasoning, and decision for each
  screened deposit
* **Threshold rationale** - Document why you chose your threshold and any
  adjustments over time
* **False positive handling** - Have a process for users to contest rejections

```typescript theme={null}
async function logScreeningResult(
  depositor: string,
  riskData: RiskData,
  decision: DepositDecision,
) {
  await complianceDB.insert({
    timestamp: new Date().toISOString(),
    depositor_address: depositor,
    risk_score: riskData.riskScore,
    risk_level: riskData.riskLevel,
    reasoning: riskData.reasoning,
    decision: decision.decision,
    decision_reason: decision.reason,
  });
}
```

***

## What's Next

> [card] [Address Risk Score](https://docs.range.org/risk-api/risk/get-address-risk-score.md)
>
> Full endpoint reference with scoring logic and examples.

> [card] [Onchain Risk Verifier: SigVerify Attestation](https://docs.range.org/risk-api/guides/sigverify-onchain-attestation.md)
>
> Enforce risk checks directly in your Solana program.

> [card] [Compliance Pipeline](https://docs.range.org/risk-api/guides/compliance-screening-pipeline.md)
>
> Build a full compliance screening workflow.

> [card] [Supported Chains](https://docs.range.org/risk-api/product-info/supported-chains.md)
>
> See which networks are supported for address risk scoring.


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