Privacy Protocol Screening

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

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=DEPOSITOR_ADDRESS" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer your_api_key_here"

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();
}

{
  "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
}

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',
  };
}

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);
}

// In your deposit instruction handler:
let risk_score = verified_feed.value(); // 0–100 scale (original 0–10 × 10)

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

// Proceed with deposit logic

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,
    };
  }
}

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

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,
  });
}