Разработка системы генерации уникальных адресов для платежей

Разработка системы генерации уникальных адресов для платежей

Один адрес для всех платежей с комментарием — это работает, пока пользователи не забывают указывать memo. Но когда 5% платежей приходят без идентификатора и требуют ручного разбора — это операционная проблема. Unique address per payment решает её полностью: каждый заказ получает свой адрес, любой входящий платёж однозначно идентифицируется.

HD Wallet деривация: математика за кулисами

Основа системы — иерархические детерминированные кошельки (BIP-32/BIP-44). Из одного master seed можно детерминированно вывести сколько угодно дочерних ключей — адреса воспроизводимы, приватный ключ любого дочернего адреса восстанавливается из seed в любой момент.

Master Seed (128/256 бит)
    ↓ BIP-39
Master Mnemonic (12/24 слова)
    ↓ BIP-32 HMAC-SHA512
Master Extended Key (xprv)
    ↓ BIP-44 деривация
m / purpose' / coin_type' / account' / change / index

Для Ethereum (coin_type = 60):

m/44'/60'/0'/0/0   → первый адрес
m/44'/60'/0'/0/1   → второй адрес
m/44'/60'/0'/0/N   → N+1-й адрес

Важный момент: деривация address-only не требует приватного ключа. Extended public key (xpub) достаточно для генерации адресов. Это позволяет разнести компоненты: сервер генерации адресов держит только xpub (компрометация = утечка адресов, не средств), сервер подписания транзакций держит xprv в изолированной среде (HSM, offline).

Реализация

import { HDNodeWallet, Mnemonic } from 'ethers';

class PaymentAddressGenerator {
  private hdNode: HDNodeWallet;
  private currentIndex: number;

  constructor(xpub: string, startIndex: number = 0) {
    // Из xpub — только публичная деривация
    this.hdNode = HDNodeWallet.fromExtendedKey(xpub);
    this.currentIndex = startIndex;
  }

  generateAddress(orderId: string): { address: string; index: number } {
    // Используем атомарный счётчик из БД, не локальное состояние
    const index = this.currentIndex++;
    const childNode = this.hdNode.deriveChild(index);
    
    return {
      address: childNode.address.toLowerCase(),
      index,
    };
  }
}

// Атомарная генерация: получаем следующий index из PostgreSQL sequence
async function getNextIndex(db: Pool): Promise<number> {
  const result = await db.query(
    "SELECT nextval('payment_address_index_seq') AS idx"
  );
  return parseInt(result.rows[0].idx);
}

Почему не просто инкремент в коде? При горизонтальном масштабировании несколько инстансов сервиса могут одновременно получить одинаковый index. PostgreSQL sequence атомарен — nextval всегда возвращает уникальное значение.

База данных: схема

CREATE SEQUENCE payment_address_index_seq START 1;

CREATE TABLE payment_addresses (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  address       VARCHAR(42) NOT NULL UNIQUE,
  derivation_index INTEGER NOT NULL UNIQUE,
  order_id      UUID NOT NULL REFERENCES orders(id),
  network       VARCHAR(20) NOT NULL, -- 'ethereum', 'bsc', 'polygon'...
  currency      VARCHAR(20) NOT NULL, -- 'ETH', 'USDT', 'USDC'...
  expected_amount NUMERIC(36, 18),
  received_amount NUMERIC(36, 18) DEFAULT 0,
  status        VARCHAR(20) NOT NULL DEFAULT 'pending',
  expires_at    TIMESTAMPTZ NOT NULL,
  confirmed_tx  VARCHAR(66), -- tx hash
  created_at    TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_payment_addresses_address ON payment_addresses(address);
CREATE INDEX idx_payment_addresses_status ON payment_addresses(status) 
  WHERE status = 'pending';

Индекс по address — критичен для O(1) lookup при получении транзакции из блокчейн-листенера.

Мониторинг: отслеживаем только активные адреса

Наивный подход — подписаться на все сгенерированные адреса. При большой системе это тысячи адресов. Лучше: держать in-memory set активных (pending) адресов, который обновляется при создании/закрытии платежей.

class PaymentAddressMonitor {
  private activeAddresses: Map<string, PaymentAddress> = new Map();

  async loadActiveAddresses(db: Pool): Promise<void> {
    const result = await db.query(
      `SELECT address, order_id, expected_amount, currency, expires_at
       FROM payment_addresses 
       WHERE status = 'pending' AND expires_at > NOW()`
    );
    for (const row of result.rows) {
      this.activeAddresses.set(row.address.toLowerCase(), row);
    }
  }

  onTransactionDetected(toAddress: string, amount: bigint, txHash: string): void {
    const payment = this.activeAddresses.get(toAddress.toLowerCase());
    if (!payment) return; // Не наш адрес

    // Проверка суммы с tolerance 1%
    const tolerance = payment.expectedAmount * 99n / 100n;
    if (amount >= tolerance) {
      this.confirmPayment(payment, txHash);
    }
  }
}

Multi-network: один index, разные адреса

EVM-совместимые сети используют один и тот же приватный ключ — адрес одинаков на Ethereum, BNB Chain, Polygon, Arbitrum. Это удобно: один index в таблице можно использовать для приёма платежей в разных сетях на один адрес, но мониторинг нужен отдельный для каждой сети.

Для non-EVM (TON, Solana, Bitcoin) — отдельные HD деривации с разными master seed или разными путями деривации.

Sweeping: консолидация средств

Средства на дочерних адресах нужно периодически собирать на основной адрес (холодный кошелёк или multisig). Sweep должен происходить после подтверждения платежа:

async function sweepAddress(index: number): Promise<void> {
  // Деривация приватного ключа — только на signing сервере
  const privateKey = masterHdNode.deriveChild(index).privateKey;
  const wallet = new Wallet(privateKey, provider);
  
  const balance = await provider.getBalance(wallet.address);
  const gasEstimate = 21000n;
  const gasPrice = await provider.getFeeData().then(d => d.gasPrice!);
  const gasCost = gasEstimate * gasPrice;
  
  if (balance <= gasCost) return; // Нечего свипать
  
  await wallet.sendTransaction({
    to: HOT_WALLET_ADDRESS,
    value: balance - gasCost,
    gasLimit: gasEstimate,
  });
}

Для ERC-20 токенов sweep сложнее: нужно сначала убедиться, что на адресе есть ETH для gas, отправить его с основного адреса, потом забрать токены. Либо использовать паттерн с Permit/EIP-2612 — тогда газ платит не дочерний адрес.

Безопасность

• Master seed — в HSM или AWS KMS. Никогда в переменных среды.
• xpub для генерации адресов — отдельно от xprv для подписания.
• Signing сервис — изолированный микросервис с минимальными привилегиями.
• Аудит всех операций sweep — каждая транзакция логируется с обоснованием.
• Gap limit — BIP-44 рекомендует не смотреть глубже 20 последовательных неиспользованных адресов при восстановлении кошелька.