Синхронизация балансов

Вы держите у себя копию балансов и хотите, чтобы она сходилась с Pert. Эта страница описывает надёжную схему: как обновлять балансы в реальном времени, как их сверять и как восполнять то, что могло не дойти.

Схема состоит из трёх частей:

1. Живое обновление из webhook

Подпишитесь на события транзакций (см. Типы событий). В каждой транзакции есть стороны from и to, и у каждой:

Плюс у самой транзакции есть поле balance_version — версия снимков балансов этой транзакции. Она монотонно растёт по каждому адресу и служит ключом порядка.

Обновляйте баланс кошелька абсолютным значением из balance — это снимок, а не приращение:

balance[address] = side.balance      # НЕ += amount

v = tx.balance_version
for side in (from, to):
    if v >= version[side.address]:
        balance[side.address] = side.balance
        version[side.address] = v
# иначе игнорировать — это устаревший снимок

Повторы событий отсеивайте по X-Webhook-Event-Id, повторы транзакций — по их id. Такое обновление идемпотентно: повтор того же снимка ничего не меняет.

2. Периодическая сверка

Периодически запрашивайте суммарные балансы и сверяйте со своими:

GET /asset/balances/currencies

Ответ — согласованный снимок:

Сравните currency_balances со своим суммарным балансом по валютам. Сошлось — готово. Разошлись — переходите к восполнению.

3. Восполнение пропущенного

Чтобы получить изменения, которые webhook не доставил, листайте журнал изменений начиная с вашей сохранённой позиции:

GET /transactions/changes?since_cursor={cursor}&limit=100

Листайте, пока has_more == true, и на каждой странице:

1. сохраните каждую транзакцию по её id (создание или замена);
2. обновите балансы кошельков из from/to — так же абсолютно и по balance_version, как в п.1;
3. сдвиньте позицию: since_cursor = next_cursor.

limit — по умолчанию 100, максимум 1000.

C = сохранённая_позиция
loop:
    page = GET /transactions/changes?since_cursor=C&limit=500
    for item in page.items:
        store(item.id, item)
        applyBalance(item.from); applyBalance(item.to)   # абсолютно, по balance_version
    C = page.next_cursor
    save(C)
    if not page.has_more: break
пересчитать суммарный баланс; повторить сверку из п.2

Курсор

cursor — непрозрачное монотонное значение. Храните его и возвращайте как есть, не разбирайте и не считайте номером. Курсор из ответа балансов и курсор журнала изменений — одно и то же пространство: позиция, полученная от балансов, всегда достижима через журнал.

min_cursor — защита от «слишком далеко отстал». Если ваша сохранённая позиция меньше min_cursor, журнал уже не сможет восстановить всё пропущенное. В этом случае не пытайтесь восполнять — сбросьте состояние: возьмите свежий снимок GET /asset/balances/currencies как истину и продолжайте с его cursor.

Гарантии и важные моменты

• Истина значения — запрос балансов. При расхождении принимайте её, а не результат пересчёта из транзакций. Ответ баланса разбивает средства на замороженные (frozen) и удержанные (held, суммы исходящих транзакций «в полёте»), и available уже вычтен из подтверждённого баланса — эти поправки из потока транзакций сам клиент надёжно не выведет.
• Идемпотентность. Запись по id транзакции и абсолютное обновление баланса по balance_version делают повторную доставку и повторное применение безопасными.
• Не сошлось после восполнения — перезапросите позже: временное расхождение от свежей активности исчезнет само, а реальное расхождение останется и разрешится при следующей сверке против балансов.

Итоговый цикл

1. Первичная загрузка: GET /asset/balances/currencies → сохранить балансы как истину и cursor.
2. Живой поток: обновлять балансы кошельков из webhook (from/to.balance, по balance_version).
3. Сверка: периодически GET /asset/balances/currencies, сравнить суммарный баланс.
4. Восполнение: при расхождении листать GET /transactions/changes?since_cursor=… до has_more == false; при cursor < min_cursor — сброс к свежему снимку.