Operatorzy

Czym jest Operator Private Channels?

Operator to zaufany podmiot z uprawnieniami on-chain, który łączy Solana Mainnet z siecią prywatnych kanałów. Operatorzy są aprowizowani przez admina instancji za pomocą AddOperator, co tworzy on-chain PDA Operator; bez tego żadna strona nie może wywołać ReleaseFunds. W praktyce operator to organizacja lub zespół prowadzący usługi monitorujące depozyty, mintujące tokeny po stronie kanału, wykrywające wypłaty i rozliczające środki z powrotem do Mainnet. Uruchomienie instancji zapewnia Twoim użytkownikom prywatne, wysokoprzepustowe transfery niewidoczne na Solana Mainnet, natychmiastową przepustowość bez opłat wykraczającą poza natywne TPS Solany oraz kontrolowany dostęp przez RBAC.

Przed Rozpoczęciem

Wymagania Wstępne

Przypnij te wersje na hoście, aby dopasować je do obrazów Docker:

• Docker Engine 26+ (macOS Apple Silicon: włącz "Docker VMM" w Ustawieniach -> Opcje maszyny wirtualnej)
• Node.js 24.7.0 i pnpm 10.15.1
• Solana CLI 3.1.13 (Agave)
• Rust 1.91.0
• Endpoint Yellowstone gRPC dla Devnet (dostępny od Helius, Triton, QuickNode)

Wymagania sieciowe i domyślne przypisania portów znajdziesz w docs/TECHNICAL_REQUIREMENTS.md w repozytorium.

Zainstaluj przypiętą wersję zestawu narzędzi Solana i rozgrzej pamięć podręczną SBF:

make install-toolchain

Usługi

Uruchomienie instancji Private Channels oznacza przejęcie pięciu bieżących obowiązków, z których każdy jest obsługiwany przez dedykowane kontenery w stosie Docker Compose:

1. Indeksowanie Mainnet pod kątem depozytów - indexer-solana monitoruje Solana Mainnet pod kątem zdarzeń Deposit przez Yellowstone gRPC; operator-solana pobiera potwierdzone depozyty i mintuje równoważne saldo tokenów w sieci kanałów
2. Indeksowanie kanału pod kątem wypłat - indexer-private-channel odpytuje kanał co sekundę w poszukiwaniu zdarzeń spalania WithdrawFunds i zapisuje oczekujące rekordy wypłat do bazy danych
3. Zwalnianie środków na Mainnet - operator-private-channel pobiera oczekujące rekordy i wywołuje ReleaseFunds w Programie Escrow z ważnym dowodem wykluczenia SMT
4. Zarządzanie korzeniem SMT - operator-private-channel wywołuje ResetSmtRoot automatycznie przy rotacji epok drzewa; sprawdzenie on-chain verify_smt_exclusion_proof to ostatnia linia obrony przed nieautoryzowanymi wypłatami
5. Uruchamianie bramy i usługi auth - brama jest jedynym publicznym endpointem dla całego ruchu klientów; usługa auth (opcjonalna) wymusza JWT/RBAC gdy ustawiono JWT_SECRET

Pełny wykaz usług i przypisania portów znajdziesz w Dokumentacji konfiguracji.

Uwaga dotycząca bezpieczeństwa: Porty węzłów zapisu i odczytu są przypisane wyłącznie do pętli zwrotnej (127.0.0.1), jednak kilka innych usług (brama, auth, metryki operatora, Grafana, Prometheus, cAdvisor) jest domyślnie publikowanych na wszystkich interfejsach sieciowych. Zapoznaj się z Dokumentacją konfiguracji w celu poznania pełnej tabeli portów i zabezpiecz je zaporą sieciową przed każdym publicznym wdrożeniem. RBAC obejmuje wyłącznie własne metody JSON-RPC bramy, a nie te pozostałe usługi.

Kontrola Dostępu: Otwarta vs. RBAC

Domyślnie brama akceptuje wszystkie połączenia bez wymagania tokenów. Aby włączyć RBAC oparty na JWT, ustaw JWT_SECRET i uruchom stos z --profile auth. Zapoznaj się z Uwierzytelnianie i Role po pełną dokumentację konfiguracji, w tym informacje o aprowizacji roli operator i rejestrowaniu portfeli użytkowników.

Jeśli włączasz auth, dodaj te zmienne do swojego środowiska przed uruchomieniem stosu:

JWT_SECRET=<openssl rand -hex 32>   # must match on gateway and auth service
AUTH_PORT=8903

Konfiguracja Środowiska

.env.devnet jest już śledzony w repozytorium z wypełnionymi domyślnymi wartościami specyficznymi dla devnet; edytuj go bezpośrednio zamiast regenerować z .env.example, co nadpisałoby te wartości domyślne.

Uzupełnij pozostałe wartości w trakcie wykonywania poniższych kroków wdrożenia; niektóre są dostępne dopiero w trakcie wdrożenia. Sekrety umieszczaj w pliku .env ignorowanym przez git; zmienne niesekretne w .env.devnet.

Sekrety – ustaw je natychmiast:

POSTGRES_PASSWORD=<openssl rand -hex 32>
POSTGRES_REPLICATION_PASSWORD=<openssl rand -hex 32>

Zmienne uzyskiwane podczas wdrożenia:

ESCROW_INSTANCE_ID=<instance address - from Step 3>
ADMIN_PRIVATE_KEY=<operator keypair as u8 array or base58 - from Step 4>
DEVNET_RPC_URL=https://api.devnet.solana.com
DEVNET_YELLOWSTONE_ENDPOINT=<your Yellowstone gRPC endpoint>
INDEXER_YELLOWSTONE_TOKEN=<your Yellowstone auth token>

Pełną dokumentację zmiennych środowiskowych znajdziesz w Konfiguracji.

Wdrożenie

make docker-devnet-build

cd admin-ui
pnpm install
echo "PRIVATE_CHANNEL_RPC_URL=http://localhost:8899" > .env
pnpm dev   # opens at http://localhost:5173

cargo run --bin create_instance -- https://api.devnet.solana.com ./keypairs/admin.json

solana-keygen new -o operator-keypair.json -s --no-bip39-passphrase
solana-keygen pubkey operator-keypair.json

make docker-devnet-up

docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet --env-file .env --profile auth up -d

cargo run --bin add_operator -- \
  https://api.devnet.solana.com \
  ./keypairs/admin.json \
  <INSTANCE_ID> \
  <OPERATOR_PUBKEY>

Operacje

Przydatne Polecenia

# View logs (all services)
make docker-devnet-logs

# View logs (specific service)
docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana

# Stop services
make docker-devnet-down

# Stop and wipe all state (volumes)
make docker-devnet-clean

Obserwowalność

Stos zawiera Prometheus, Grafana i cAdvisor do monitorowania metryk i kontenerów. Grafana jest dostępna na porcie 37429.

Rozwiązywanie Problemów

Saldo kanału nie aktualizuje się po depozycie

1. Potwierdź, że transakcja depozytu na Mainnet pojawiła się w eksploratorze Mainnet
2. Zweryfikuj, czy indexer-solana działa: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
3. Zweryfikuj, czy operator-solana działa: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
4. Sprawdź, czy Twój endpoint Yellowstone gRPC jest osiągalny i token jest ważny (DEVNET_YELLOWSTONE_ENDPOINT, INDEXER_YELLOWSTONE_TOKEN)
5. Poczekaj do 30 sekund po potwierdzeniu on-chain, ponieważ indekser stosuje opóźnienie bezpieczeństwa finalizacji przed zaksięgowaniem środków

Wypłata nie jest rozliczana na Mainnet

1. Zweryfikuj, czy indexer-private-channel działa: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
2. Zweryfikuj, czy operator-private-channel działa: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
3. Potwierdź, że keypair operatora w ADMIN_PRIVATE_KEY odpowiada kluczowi zarejestrowanemu przez AddOperator on-chain
4. Jeśli logi pokazują "SMT root mismatch", usługa wyłącza się zamiast przesłać nieprawidłowy dowód. Zatrzymaj stos, przywróć spójny stan i uruchom ponownie

Błędy uwierzytelniania JWT (401 na wszystkich żądaniach)

1. Potwierdź, że JWT_SECRET jest identyczny w kontenerach bramy i usługi auth
2. Potwierdź, że stos został uruchomiony z --profile auth
3. Tokeny wygasają po 24 godzinach; uwierzytelnij się ponownie, aby uzyskać nowy token

Pierwsze budowanie trwa zbyt długo

To oczekiwane. Pierwsze make docker-devnet-build kompiluje wszystkie usługi Rust i może zająć 30–60 minut na typowym sprzęcie. Kolejne budowania korzystają z pamięci podręcznej warstw Docker i są znacznie szybsze.

Następne Kroki