Operators

Wat is een Private Channels Operator?

Een operator is een vertrouwde, on-chain-gemachtigde entiteit die Solana Mainnet en het privékanaalnetwerk met elkaar verbindt. Operators worden ingericht door de instantiebeheerder via AddOperator, waarmee een on-chain Operator PDA wordt aangemaakt; zonder dit kan geen enkele partij ReleaseFunds aanroepen. In de praktijk is een operator een organisatie of team dat de services beheert die stortingen bewaken, tokens op kanaalniveau aanmaken, opnames detecteren en fondsen terugvereffenen naar Mainnet. Het uitvoeren van een instantie biedt uw gebruikers privé, grootschalige overdrachten die niet verschijnen op Solana Mainnet, directe doorvoer zonder kosten die de native Solana TPS overstijgt, en gecontroleerde toegang via RBAC.

Als u een ontwikkelaar bent die integreert met een bestaande Private Channels- instantie in plaats van er zelf een te deployen, begin dan met de Quickstart.

Voordat u begint

Vereisten

Vergrendel deze versies op de host zodat ze overeenkomen met de Docker-images:

Docker Engine 26+ (macOS Apple Silicon: schakel "Docker VMM" in via Instellingen -> Virtual Machine Options)
Node.js 24.7.0 en pnpm 10.15.1
Solana CLI 3.1.13 (Agave)
Rust 1.91.0
Een Yellowstone gRPC-eindpunt voor Devnet (beschikbaar via Helius, Triton, QuickNode)

Voor netwerkvereisten en standaardpoorttoewijzingen, zie docs/TECHNICAL_REQUIREMENTS.md in de repository.

Installeer de vastgezette Solana-toolchain en verwarm de SBF-cache:

make install-toolchain

Services

Het uitvoeren van een Private Channels-instantie betekent het op je nemen van vijf doorlopende verantwoordelijkheden, elk afgehandeld door toegewijde containers in de Docker Compose-stack:

Mainnet indexeren voor stortingen - indexer-solana bewaakt Solana Mainnet op Deposit-events via Yellowstone gRPC; operator-solana verwerkt bevestigde stortingen en slaat het equivalente tokensaldo op het kanaalnetwerk
Het kanaal indexeren voor opnames - indexer-private-channel peilt het kanaal elke seconde op WithdrawFunds-burn-events en schrijft openstaande opnamerecords naar de database
Fondsen vrijgeven op Mainnet - operator-private-channel verwerkt openstaande records en roept ReleaseFunds aan op het Escrow-programma met een geldig SMT- uitsluitingsbewijs
De SMT-root beheren - operator-private-channel roept ResetSmtRoot automatisch aan wanneer boom-epochs roteren; de on-chain verify_smt_exclusion_proof-controle is de laatste verdedigingslinie tegen ongeautoriseerde opnames
De gateway en auth-service uitvoeren - de gateway is het enige publieke eindpunt voor al het clientverkeer; de auth-service (optioneel) handhaaft JWT/RBAC wanneer JWT_SECRET is ingesteld

Voor de volledige service-inventaris en poorttoewijzingen, zie de Configuratiereferentie.

Beveiligingsopmerking: Write-node- en read-node-poorten zijn uitsluitend gebonden aan loopback (127.0.0.1), maar meerdere andere services (gateway, auth, operator metrics, Grafana, Prometheus, cAdvisor) worden standaard gepubliceerd naar alle netwerk- interfaces. Zie de Configuratiereferentie voor de volledige poorttabel en beveilig deze met een firewall vóór elke publiek toegankelijke implementatie. RBAC dekt alleen de eigen JSON-RPC-methoden van de gateway, niet deze andere services.

Toegangscontrole: Open vs. RBAC

Standaard accepteert de gateway alle verbindingen; geen tokens vereist. Om JWT-gebaseerde RBAC in te schakelen, stelt u JWT_SECRET in en start u de stack met --profile auth. Zie Authenticatie & Rollen voor de volledig configuratiereferentie, inclusief hoe u de operator-rol inricht en gebruikerswallets registreert.

Als u auth inschakelt, voeg deze toe aan uw omgeving voordat u de stack start:

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

Omgevingsinstellingen

.env.devnet wordt al bijgehouden in de repository met devnet-specifieke standaardwaarden ingevuld; bewerk het direct in plaats van het opnieuw te genereren vanuit .env.example, wat die standaardwaarden zou overschrijven.

Vul de resterende waarden in terwijl u de onderstaande implementatiestappen doorloopt; sommige zijn pas beschikbaar halverwege de implementatie. Geheimen gaan in het gitignored .env-bestand; niet-geheime variabelen gaan in .env.devnet.

Geheimen - stel deze onmiddellijk in:

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

Variabelen verkregen tijdens de implementatie:

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>

ADMIN_PRIVATE_KEY is de verplichte fee-payer-ondertekenaar van de off-chain services zelf, niet gerelateerd aan de on-chain instantiebeheerder uit Stap 3. Deze handleiding plaatst het operator keypair dat in Stap 4 hieronder is gegenereerd in ADMIN_PRIVATE_KEY en laat de optionele OPERATOR_PRIVATE_KEY oningesteld, zodat de operator-ondertekenaar terugvalt op dezelfde sleutel. Plaats nooit het keypair van de instantiebeheerder op protocolniveau uit Stap 3 in een van beide variabelen.

Voor de volledige referentie van omgevingsvariabelen, zie Configuratie.

Implementeren

Images bouwen

make docker-devnet-build

Dit compileert alle Rust-services in een gedeelde Docker-image. De eerste build duurt 30 minuten tot een uur.

De Admin UI instellen

De Admin UI is een browsergebaseerde tool voor het aanmaken en configureren van de escrow- instantie: een ontwikkelings- en beheerhulpmiddel, geen gebruikersgerichte product en geen vereist runtime-component. Alle bewerkingen die het uitvoert (CreateInstance, AllowMint, AddOperator) kunnen ook worden uitgevoerd via de CLI- scripts in de repository.

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

Een escrow-instantie aanmaken

Stel uw browserportemonnee in op Devnet en zorg dat u Devnet SOL heeft voor kosten
Klik in de Admin UI op Create New Instance en keur de transactie goed
Kopieer het Instance Address en stel dit in als ESCROW_INSTANCE_ID in .env.devnet

Of gebruik het CLI-script:

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

Een operator keypair genereren

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

Stel de inhoud van het keypair in als ADMIN_PRIVATE_KEY in uw omgeving. De publieke sleutel is geen omgevingsvariabele; u geeft deze rechtstreeks door als de operator pubkey in de stap "De instantie configureren" hieronder.

Omgevingsvariabelen afronden

Werk .env.devnet bij met ESCROW_INSTANCE_ID, DEVNET_RPC_URL, DEVNET_YELLOWSTONE_ENDPOINT en INDEXER_YELLOWSTONE_TOKEN. Plaats geheimen (POSTGRES_PASSWORD, POSTGRES_REPLICATION_PASSWORD, ADMIN_PRIVATE_KEY) in het gitignored .env-bestand.

Als u RBAC hebt ingeschakeld (Toegangscontrole: Open vs. RBAC), voeg dan nu ook JWT_SECRET en AUTH_PORT toe.

Alle services starten

Zonder auth:

make docker-devnet-up

Met auth:

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

Compose schakelt zijn automatische .env-autolading uit zodra een --env-file-vlag wordt doorgegeven, dus de afsluitende --env-file .env is vereist. Zonder dit lossen POSTGRES_PASSWORD, ADMIN_PRIVATE_KEY en JWT_SECRET (die u in .env hebt geplaatst) leeg op en kan de stack niet correct starten.

Start de services vóór het configureren van de instantie. De indexer streamt events in real time, dus door de stack eerst omhoog te brengen, zorgt u dat AllowMint en uw eerste storting in volgorde worden geïndexeerd zonder dat een backfill nodig is.

De instantie configureren

Met de stack actief, whitelists u een token mint en voegt u uw operator toe via de Admin UI:

Allow Mint: Admin Functions -> Mint Management -> voer mintadres in -> Allow Mint
Add Operator: Admin Functions -> Operator Management -> voer operator pubkey in -> Add Operator

Of via CLI:

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

Deze handleiding richt zich op Solana devnet. Voor Mainnet:

Program-ID's worden gecompileerd via declare_id!(): controleer of u de juiste Mainnet-ID's uit de repository gebruikt
Yellowstone gRPC-eindpunten vereisen een Mainnet-abonnement; devnet-eindpunten streamen geen Mainnet-events
De operatorwallet betaalt SOL-kosten voor elke ReleaseFunds-aanroep, dus pas het SOL-saldo aan op uw verwachte opnamevolume
Wijzig alle standaardgegevens (Grafana, PostgreSQL) vóór elke publiek toegankelijke implementatie

Beheer

Handige Commando's

# 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

Observeerbaarheid

De stack bevat Prometheus, Grafana en cAdvisor voor statistieken en container- bewaking. Grafana is toegankelijk op poort 37429.

Het standaard Grafana-wachtwoord is admin. Wijzig het voordat u poort 37429 blootstelt aan een netwerk buiten localhost.

Probleemoplossing

Kanaalsaldo wordt niet bijgewerkt na storting

Bevestig dat de Mainnet-stortingstransactie is verwerkt op een Mainnet-verkenner
Controleer of indexer-solana actief is: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
Controleer of operator-solana actief is: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
Controleer of uw Yellowstone gRPC-eindpunt bereikbaar is en het token geldig is (DEVNET_YELLOWSTONE_ENDPOINT, INDEXER_YELLOWSTONE_TOKEN)
Wacht tot 30 seconden na on-chain bevestiging, aangezien de indexer een finaliteits-veiligheidsvertraging toepast voordat credits worden toegekend

Opname wordt niet vereffend naar Mainnet

Controleer of indexer-private-channel actief is: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
Controleer of operator-private-channel actief is: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
Bevestig dat het operator keypair in ADMIN_PRIVATE_KEY overeenkomt met de sleutel die is geregistreerd met AddOperator on-chain
Als de logs "SMT root mismatch" tonen, sluit de service af in plaats van een ongeldig bewijs in te dienen. Stop de stack, herstel vanuit een consistente staat en herstart

JWT-authenticatiefouten (401 op alle verzoeken)

Bevestig dat JWT_SECRET identiek is op zowel de gateway- als de auth-service- containers
Bevestig dat de stack is gestart met --profile auth
Tokens verlopen na 24 uur; authenticeer opnieuw om een nieuw token te verkrijgen