Operaattorit

Mikä on Private Channels -operaattori?

Operaattori on luotettu, ketjussa oikeuksitettu taho, joka toimii siltana Solana Mainnetin ja yksityisen kanavaverkon välillä. Instanssin ylläpitäjä provisioi operaattorit AddOperator-komennolla, joka luo ketjuun Operator-PDA:n; ilman tätä mikään osapuoli ei voi kutsua ReleaseFunds-toimintoa. Käytännössä operaattori on organisaatio tai tiimi, joka ajaa palveluita, jotka tarkkailevat talletuksia, lyövät kanavapuolen tokeneita, havaitsevat nostot ja tilittävät varat takaisin Mainnetiin. Instanssin ajaminen tarjoaa käyttäjillesi yksityisiä, suuren volyymin siirtoja, jotka eivät näy Solana Mainnetissä, välittömän nollamaksuisen läpimenon natiivin Solana TPS:n ylittämiseksi sekä hallitun pääsynhallinnan RBAC:n kautta.

Ennen aloittamista

Esitietovaatimukset

Kiinnitä nämä versiot isäntäkoneelle vastaamaan Docker-kuvia:

• Docker Engine 26+ (macOS Apple Silicon: ota käyttöön "Docker VMM" kohdasta Asetukset -> Virtuaalikoneasetukset)
• Node.js 24.7.0 ja pnpm 10.15.1
• Solana CLI 3.1.13 (Agave)
• Rust 1.91.0
• Yellowstone gRPC -päätepiste Devnetille (saatavilla Heliukselta, Tritonilta, QuickNodesta)

Verkkovaatimukset ja oletusporttimääritykset löytyvät docs/TECHNICAL_REQUIREMENTS.md -tiedostosta repositoriossa.

Asenna kiinnitetty Solana-työkaluketju ja lämmitä SBF-välimuisti:

make install-toolchain

Palvelut

Private Channels -instanssin ajaminen tarkoittaa viiden jatkuvan vastuualueen hallintaa, joista jokainen on omistettu Docker Compose -pinon erillisille konteille:

1. Indeksoi Mainnet talletuksia varten - indexer-solana tarkkailee Solana Mainnetia Deposit-tapahtumien varalta Yellowstone gRPC:n kautta; operator-solana poimii vahvistetut talletukset ja lyö vastaavan tokenisaldon kanavaverkkoon
2. Indeksoi kanava nostoja varten - indexer-private-channel kyselee kanavalta joka sekunti WithdrawFunds-polttotapahtumien varalta ja kirjoittaa odottavat nostotietueet tietokantaan
3. Vapauta varat Mainnetissä - operator-private-channel poimii odottavat tietueet ja kutsuu ReleaseFunds-toimintoa Escrow-ohjelmalla kelvollisella SMT- poissulkemistodistuksella
4. Hallitse SMT-juurta - operator-private-channel kutsuu ResetSmtRoot-toimintoa automaattisesti, kun puun epochit kiertyvät; ketjussa oleva verify_smt_exclusion_proof-tarkistus on viimeinen puolustuslinja luvattomia nostoja vastaan
5. Aja yhdyskäytävää ja auth-palvelua - yhdyskäytävä on ainoa julkinen päätepiste kaikelle asiakkasliikenteelle; auth-palvelu (valinnainen) pakottaa JWT/RBAC-käytännön, kun JWT_SECRET on asetettu

Täydellinen palveluluettelo ja porttimääritykset löytyvät Konfiguraatioviitteestä.

Tietoturvahuomio: Write-node- ja read-node-portit on sidottu vain loopback-osoitteeseen (127.0.0.1), mutta useat muut palvelut (yhdyskäytävä, auth, operaattorimittarit, Grafana, Prometheus, cAdvisor) julkaistaan oletuksena kaikille verkkoliitännöille. Katso Konfiguraatioviite täydellisestä porttitaulukosta ja suojaa nämä palomuurilla ennen julkiseen verkkoon suunnattua käyttöönottoa. RBAC kattaa vain yhdyskäytävän omat JSON-RPC-metodit, ei näitä muita palveluita.

Pääsynhallinta: Avoin vs. RBAC

Yhdyskäytävä hyväksyy oletuksena kaikki yhteydet ilman tokeneja. JWT-pohjaisen RBAC:n käyttöönottamiseksi aseta JWT_SECRET ja käynnistä pino komennolla --profile auth. Katso Todennus & Roolit -osiosta täydellinen konfiguraatioviite, mukaan lukien ohjeet operator-roolin provisiointiin ja käyttäjälompakoiden rekisteröintiin.

Jos otat autentikoinnin käyttöön, lisää nämä ympäristöön ennen pinon käynnistämistä:

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

Ympäristön asennus

.env.devnet on jo seurannassa repositoriossa devnet-kohtaisilla oletusarvoilla täytettynä; muokkaa sitä suoraan sen sijaan, että generoisit sen uudelleen .env.example-tiedostosta, mikä ylikirjoittaisi nuo oletusarvot.

Täytä loput arvot käydessäsi läpi alla olevia käyttöönottovaiheita; osa arvoista on saatavilla vasta käyttöönoton aikana. Salaisuudet menevät gitignore-listattuun .env-tiedostoon; ei-salaiset muuttujat menevät .env.devnet-tiedostoon.

Salaisuudet – aseta nämä välittömästi:

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

Käyttöönoton aikana saatavat muuttujat:

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>

Täydellinen ympäristömuuttujien viite löytyy Konfiguraatiosta.

Käyttöönotto

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>

Ylläpitotoiminnot

Hyödyllisiä komentoja

# 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

Havainnointikyky

Pino sisältää Prometheuksen, Grafanan ja cAdvisorin mittareita ja konttien seurantaa varten. Grafana on käytettävissä portissa 37429.

Vianmääritys

Kanavan saldo ei päivity talletuksen jälkeen

1. Varmista, että Mainnet-talletustransaktio näkyy Mainnet-selaimessa
2. Varmista, että indexer-solana on käynnissä: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
3. Varmista, että operator-solana on käynnissä: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
4. Tarkista, että Yellowstone gRPC -päätepisteesi on tavoitettavissa ja token on kelvollinen (DEVNET_YELLOWSTONE_ENDPOINT, INDEXER_YELLOWSTONE_TOKEN)
5. Odota enintään 30 sekuntia ketjussa tapahtuvan vahvistuksen jälkeen, sillä indekseri soveltaa lopullisuuden turvaviivettä ennen hyvitystä

Nosto ei tiliinty Mainnetiin

1. Varmista, että indexer-private-channel on käynnissä: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
2. Varmista, että operator-private-channel on käynnissä: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
3. Varmista, että ADMIN_PRIVATE_KEY-muuttujan operaattorin keypair vastaa AddOperator-komennolla ketjuun rekisteröityä avainta
4. Jos lokit näyttävät "SMT root mismatch" -virheen, palvelu sammuttaa itsensä sen sijaan, että lähettäisi virheellisen todistuksen. Pysäytä pino, palauta johdonmukaisesta tilasta ja käynnistä uudelleen

JWT-todennusvirheet (401 kaikissa pyynnöissä)

1. Varmista, että JWT_SECRET on täsmälleen sama sekä yhdyskäytävän että auth-palvelun konteissa
2. Varmista, että pino käynnistettiin --profile auth -lipulla
3. Tokenit vanhenevat 24 tunnin jälkeen; todenna uudelleen saadaksesi uuden tokenin

Ensimmäinen rakennus kestää liian kauan

Tämä on odotettua. Ensimmäinen make docker-devnet-build kääntää kaikki Rust-palvelut ja voi kestää 30–60 minuuttia tyypillisellä laitteistolla. Myöhemmät rakennukset käyttävät Docker-kerrosvälimuistia ja ovat huomattavasti nopeampia.

Seuraavat vaiheet