Wallet & dApp Integration

User enters recipient + amount
      │
      ▼
┌─────────────────────────┐
│  Screen recipient       │──── High risk? → Show warning
│  (Address Risk Score)   │
└─────────────────────────┘
      │
      ▼
  User constructs transaction
      │
      ▼
┌─────────────────────────┐
│  Scan unsigned tx       │──── High severity? → Show warning
│  (Transaction Scan)     │     Findings / failed sim? → Show detail
└─────────────────────────┘
      │
      ▼
  User reviews risk info → Confirm or Cancel
      │
      ▼
  Sign and broadcast

async function screenRecipient(address: string, network: string = 'solana') {
  const params = new URLSearchParams({ address, network });
  const response = await fetch(
    `https://api.range.org/v1/risk/address?${params}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  const data = await response.json();

  return {
    score: data.riskScore,
    level: data.riskLevel,
    reasoning: data.reasoning,
    isSafe: data.riskScore <= 3,
    isAttributed: data.attribution !== null,
    attribution: data.attribution,
  };
}

async function scanUnsignedTransaction(encodedTransaction: string) {
  const response = await fetch(
    'https://api.range.org/v2/risk/transaction/scan',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        network: 'solana',
        transaction: encodedTransaction,
        encoding: 'base64',
      }),
    },
  );
  return response.json();
}

function checkScanRisk(scan: {
  severity: string;
  findings: { signal: string; caption: string }[];
  meta: { poisoning_screened: boolean };
}) {
  const warnings: string[] = [];

  if (scan.severity !== 'none' && scan.severity !== 'low') {
    warnings.push(`Transaction severity: ${scan.severity}`);
  }

  for (const finding of scan.findings || []) {
    if (finding.signal === 'large-transfer') continue; // informational only
    warnings.push(finding.caption || finding.signal);
  }

  if (!scan.meta.poisoning_screened) {
    warnings.push('Recipients were not checked for address poisoning');
  }

  return {
    hasRisk: warnings.length > 0,
    warnings,
  };
}

┌─────────────────────────────────────────┐
│  Transaction Preview                    │
│                                         │
│  Sending: 100 USDC                      │
│  To: 7xKX...3mN2                        │
│  Fee: ~0.00025 SOL                      │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │ ⚠ Recipient Risk: Medium (5/10) │    │
│  │ 3 hops from flagged address     │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Scan severity: high                    │
│  Intent: Swap 100 USDC for SOL          │
│                                         │
│  Balance Changes:                       │
│  · USDC: -100.00                        │
│  · SOL:  -0.00025 (fee)                 │
│                                         │
│  [Cancel]              [Send Anyway]    │
└─────────────────────────────────────────┘

async function screenWithFallback(address: string, network: string) {
  try {
    const result = await Promise.race([
      screenRecipient(address, network),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('timeout')), 5000),
      ),
    ]);
    return result;
  } catch (error) {
    // If the risk check fails, inform the user but don't block
    return {
      score: null,
      level: 'unknown',
      reasoning: 'Risk check unavailable - proceed with caution',
      isSafe: null,
    };
  }
}

async function protectedSend(
  recipient: string,
  amount: number,
  network: string,
) {
  // Screen the recipient
  const risk = await screenWithFallback(recipient, network);

  if (risk.score >= 8) {
    // Require explicit user confirmation for high-risk
    const confirmed = await showHighRiskWarning(risk);
    if (!confirmed) return { status: 'cancelled' };
  } else if (risk.score >= 4) {
    // Show warning for medium-risk
    const confirmed = await showMediumRiskWarning(risk);
    if (!confirmed) return { status: 'cancelled' };
  }

  // Build and encode the transaction (see Transaction Simulation guide for SDK examples)
  const transaction = await buildTransaction(recipient, amount);
  const encoded = encodeTransactionBase64(transaction);

  // Scan before signing
  const scan = await scanUnsignedTransaction(encoded);

  if (!scan.simulation || scan.simulation.simulation_success === false) {
    return { status: 'error', reason: 'Simulation failed' };
  }

  const scanRisk = checkScanRisk(scan);
  if (scanRisk.hasRisk) {
    const confirmed = await showExploitWarning(scanRisk.warnings);
    if (!confirmed) return { status: 'cancelled' };
  }

  // Show confirmation with all risk data
  const confirmed = await showConfirmation({ risk, scan });
  if (!confirmed) return { status: 'cancelled' };

  // Sign and send
  return await signAndSend(transaction);
}