Operators

Τι είναι ένας Operator του Private Channels;

Ένας operator είναι μια αξιόπιστη οντότητα με άδεια on-chain που γεφυρώνει το Solana Mainnet και το δίκτυο ιδιωτικών καναλιών. Οι operators προβλέπονται από τον διαχειριστή της παρουσίας μέσω του AddOperator, το οποίο δημιουργεί ένα on-chain Operator PDA· χωρίς αυτό, κανένα μέρος δεν μπορεί να καλέσει το ReleaseFunds. Στην πράξη, ένας operator είναι ένας οργανισμός ή ομάδα που εκτελεί τις υπηρεσίες που παρακολουθούν καταθέσεις, κόβουν τokens στην πλευρά του καναλιού, εντοπίζουν αναλήψεις και διακανονίζουν κεφάλαια πίσω στο Mainnet. Η εκτέλεση μιας παρουσίας παρέχει στους χρήστες σας ιδιωτικές μεταφορές μεγάλου όγκου που δεν εμφανίζονται στο Solana Mainnet, άμεση ροή χωρίς τέλη που υπερβαίνει το εγγενές Solana TPS, και ελεγχόμενη πρόσβαση μέσω RBAC.

Πριν Ξεκινήσετε

Προαπαιτούμενα

Καρφιτσώστε αυτές τις εκδόσεις στον host ώστε να ταιριάζουν με τις Docker images:

• Docker Engine 26+ (macOS Apple Silicon: ενεργοποιήστε το "Docker VMM" στις Ρυθμίσεις -> Virtual Machine Options)
• Node.js 24.7.0 και pnpm 10.15.1
• Solana CLI 3.1.13 (Agave)
• Rust 1.91.0
• Ένα Yellowstone gRPC endpoint για το Devnet (διαθέσιμο από Helius, Triton, QuickNode)

Για τις απαιτήσεις δικτύου και τις προεπιλεγμένες αναθέσεις θυρών, δείτε docs/TECHNICAL_REQUIREMENTS.md στο αποθετήριο.

Εγκαταστήστε την καρφιτσωμένη αλυσίδα εργαλείων Solana και προθερμάνετε την προσωρινή μνήμη SBF:

make install-toolchain

Υπηρεσίες

Η εκτέλεση μιας παρουσίας Private Channels σημαίνει ότι αναλαμβάνετε πέντε συνεχείς υπευθυνότητες, καθεμία από τις οποίες διαχειρίζεται ειδικά containers στο Docker Compose stack:

1. Ευρετηρίαση Mainnet για καταθέσεις - το indexer-solana παρακολουθεί το Solana Mainnet για συμβάντα Deposit μέσω Yellowstone gRPC· το operator-solana παραλαμβάνει επιβεβαιωμένες καταθέσεις και κόβει το αντίστοιχο υπόλοιπο token στο δίκτυο καναλιών
2. Ευρετηρίαση καναλιού για αναλήψεις - το indexer-private-channel ελέγχει το κανάλι κάθε δευτερόλεπτο για συμβάντα burn WithdrawFunds και γράφει εκκρεμείς εγγραφές ανάληψης στη βάση δεδομένων
3. Αποδέσμευση κεφαλαίων στο Mainnet - το operator-private-channel παραλαμβάνει εκκρεμείς εγγραφές και καλεί το ReleaseFunds στο Escrow Program με έγκυρη απόδειξη αποκλεισμού SMT
4. Διαχείριση του SMT root - το operator-private-channel καλεί το ResetSmtRoot αυτόματα όταν γίνεται εναλλαγή epoch του δέντρου· ο on-chain έλεγχος verify_smt_exclusion_proof είναι η τελευταία γραμμή άμυνας κατά μη εξουσιοδοτημένων αναλήψεων
5. Εκτέλεση gateway και υπηρεσίας auth - το gateway είναι το μοναδικό δημόσιο endpoint για όλη την κίνηση clients· η υπηρεσία auth (προαιρετική) επιβάλλει JWT/RBAC όταν έχει οριστεί το JWT_SECRET

Για το πλήρες ευρετήριο υπηρεσιών και τις αναθέσεις θυρών, δείτε την Αναφορά Διαμόρφωσης.

Σημείωση ασφαλείας: Οι θύρες write-node και read-node δεσμεύονται μόνο στο loopback (127.0.0.1), αλλά αρκετές άλλες υπηρεσίες (gateway, auth, μετρικά operator, Grafana, Prometheus, cAdvisor) δημοσιεύονται σε όλες τις διεπαφές δικτύου από προεπιλογή. Δείτε την Αναφορά Διαμόρφωσης για τον πλήρη πίνακα θυρών και προστατέψτε τις με τείχος προστασίας πριν από οποιαδήποτε δημόσια ανάπτυξη. Το RBAC καλύπτει μόνο τις δικές του μεθόδους JSON-RPC του gateway, όχι αυτές τις άλλες υπηρεσίες.

Έλεγχος Πρόσβασης: Ανοιχτός vs. RBAC

Από προεπιλογή το gateway δέχεται όλες τις συνδέσεις· δεν απαιτούνται tokens. Για να ενεργοποιήσετε RBAC βάσει JWT, ορίστε το JWT_SECRET και εκκινήστε το stack με --profile auth. Δείτε Πιστοποίηση & Ρόλοι για την πλήρη αναφορά διαμόρφωσης, συμπεριλαμβανομένου του τρόπου παροχής του ρόλου operator και καταχώρισης των wallets χρηστών.

Αν ενεργοποιείτε το auth, προσθέστε τα παρακάτω στο περιβάλλον σας πριν εκκινήσετε το stack:

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

Ρύθμιση Περιβάλλοντος

Το .env.devnet παρακολουθείται ήδη στο αποθετήριο με προεπιλεγμένες τιμές ειδικές για devnet συμπληρωμένες· επεξεργαστείτε το απευθείας αντί να το αναδημιουργήσετε από το .env.example, κάτι που θα αντικαθιστούσε αυτές τις προεπιλογές.

Συμπληρώστε τις υπόλοιπες τιμές καθώς εργάζεστε στα βήματα ανάπτυξης παρακάτω· ορισμένες είναι διαθέσιμες μόνο στη μέση της ανάπτυξης. Τα secrets πηγαίνουν στο gitignored αρχείο .env· οι μη εμπιστευτικές μεταβλητές πηγαίνουν στο .env.devnet.

Secrets - ορίστε τα αμέσως:

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

Μεταβλητές που λαμβάνονται κατά την ανάπτυξη:

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>

Για την πλήρη αναφορά μεταβλητών περιβάλλοντος, δείτε Διαμόρφωση.

Ανάπτυξη

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>

Λειτουργίες

Χρήσιμες Εντολές

# 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

Παρατηρησιμότητα

Το stack περιλαμβάνει Prometheus, Grafana και cAdvisor για μετρικά και παρακολούθηση containers. Το Grafana είναι προσβάσιμο στη θύρα 37429.

Αντιμετώπιση Προβλημάτων

Το υπόλοιπο καναλιού δεν ενημερώνεται μετά την κατάθεση

1. Επιβεβαιώστε ότι η συναλλαγή κατάθεσης στο Mainnet ολοκληρώθηκε σε έναν Mainnet explorer
2. Επαληθεύστε ότι το indexer-solana εκτελείται: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
3. Επαληθεύστε ότι το operator-solana εκτελείται: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
4. Ελέγξτε ότι το Yellowstone gRPC endpoint σας είναι προσβάσιμο και το token είναι έγκυρο (DEVNET_YELLOWSTONE_ENDPOINT, INDEXER_YELLOWSTONE_TOKEN)
5. Περιμένετε έως 30 δευτερόλεπτα μετά την on-chain επιβεβαίωση, καθώς ο indexer εφαρμόζει μια καθυστέρηση ασφαλείας οριστικοποίησης πριν πιστώσει

Η ανάληψη δεν διακανονίζεται στο Mainnet

1. Επαληθεύστε ότι το indexer-private-channel εκτελείται: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
2. Επαληθεύστε ότι το operator-private-channel εκτελείται: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
3. Επιβεβαιώστε ότι το keypair operator στο ADMIN_PRIVATE_KEY ταιριάζει με το κλειδί καταχωρισμένο με AddOperator on-chain
4. Αν τα logs εμφανίζουν "SMT root mismatch", η υπηρεσία τερματίζει αντί να υποβάλει μη έγκυρη απόδειξη. Σταματήστε το stack, επαναφέρετε από συνεπή κατάσταση και επανεκκινήστε

Αποτυχίες πιστοποίησης JWT (401 σε όλα τα αιτήματα)

1. Επιβεβαιώστε ότι το JWT_SECRET είναι ίδιο τόσο στο gateway όσο και στα containers της υπηρεσίας auth
2. Επιβεβαιώστε ότι το stack εκκινήθηκε με --profile auth
3. Τα tokens λήγουν μετά από 24 ώρες· επαναπιστοποιηθείτε για να λάβετε νέο token

Η πρώτη δημιουργία διαρκεί πολύ

Αναμενόμενο. Η πρώτη εκτέλεση make docker-devnet-build μεταγλωττίζει όλες τις υπηρεσίες Rust και μπορεί να διαρκέσει 30-60 λεπτά σε τυπικό υλικό. Οι επόμενες δημιουργίες χρησιμοποιούν την προσωρινή μνήμη layer του Docker και είναι σημαντικά ταχύτερες.

Επόμενα Βήματα