# 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:

```bash
sudo systemctl stop agave-validator.service
```

2. Wyczyscic `ledger` i `state`:

```bash
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:

```bash
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:

```bash
./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:

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

Czy Yellowstone jest wylaczony:

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

Szybki health:

```bash
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:

```bash
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