Übersicht

Architektur

Private Channels besteht aus vier Komponenten: zwei On-Chain-Solana-Programmen (Escrow und Withdraw) und zwei Off-Chain-Diensten (Gateway und Auth Service). Zusammen bilden sie ein State-Channel-Protokoll, bei dem Geldmittel auf Mainnet verbleiben, Transfers jedoch Off-Chain abgewickelt werden.

Escrow-Programm

Das Escrow-Programm ist ein On-Chain-Solana-Programm, das hinterlegte SPL-Token verwahrt. Es ist der Vertrauensanker des Systems: Alle Geldmittel verbleiben letztendlich im Escrow, bis ein Betreiber einen gültigen Sparse-Merkle-Tree-Ausschlussbeweis zur Freigabe vorlegt.

• Programm-ID: 9tgHa1DcnaSSUtmMsst8ovKTe1Gfxzezn27KnH9xXYeU
• Diese ID wird über declare_id!() in das Programm-Binary kompiliert. Off-Chain-Dienste lesen dieselbe ID zur Kompilierzeit aus dem generierten Client-Crate, nicht aus einer Umgebungsvariable.
• Verwaltet Instance-, AllowedMint- und Operator-PDAs
• Anweisungen: CreateInstance, AllowMint, BlockMint, AddOperator, RemoveOperator, SetNewAdmin, Deposit, ReleaseFunds, ResetSmtRoot

Withdraw-Programm

Das Withdraw-Programm läuft im privaten Channel-Netzwerk, nicht auf Solana Mainnet. Benutzer rufen WithdrawFunds auf, um ihr kanalseitiges Token-Guthaben zu verbrennen. Dieses Verbrennen gibt keine Geldmittel automatisch frei; es signalisiert dem Betreiber, dass eine Auszahlung aussteht. Der Betreiber ruft daraufhin ReleaseFunds auf dem Escrow-Programm mit einem gültigen SMT-Beweis auf, um die Abwicklung abzuschließen.

• Programm-ID: J231K9UEpS4y4KAPwGc4gsMNCjKFRMYcQBcjVW7vBhVi
• Diese ID wird in das Programm-Binary kompiliert. Off-Chain-Dienste lesen dieselbe ID zur Kompilierzeit aus dem generierten Client-Crate, nicht aus einer Umgebungsvariable.

Gateway

Das Gateway ist ein Solana-JSON-RPC-kompatibler Proxy, der Client-Anfragen an den Schreibknoten des Channel-Netzwerks (für die Transaktionsübermittlung) und den Leseknoten (für Abfragen) weiterleitet. Es wird über Umgebungsvariablen konfiguriert: GATEWAY_PORT, GATEWAY_WRITE_URL, GATEWAY_READ_URL.

Health-Endpunkte (keine Authentifizierung erforderlich):

• GET /health - Liveness-Check; gibt 200 {"status":"ok"} zurück
• GET /ready - Tiefe Bereitschaftsprüfung, testet Schreib- und Leseknoten; gibt 200 {"status":"ready"} oder 503 {"status":"degraded"} zurück

RPC-Methoden-Routing und Zugriff

Das Gateway leitet sendTransaction an den Schreibknoten weiter und alle anderen Methoden an den Leseknoten. Anfragen größer als 64 KB werden mit HTTP 413 abgelehnt. Wenn die Authentifizierung aktiviert ist, wird der Methodenzugriff durch JWT-Rollen gesteuert. Siehe Authentifizierung & Rollen für die vollständige Methodenmatrix.

Auth Service

Der Auth Service ist eine optionale Komponente, die HS256-JWTs (24-Stunden-Ablauf) für die Gateway-Zugriffskontrolle ausstellt. Er wird aktiviert, wenn die Umgebungsvariable JWT_SECRET gesetzt ist. Ohne diese akzeptiert das Gateway alle Verbindungen.

JWT-Claims: sub (Benutzer-UUID), role ("user" oder "operator"), iss ("private-channel-auth"), aud ("private-channel-gateway"), exp (Unix-Zeitstempel). iss und aud werden durch die JWT-Konfiguration des Gateways validiert, nicht in den Anwendungs-Claims-Struct deserialisiert: Nur sub, role und exp stehen dem Anwendungsschicht-Code zur Verfügung.

Rollen:

• user - Zugriff auf eigene verifizierte Wallets beschränkt; kann getBlock, getTransaction oder simulateTransaction nicht aufrufen
• operator - umgeht alle Eigentümerschaftsprüfungen; voller RPC-Methodenzugriff; muss in der Datenbank bereitgestellt werden (keine Self-Service-Eskalation)

Streamer

Der Streamer ist ein WebSocket-Server, der verbundenen Clients in Echtzeit Channel-Statusaktualisierungen überträgt und so das Polling des RPC überflüssig macht. Er fragt PostgreSQL nach Statusänderungen ab. Er ist Teil des grundlegenden Docker-Compose-Stacks, nicht des Devnet-Stacks, den dieser Leitfaden deployt; siehe die Konfigurationsreferenz.

• Port: 8902, konfigurierbar über STREAMER_PORT
• Verbinden: ws://localhost:8902
• Health-Endpunkt: GET /health - gibt 503 zurück, wenn eine interne Poll-Schleife länger als 30 Sekunden blockiert

Transaktions-Pipeline

Transaction -> [1:Dedup] -> [2:SigVerify] -> [3:Sequencer] -> [4:Executor] -> [5:Settler] -> Database

Transaktionen, die an das Gateway übermittelt werden, durchlaufen eine fünfstufige Pipeline, bevor ihr Status festgeschrieben wird:

1. Dedup - filtert doppelte Transaktionen heraus, bevor sie in die Pipeline gelangen
2. SigVerify - validiert Transaktionssignaturen gegen den öffentlichen Schlüssel des Signer
3. Sequencer - ordnet gültige Transaktionen deterministisch an, um eine kanonische Historie zu etablieren
4. Executor - führt Transaktionen gegen die Konten-Schicht des Channels (BOB Cache + AccountsDB) aus und aktualisiert Guthaben Off-Chain
5. Settler - schreibt akkumulierte Transaktionsergebnisse in PostgreSQL und aktualisiert den Redis-Cache; generiert neue Blockhashes für den nächsten Block-Zyklus. Die Mainnet-Abwicklung (Aufruf von ReleaseFunds) wird separat durch den operator-private-channel-Dienst verarbeitet

Hauptmerkmale

Datenschutz

Transfers zwischen Kanal-Teilnehmern werden nicht auf Solana Mainnet aufgezeichnet. Nur Einzahlungen (Eintritt in den Kanal) und endgültige Auszahlungen (Verlassen des Kanals) erscheinen On-Chain. Gegenparteiidentitäten und Transferbeträge sind für außenstehende Beobachter während des Kanalbetriebs nicht sichtbar.

Leistung

Die Off-Chain-Pipeline entfernt Solanas Blockzeit aus dem kritischen Pfad. Transfers werden bestätigt, wenn der Sequencer sie verarbeitet, nicht wenn ein Solana-Block bestätigt. Dies ermöglicht Sub-Sekunden-Finalität und einen Durchsatz jenseits von Solanas nativem TPS für App-Schicht-Transfers.

Abwicklung

Jede Auszahlung wird durch einen On-Chain-Sparse-Merkle-Tree-Beweis abgesichert. Die SMT-Wurzel wird in Instance.withdrawal_transactions_root im Escrow-Programm gespeichert. Beim Aufruf von ReleaseFunds verifiziert das Programm zunächst einen Ausschlussbeweis für eine unbekannte Nonce gegen die aktuelle On-Chain-Wurzel und anschließend einen separaten Einschlussbeweis für diese Nonce gegen die vom Aufrufer übermittelte neue Wurzel. Erst nachdem beide Prüfungen bestanden sind, speichert es die neue Wurzel, wodurch ein Doppelausgaben-Angriff unmöglich wird, selbst wenn ein Betreiberschlüssel kompromittiert ist.

Sicherheitsmodell

Admin-Schlüssel - kontrolliert die Instanzerstellung (CreateInstance) und die Betreiber-Bereitstellung (AddOperator / RemoveOperator). Eine Kompromittierung des Admin-Schlüssels ermöglicht eine beliebige Betreiber-Bereitstellung. SetNewAdmin überträgt die Admin-Autorität unwiderruflich in einem einzigen Schritt; schützen Sie den Admin-Schlüssel entsprechend.

Betreiberschlüssel - können ReleaseFunds und ResetSmtRoot aufrufen. Sie können keine Geldmittel ohne einen gültigen SMT-Ausschlussbeweis gegen die aktuelle On-Chain-Wurzel freigeben. Die On-Chain-Prüfung verify_smt_exclusion_proof ist die letzte Verteidigungslinie gegen unbefugte Auszahlungen: Ein kompromittierter Betreiberschlüssel allein reicht nicht aus, um den Escrow zu leeren.

SMT-Wurzel - On-Chain in Instance.withdrawal_transactions_root gespeichert. Atomar mit jedem ReleaseFunds-Aufruf aktualisiert. Da jeder Beweis eine unbekannte Nonce referenzieren muss, ist ein Doppelausgaben-Angriff auf dasselbe Kanalguthaben unmöglich, selbst wenn ein Betreiberschlüssel kompromittiert ist.

Baumrotation - Instance.current_tree_index verfolgt Baum-Epochen. Wenn ResetSmtRoot aufgerufen wird, inkrementiert es den Baumindex und invalidiert alle Nonces aus der vorherigen Baum-Epoche, was einen sauberen Zustand für neue Abwicklungszyklen bietet.

Operative Schlüsselsicherheit

ReleaseFunds und ResetSmtRoot erfordern zwei On-Chain-Signaturen: den Fee-Zahler (aus ADMIN_PRIVATE_KEY) und die Autorität des Operator-PDAs (aus OPERATOR_PRIVATE_KEY oder ADMIN_PRIVATE_KEY, wenn dieser nicht gesetzt ist). Die Devnet-Anleitung dieses Deployment-Leitfadens legt das generierte Operator-keypair in ADMIN_PRIVATE_KEY und lässt OPERATOR_PRIVATE_KEY ungesetzt, sodass dasselbe keypair beide Signer-Rollen übernimmt. Behandeln Sie den Schlüssel, der letztendlich in ADMIN_PRIVATE_KEY landet, mit denselben Kontrollen wie einen privaten Schlüssel einer Hot Wallet:

• Speichern Sie ihn nur in der per gitignore ausgeschlossenen .env-Datei, niemals in .env.devnet oder einer eingecheckten Konfiguration
• Erwägen Sie für Produktions-Deployments einen Secrets-Manager (AWS Secrets Manager, HashiCorp Vault) anstelle einer Klartextumgebungsvariable
• Das keypair des protokollseitigen Instanz-Admins (verwendet zum Aufrufen von AddOperator / SetNewAdmin) sollte kalt aufbewahrt werden; es wird nur während der Instanzeinrichtung und Betreiber-Bereitstellung benötigt, nicht zur Laufzeit

SetNewAdmin überträgt Admin-Rechte unwiderruflich in einer einzigen Transaktion: Der aktuelle Admin hat ohne die Mitwirkung des neuen Admins keinen Wiederherstellungspfad. Rufen Sie es nicht auf, ohne die Zieladresse zu verifizieren.

Nächste Schritte