main.php

<?php

/**
 * Клиент API AML-скоринга Atlorium — скрининг криптокошелька по адресу и сети.
 *
 * Запуск (работает сразу, без регистрации — на демо-ключе):
 *   php main.php
 *   php main.php 0x26a5919cd0392df875a53873b0323c42094bb216 ETH
 *
 * Боевой ключ: получить на https://atlorium.com и положить в переменную окружения
 * ATLORIUM_API_KEY. Код при этом не меняется.
 */

declare(strict_types=1);

/**
 * Публичный демо-ключ. С ним API отвечает правдоподобными МОКАМИ (не реальными
 * данными) — чтобы можно было встроить и протестировать интеграцию до оплаты.
 * Ответы детерминированы: один и тот же запрос всегда даёт один и тот же результат,
 * поэтому на них можно писать стабильные тесты.
 */
const SANDBOX_KEY = 'ak_sandbox_demo_mockdata_v1';

const TIMEOUT = 60;

/** Ошибка API: HTTP-код разложен в человекочитаемую причину. */
final class AtloriumError extends RuntimeException
{
    private const REASONS = [
        400 => 'Адрес или сеть не указаны либо имеют неверный формат (неподдерживаемая сеть, некорректный адрес)',
        401 => 'API-ключ отсутствует, просрочен или недействителен',
        402 => 'Недостаточно кредитов на балансе — пополните на https://atlorium.com',
        404 => 'Объект не найден',
        429 => 'Превышен лимит запросов — повторите позже',
        503 => 'Сервис AML-скоринга временно недоступен (за сбой на своей стороне мы не списываем деньги)',
    ];

    public function __construct(public readonly int $status, string $body)
    {
        $reason = self::REASONS[$status] ?? 'Неизвестная ошибка';
        parent::__construct(sprintf(
            'HTTP %d: %s. Ответ сервера: %s',
            $status,
            $reason,
            mb_substr($body, 0, 200)
        ));
    }
}

final class AmlClient
{
    private string $apiKey;
    private string $baseUrl;

    public function __construct(?string $apiKey = null, ?string $baseUrl = null)
    {
        $this->apiKey = $apiKey ?? (getenv('ATLORIUM_API_KEY') ?: SANDBOX_KEY);
        $this->baseUrl = $baseUrl ?? (getenv('ATLORIUM_BASE_URL') ?: 'https://atlorium.com');
    }

    public function isSandbox(): bool
    {
        return $this->apiKey === SANDBOX_KEY;
    }

    /**
     * AML-скрининг кошелька: балл риска 0–100, санкции и PEP, источники и назначение
     * средств, контрагенты.
     *
     * Это POST с JSON-телом, а не GET: адрес и сеть уходят в теле запроса.
     * Тарифицируется только успешный скрининг — неверный ввод и недоступность
     * источника денег не списывают.
     *
     * @return array<string, mixed>
     */
    public function screenWallet(string $walletAddress, string $blockchain): array
    {
        $payload = json_encode(
            ['walletAddress' => $walletAddress, 'blockchain' => $blockchain],
            JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE
        );

        return $this->request('/api/aml/screen', [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $payload,
        ], ['Content-Type: application/json']);
    }

    /**
     * Проверка ФОРМАТА адреса и поддержки сети — без обращения к блокчейну.
     *
     * Отвечает на вопрос «можно ли вообще скринить такую пару адрес+сеть», а не
     * «существует ли этот адрес». Дешёвая предварительная проверка ввода.
     *
     * @return array<string, mixed>
     */
    public function validateWallet(string $walletAddress, string $blockchain): array
    {
        $query = http_build_query([
            'walletAddress' => $walletAddress,
            'blockchain' => $blockchain,
        ]);

        return $this->request('/api/aml/validate?' . $query, []);
    }

    /**
     * @param array<int, mixed> $options
     * @param list<string> $headers
     * @return array<string, mixed>
     */
    private function request(string $path, array $options, array $headers = []): array
    {
        $curl = curl_init($this->baseUrl . $path);
        curl_setopt_array($curl, $options + [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => TIMEOUT,
            CURLOPT_HTTPHEADER => array_merge([
                'Authorization: Bearer ' . $this->apiKey,
                'Accept: application/json',
            ], $headers),
        ]);

        $body = curl_exec($curl);
        if ($body === false) {
            $error = curl_error($curl);
            curl_close($curl);
            throw new RuntimeException("Сетевая ошибка: {$error}");
        }

        $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
        curl_close($curl);

        if ($status !== 200) {
            throw new AtloriumError($status, (string) $body);
        }

        return json_decode((string) $body, true, 512, JSON_THROW_ON_ERROR);
    }
}

// ── Применение данных: комплаенс-гейт перед выводом или зачислением средств ────
// Карточка скрининга сама по себе — просто JSON. Ценность появляется, когда по ней
// принимают решение. Ниже — гейт из трёх исходов: ALLOW / REVIEW / BLOCK.

// ВНИМАНИЕ: пороги ниже — отправная точка, а не универсальная истина.
// Настраивайте их под свою риск-политику, юрисдикцию и аппетит к риску.
const SCORE_BLOCK = 75;          // балл >= этого — блокируем
const SCORE_REVIEW = 40;         // балл >= этого — на ручную проверку
const EXPOSURE_ALERT_PCT = 5.0;  // доля средств из «плохой» категории, с которой это уже сигнал

/**
 * Категории источников/назначения средств, которые сами по себе поднимают флаг.
 * Сравнение по подстроке — коды категорий у провайдеров различаются в написании.
 */
const HIGH_RISK_CATEGORY_KEYWORDS = [
    'sanction', 'mixer', 'tumbler', 'darknet', 'ransomware',
    'stolen', 'scam', 'fraud', 'terror', 'illicit', 'hack', 'phishing',
];

/** Исход комплаенс-гейта: чем больше вес, тем строже. */
const DECISION_RANK = ['ALLOW' => 0, 'REVIEW' => 1, 'BLOCK' => 2];

function isHighRiskCategory(?string $category): bool
{
    $lowered = mb_strtolower($category ?? '');
    foreach (HIGH_RISK_CATEGORY_KEYWORDS as $keyword) {
        if (str_contains($lowered, $keyword)) {
            return true;
        }
    }

    return false;
}

/**
 * Комплаенс-гейт: пропустить операцию, отправить на ручную проверку или заблокировать.
 *
 * @param array<string, mixed> $result
 * @return array{decision: string, factors: list<string>}
 */
function complianceGate(array $result): array
{
    $decision = 'ALLOW';
    $factors = [];

    // Решение может только ужесточаться: ALLOW → REVIEW → BLOCK.
    $escalate = static function (string $next) use (&$decision): void {
        if (DECISION_RANK[$next] > DECISION_RANK[$decision]) {
            $decision = $next;
        }
    };

    // 1. Санкции — безусловный стоп. Никакой низкий балл это не перевешивает.
    if ($result['sanctionsHit'] ?? false) {
        $escalate('BLOCK');
        $factors[] = '[!] Санкционное совпадение — блокировка безусловна';
    } else {
        $factors[] = '[+] Санкционных совпадений нет';
    }

    // 2. Публичное должностное лицо (PEP) среди контрагентов — тоже безусловный стоп:
    //    такие операции требуют отдельного решения комплаенс-офицера, а не автомата.
    if ($result['pepCounterparty'] ?? false) {
        $escalate('BLOCK');
        $factors[] = '[!] Контрагент из списка PEP — блокировка безусловна';
    } else {
        $factors[] = '[+] PEP-контрагентов нет';
    }

    // 3. Балл риска 0–100.
    $score = (int) ($result['riskScore'] ?? 0);
    if ($score >= SCORE_BLOCK) {
        $escalate('BLOCK');
        $factors[] = sprintf(
            '[!] Риск-балл %d >= порога блокировки %d (severity %s)',
            $score,
            SCORE_BLOCK,
            $result['severity'] ?? '?'
        );
    } elseif ($score >= SCORE_REVIEW) {
        $escalate('REVIEW');
        $factors[] = sprintf(
            '[?] Риск-балл %d в диапазоне ручной проверки %d–%d',
            $score,
            SCORE_REVIEW,
            SCORE_BLOCK - 1
        );
    } else {
        $factors[] = sprintf('[+] Риск-балл %d ниже порога ручной проверки (%d)', $score, SCORE_REVIEW);
    }

    // 4. Экспозиция на токсичные категории: миксеры, даркнет, вымогатели, краденое.
    //    Балл может быть умеренным, а вот прямая связь с миксером — нет.
    $exposures = array_merge($result['sourceOfFunds'] ?? [], $result['destinationOfFunds'] ?? []);
    foreach ($exposures as $exposure) {
        $percentage = (float) ($exposure['percentage'] ?? 0);
        if (isHighRiskCategory($exposure['category'] ?? null) && $percentage >= EXPOSURE_ALERT_PCT) {
            $escalate('REVIEW');
            $factors[] = sprintf(
                '[?] Экспозиция %.1f%% на категорию «%s» (%s)',
                $percentage,
                (string) $exposure['category'],
                $exposure['entityName'] ?? 'контрагент не назван'
            );
        }
    }

    if (!empty($result['dominantRiskCategory'])) {
        $factors[] = '[i] Доминирующая категория риска: ' . $result['dominantRiskCategory'];
    }

    return ['decision' => $decision, 'factors' => $factors];
}

// ── Печать отчёта ─────────────────────────────────────────────────────────────

function money(mixed $value): string
{
    return $value === null ? 'н/д' : '$' . number_format((float) $value, 2, '.', ' ');
}

function orDash(?string $value): string
{
    return ($value === null || $value === '') ? '—' : $value;
}

function yesNo(bool $value): string
{
    return $value ? 'ДА' : 'нет';
}

/** @param list<array<string, mixed>> $exposures */
function printExposures(string $title, array $exposures): void
{
    if ($exposures === []) {
        return;
    }

    echo "  {$title}:\n";
    foreach ($exposures as $exposure) {
        $parts = [
            sprintf('%.1f%%', (float) ($exposure['percentage'] ?? 0)),
            orDash($exposure['category'] ?? null),
            orDash($exposure['entityName'] ?? null),
        ];

        if (!empty($exposure['description'])) {
            $parts[] = (string) $exposure['description'];
        }
        if (!empty($exposure['country'])) {
            $parts[] = (string) $exposure['country'];
        }

        echo '    ' . implode(' · ', $parts) . "\n";
    }
}

// ── Демонстрация ─────────────────────────────────────────────────────────────

$client = new AmlClient();

if ($client->isSandbox()) {
    echo "Демо-ключ: ответы сгенерированы (моки), не реальные данные.\n\n";
}

$wallet = $argv[1] ?? '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa';
$blockchain = $argv[2] ?? 'BTC';

try {
    $result = $client->screenWallet($wallet, $blockchain);
} catch (AtloriumError $error) {
    fwrite(STDERR, "Ошибка: {$error->getMessage()}\n");
    exit(1);
}

echo "{$result['blockchain']} {$result['walletAddress']}\n";
printf(
    "  Риск-балл: %d/100 · severity: %s · статус: %s\n",
    $result['riskScore'],
    $result['severity'],
    $result['status']
);

if (!empty($result['summary'])) {
    echo "  Резюме: {$result['summary']}\n";
}

echo '  Санкции: ' . yesNo((bool) $result['sanctionsHit'])
    . ' · PEP: ' . yesNo((bool) $result['pepCounterparty']) . "\n";
echo '  Оборот: ' . money($result['totalValueUsd'] ?? null)
    . ' · комиссии: ' . money($result['feeUsd'] ?? null) . "\n";

printExposures('Источники средств', $result['sourceOfFunds'] ?? []);
printExposures('Назначение средств', $result['destinationOfFunds'] ?? []);

if (!empty($result['counterpartyConnections'])) {
    echo "  Контрагенты:\n";
    foreach ($result['counterpartyConnections'] as $counterparty) {
        printf(
            "    %s · %s · риск %s · %.1f%%\n",
            orDash($counterparty['entityName'] ?? null),
            orDash($counterparty['entityType'] ?? null),
            orDash($counterparty['riskLevel'] ?? null),
            (float) ($counterparty['percentage'] ?? 0)
        );
    }
}

$gate = complianceGate($result);
echo "\nКОМПЛАЕНС-ГЕЙТ: {$gate['decision']}\n";
foreach ($gate['factors'] as $factor) {
    echo "  {$factor}\n";
}