trade-doc/agave-sync-recipe.md

Agave Sync Recipe

Data: 2026-03-13 Aktualizacja: 2026-03-15

Ten plik opisuje praktyczna recepture rozruchu Agave na mevnode_sol w dwoch trybach:

• catch-up mode: celem jest dogonienie sieci
• product mode: celem jest obsluga workloadow RPC i Yellowstone dla reszty systemu

Plik sterujacy

Aktualny start validatora jest skladany przez:

• /usr/local/bin/agave-validator.sh

Usluga systemd:

• agave-validator.service

Catch-up Mode

Stan wdrozony na mevnode_sol 2026-03-15 podczas przejscia na Agave 3.1.9.

Cel:

• maksymalnie odchudzic runtime podczas syncu
• nie wystawiac Yellowstone
• nie budowac ciezkiego profilu RPC

Wlaczone:

• --private-rpc
• --rpc-bind-address 127.0.0.1
• --rpc-port 8899
• --accounts-db-cache-limit-mb 32768
• --no-voting
• --limit-ledger-size 50000000
• --minimal-snapshot-download-speed 25000000
• --maximum-snapshot-download-abort 8
• --use-snapshot-archives-at-startup always
• --known-validator 7mF8NZJdREuM1uwYcvKffuY9QJBEoHhNp4hZ4NS2fuXW
• --only-known-rpc
• dodatkowy --entrypoint 51.89.11.213:8001 dla Frankfurtu

Wylaczone:

• --geyser-plugin-config /etc/agave/geyser.json
• --full-rpc-api
• --enable-accounts-disk-index
• --accounts-index-path /data/ledger/accounts_index
• --account-index ...

Wazne:

• --accounts-index-path nie moze zostac, jesli --enable-accounts-disk-index jest wylaczone
• zostawienie samego --accounts-index-path powoduje start failure Agave

Product Mode

To jest profil po pelnym syncu, kiedy node ma znowu obslugiwac reszte systemu. Stan finalny z 2026-03-15:

Wlaczone:

• --geyser-plugin-config /etc/agave/geyser.json
• --full-rpc-api
• --enable-accounts-disk-index
• --accounts-db-cache-limit-mb 32768
• --maximum-full-snapshots-to-retain 1
• --maximum-incremental-snapshots-to-retain 1
• --use-snapshot-archives-at-startup when-newest
• --known-validator 7mF8NZJdREuM1uwYcvKffuY9QJBEoHhNp4hZ4NS2fuXW
• --only-known-rpc

Cel:

• Yellowstone dla mevnode_bot
• ciezsze metody RPC
• nizszy swap niz przy czysto pamieciowym accounts index

Uwaga:

• w aktualnym wdrozeniu nie ma --accounts-index-path
• w aktualnym wdrozeniu nie ma --account-index program-id
• samo --enable-accounts-disk-index zmniejsza presje na swap, ale nie przyspiesza ciezkich getProgramAccounts
• retencja snapshotow 1/1 nie jest tutaj opcjonalna; to jest kluczowy bezpiecznik operacyjny

Dlaczego retencja 1/1 jest krytyczna

Na mevnode_sol katalog /data/state jest jednym filesystemem 2 TB, na ktorym siedza jednoczesnie:

• accounts
• accounts disk index
• archiwa snapshotow
• tymczasowe tmp-snapshot-archive-*

Przy profilu:

• --full-rpc-api
• --enable-accounts-disk-index
• --geyser-plugin-config /etc/agave/geyser.json

sam katalog accounts potrafi zajmowac ponad 1 TB, a snapshoty i pliki tymczasowe potrafia dopchnac /data/state do 100%.

Wniosek praktyczny:

• --maximum-full-snapshots-to-retain 1
• --maximum-incremental-snapshots-to-retain 1

to nie jest tylko "porzadek na dysku", tylko warunek utrzymania zapasu miejsca na:

• prace accounts disk index
• tworzenie nowego snapshotu
• restart z lokalnego full + incremental

Bez tego Agave moze dojsc do ENOSPC, przestac odpowiadac po RPC albo wymusic awaryjny cleanup przed restartem.

Dlaczego nie 8 GB

W tej sesji nie bylo twardych danych, ze samo 8 GB rozwiazuje problem. Przy 32 GB host nie byl pod presja pamieci:

• RAM hosta: okolo 186 GiB
• available memory: okolo 143 GiB
• swap praktycznie nieuzywany

Problem wygladal bardziej na zbyt ciezki profil catch-up niz na brak RAM.

Obserwacje z 2026-03-13

Przed przelaczeniem na catch-up mode:

• geyser byl wylaczony
• nadal wlaczone byly --full-rpc-api i --enable-accounts-disk-index
• node nie nadganial heada; lokalny slot rosl wolniej niz publiczny mainnet

Po przelaczeniu na catch-up mode:

• Agave wystartowalo poprawnie bez full-rpc-api
• Agave wystartowalo poprawnie bez accounts-disk-index
• aktywny proces nie ma juz geyser, full-rpc-api ani accounts-disk-index

Kolejnosc wdrozenia z 2026-03-15

Poniżej jest praktyczna kolejnosc, ktora byla wykonana na mevnode_sol.

1. Zatrzymac usluge:

sudo systemctl stop agave-validator.service

2. Wyczyscic ledger i state:

sudo rm -rf /data/ledger/*
sudo rm -rf /data/state/*

3. Zbudowac i podmienic Agave na 3.1.9:

• build z taga v3.1.9
• instalacja do /opt/agave-v3.1.9
• przelaczenie /opt/agave -> /opt/agave-v3.1.9

4. Wystartowac lekki catch-up mode:

• bez geyser
• bez --full-rpc-api
• bez --enable-accounts-disk-index
• bez --accounts-index-path
• z --use-snapshot-archives-at-startup always

5. Wymusic szybki source snapshotu z Frankfurtu:

• --known-validator 7mF8NZJdREuM1uwYcvKffuY9QJBEoHhNp4hZ4NS2fuXW
• --only-known-rpc
• --entrypoint 51.89.11.213:8001

6. Poczekac az catch-up mode dojdzie do getHealth=ok.

7. Zmienic startup snapshotow z always na when-newest.

Powod:

• przy always kazdy restart wymuszal ladowanie z archive
• when-newest zostawia Agave mozliwosc uzycia nowszego archive, ale nie wymusza tej sciezki przy kazdym restarcie

8. Wlaczyc --full-rpc-api i zrestartowac.

9. Po ponownym syncu wlaczyc --enable-accounts-disk-index i zrestartowac.

Powod:

• przy full-rpc bez accounts-disk-index swap byl praktycznie zapychany
• po wlaczeniu accounts-disk-index swap spadl prawie do zera

10. Po kolejnym syncu wlaczyc geyser.

Praktycznie:

• dopiac --geyser-plugin-config /etc/agave/geyser.json
• upewnic sie, ze libpath z configu istnieje
• na mevnode_sol trzeba bylo utworzyc symlink:

sudo mkdir -p /opt/agave/plugins
sudo ln -sfn /opt/agave.live-3.1.10-20260314-0903/plugins/v12.1.0+solana.3.1.10 /opt/agave/plugins/current

11. Po wlaczeniu geysera zweryfikowac:

• 10.91.0.1:10000 nasluchuje
• 10.91.0.1:8999/metrics odpowiada
• w logu jest:
  • Geyser plugin: accounts_update_notifier: true, transaction_notifier: true, entry_notifier: true

12. Na koncu ustawic retencje snapshotow:

• --maximum-full-snapshots-to-retain 1
• --maximum-incremental-snapshots-to-retain 1

Cel:

• ograniczyc wzrost /data/state/snapshots
• zostawic minimalny zestaw do restartu
• nie dopuscic do zapchania 2 TB /data/state, na ktorym siedza tez accounts i accounts disk index

13. Po syncu usuwac tylko stare snapshoty, nie ruszajac:

• aktualnego full snapshotu
• najnowszego ukonczonego incremental
• aktywnego tmp-snapshot-archive-*

To byl praktyczny cleanup, ktory odzyskal kilkaset GB, bez psucia restart path.

Jak sprawdzac stan

Jednym poleceniem snapshot kluczowych metryk:

./scripts/ops/agave-metrics.sh mevnode

Skrypt zbiera:

• health RPC i lokalny slot
• publiczny head i lag_slots
• porty 8899 / 8999 / 10000
• rss_mb, pcpu, pmem
• mem_available_mb, swap_used_mb
• vm_us, vm_sy, vm_id, vm_wa
• ostatnie rcvbuf_errors_delta_recent

Status uslugi:

ssh mevnode 'systemctl --no-pager --full status agave-validator.service | sed -n "1,20p"'

Czy Yellowstone jest wylaczony:

ssh mevnode 'ss -ltnp | grep -E ":(8899|10000|8999)\\b" || true'

Szybki health:

ssh mevnode "printf '%s' '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getHealth\"}' | curl -sS -H 'Content-Type: application/json' -d @- http://10.91.0.1:8899"

Pomiar, czy node nadgania:

ssh mevnode 'for i in 1 2 3; do ts=$(date +%s); pjson=$(printf "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSlot\",\"params\":[{\"commitment\":\"processed\"}]}" ); pubjson=$(printf "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSlot\"}" ); p=$(curl -sS -m 6 -H "Content-Type: application/json" -d "$pjson" http://10.91.0.1:8899 | sed -n "s/.*\"result\":\\([0-9][0-9]*\\).*/\\1/p"); pub=$(curl -sS -m 6 -H "Content-Type: application/json" -d "$pubjson" https://api.mainnet-beta.solana.com | sed -n "s/.*\"result\":\\([0-9][0-9]*\\).*/\\1/p"); echo "$ts $p $pub"; sleep 10; done'

Interpretacja:

• jesli lokalny processed rosnie szybciej niz publiczny head, node nadgania
• jesli lokalny processed rosnie wolniej, lag dalej narasta

Re-enable Po Sync

Nie wlaczac wszystkiego naraz.

Kolejnosc rekomendowana:

1. --full-rpc-api
2. --enable-accounts-disk-index
3. --geyser-plugin-config /etc/agave/geyser.json
4. retencja snapshotow 1/1

Po kazdym etapie:

• restart agave-validator.service
• poczekac na getHealth=ok
• dopiero potem przechodzic do nastepnego etapu