polyledger: возобновляемый индексатор Polymarket на DuckDB — что нужно знать перед развёртыванием

Что это

nahrek/polyledger — репозиторий на Python (620 звёзд, 109 форков, создан 2026-09-02), реализующий возобновляемый индексатор Polymarket. Он собирает две категории данных в единый файл DuckDB, доступный для SQL-запросов:

• метаданные рынков CLOB (Central Limit Order Book) Polymarket;
• ончейн-сделки с Polygon.

Ключевая инженерная идея — «resumable»: индексатор должен переживать рестарты и продолжать с места остановки, не теряя и не дублируя данные. Для операторов это главный пункт проверки перед продакшн-использованием.

Почему это важно

DuckDB как единственное хранилище — удобно для аналитики (SQL из коробки, встраиваемость, нет отдельного сервера), но это же и точка отказа:

• один файл = один lock на запись; параллельные индексатор + аналитик по одному файлу конфликтуют;
• нет встроенной репликации — бэкапить нужно вручную;
• при падении процесса важно понимать, как реализован чекпоинтинг (курсор по блокам Polygon + курсор по CLOB API).

Если планируете использовать это как источник данных для трейдинговых ботов или дашбордов — оцените, что происходит при частичной записи и рестарте до релиза в прод.

Чек-лист перед внедрением

1. Проверить схему устойчивости к рестартам

• найти, где хранится курсор (последний обработанный блок Polygon, последний курсор CLOB API);
• убедиться, что чекпоинт коммитится атомарно вместе с данными (одна транзакция DuckDB), иначе возможен дубль/пропуск при краше.

2. Изолировать файл DuckDB от конкурентного доступа

# Только один writer-процесс на файл.
# Для read-only аналитики — открывайте копию или read_only режим:
python - <<'PY'
import duckdb
con = duckdb.connect('polyledger.duckdb', read_only=True)
print(con.execute('SELECT count(*) FROM trades').fetchall())
PY

3. Настроить регулярный бэкап файла

# Простой снапшот с ротацией
SRC=/data/polyledger.duckdb
DST=/backup/polyledger_$(date +%Y%m%d_%H%M).duckdb
cp "$SRC" "$DST"
find /backup -name 'polyledger_*.duckdb' -mtime +14 -delete

4. Ограничить сетевые зависимости

• индексатор ходит и в Polygon RPC, и в Polymarket CLOB API — зафиксируйте таймауты и ретраи, чтобы недоступность одного источника не роняла процесс целиком;
• используйте выделенный RPC-эндпоинт (не публичный shared), иначе возможен rate-limit и рассинхронизация индекса.

5. Мониторинг лага индексации

-- Пример: разница между текущим блоком сети и последним индексированным
SELECT max(block_number) AS last_indexed_block
FROM onchain_trades;

Сравнивайте last_indexed_block с актуальной высотой Polygon через отдельный RPC-запрос и алертите при отставании выше порога (например, 100 блоков).

6. Зафиксировать версии зависимостей

pip install --no-cache-dir -r requirements.txt
pip freeze > requirements.lock.txt

Проект молодой (создан в сентябре 2026), API и схема таблиц могут меняться между релизами — жёстко пиньте версию перед продакшн-деплоем и тестируйте миграции схемы на копии файла.

Итог

Architecture «всё в одном DuckDB-файле» снижает порог входа для аналитики Polymarket, но перекладывает вопросы конкурентного доступа, бэкапов и мониторинга лага на оператора. Перед боевым использованием — проверить атомарность чекпоинтов, настроить бэкапы и алерты на отставание индекса, зафиксировать версии зависимостей.