Genel Bakış

Private Channels güvenlik denetiminden geçmemiştir ve gerçek fonlarla üretim ortamında kullanımı, kapsamlı bir güvenlik incelemesi yapılmadan önerilmez.

Bir örnek mi dağıtıyorsunuz? Operatör kılavuzuna gidin. Mevcut bir örneğe entegrasyon mu yapıyorsunuz? Hızlı Başlangıç bölümüne gidin. Bu sayfa her iki kitle için de mimari referansıdır.

Mimari

Private Channels dört bileşenden oluşur: zincir üzerinde iki Solana programı (Escrow ve Withdraw) ve zincir dışı iki servis (Gateway ve Auth Service). Birlikte, fonların Mainnet'te yaşadığı ancak transferlerin zincir dışında tamamlandığı bir durum kanalı protokolü oluştururlar.

Escrow Programı

Escrow Programı, yatırılan SPL tokenlarını tutan zincir üzerinde bir Solana programıdır. Sistemin güven çıpasıdır: tüm fonlar, bir operatör geçerli bir Seyrek Merkle Ağacı dışlama kanıtı sağlayana kadar nihayetinde escrow'da kalır.

Program ID: 9tgHa1DcnaSSUtmMsst8ovKTe1Gfxzezn27KnH9xXYeU
Bu ID, declare_id!() aracılığıyla program ikili dosyasına derlenir. Zincir dışı servisler aynı ID'yi derleme zamanında oluşturulan istemci crate'inden okur, bir ortam değişkeninden değil.
Instance, AllowedMint ve Operator PDA'larını yönetir
Talimatlar: CreateInstance, AllowMint, BlockMint, AddOperator, RemoveOperator, SetNewAdmin, Deposit, ReleaseFunds, ResetSmtRoot

Withdraw Programı

Withdraw Programı, Solana Mainnet'te değil, özel kanal ağı üzerinde çalışır. Kullanıcılar kanal tarafındaki token bakiyelerini yakmak için WithdrawFunds fonksiyonunu çağırır. Bu yakma işlemi fonları otomatik olarak serbest bırakmaz; operatöre bir çekimin beklemede olduğunu bildirir. Operatör daha sonra tamamlanmış uzlaşma için geçerli bir SMT kanıtıyla Escrow Programı üzerinde ReleaseFunds fonksiyonunu çağırır.

Program ID: J231K9UEpS4y4KAPwGc4gsMNCjKFRMYcQBcjVW7vBhVi
Bu ID program ikili dosyasına derlenir. Zincir dışı servisler aynı ID'yi derleme zamanında oluşturulan istemci crate'inden okur, bir ortam değişkeninden değil.

Gateway

Gateway, istemci isteklerini kanal ağının yazma düğümüne (işlem gönderimi için) ve okuma düğümüne (sorgular için) yönlendiren Solana JSON-RPC uyumlu bir proxy'dir. Ortam değişkenleri aracılığıyla yapılandırılır: GATEWAY_PORT, GATEWAY_WRITE_URL, GATEWAY_READ_URL.

Sağlık uç noktaları (kimlik doğrulama gerekmez):

GET /health - canlılık kontrolü; 200 {"status":"ok"} döndürür
GET /ready - derin hazırlık kontrolü, yazma ve okuma düğümlerini test eder; 200 {"status":"ready"} veya 503 {"status":"degraded"} döndürür

RPC Yöntemi Yönlendirme ve Erişim

Gateway, sendTransaction isteklerini yazma düğümüne, diğer tüm yöntemleri ise okuma düğümüne yönlendirir. 64 KB'dan büyük istekler HTTP 413 ile reddedilir. Kimlik doğrulama etkinleştirildiğinde, yöntem erişimi JWT rolüyle denetlenir. Tam yöntem matrisi için Kimlik Doğrulama ve Roller bölümüne bakın.

Auth Service

Auth Service, ağ geçidi erişim kontrolü için HS256 JWT'leri (24 saatlik geçerlilik süresi) veren isteğe bağlı bir bileşendir. JWT_SECRET ortam değişkeni ayarlandığında etkinleşir. Bu değişken olmadan gateway tüm bağlantıları kabul eder.

JWT talepleri: sub (kullanıcı UUID'si), role ("user" veya "operator"), iss ("private-channel-auth"), aud ("private-channel-gateway"), exp (Unix zaman damgası). iss ve aud, gateway'in JWT yapılandırması tarafından doğrulanır; uygulama talep yapısına seri hale getirilmez: uygulama katmanı kodunda yalnızca sub, role ve exp kullanılabilir.

Roller:

user - erişim yalnızca doğrulanmış kendi cüzdanlarıyla sınırlıdır; getBlock, getTransaction veya simulateTransaction çağrıları yapamaz
operator - tüm sahiplik kontrollerini atlar; tam RPC yöntemi erişimine sahiptir; veritabanında sağlanması gerekir (kendi kendine yetki yükseltme yapılamaz)

Streamer

Streamer, RPC'yi sorgulamaya gerek kalmadan bağlı istemcilere kanal durum güncelmelerini gerçek zamanlı olarak ileten bir WebSocket sunucusudur. PostgreSQL'i durum değişiklikleri için yoklar. Temel Docker Compose yığınının bir parçasıdır; bu kılavuzun dağıttığı devnet yığınının değil. Daha fazla bilgi için Yapılandırma referansına bakın.

Port: 8902, STREAMER_PORT aracılığıyla yapılandırılabilir
Bağlantı: ws://localhost:8902
Sağlık uç noktası: GET /health - herhangi bir dahili yoklama döngüsü 30 saniyenin ötesinde takılırsa 503 döndürür

WebSocket olay şeması henüz kamuya açık olarak belgelenmemiştir. Resmi belgeler mevcut olana kadar uygulama ayrıntıları için core/src/bin/streamer.rs dosyasına başvurun.

İşlem Hattı

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

Gateway'e gönderilen işlemler, durumları kaydedilmeden önce beş aşamalı bir hattan geçer:

Tekilleştirme (Dedup) - yinelenen işlemleri hatta girmeden önce filtreler
İmza Doğrulama (SigVerify) - işlem imzalarını imzalayanın açık anahtarına karşı doğrular
Sıralayıcı (Sequencer) - geçerli işlemleri kanonik bir geçmiş oluşturmak için deterministik biçimde sıralar
Yürütücü (Executor) - işlemleri kanalın hesap katmanına karşı yürütür (BOB Cache + AccountsDB), bakiyeleri zincir dışında günceller
Uzlaştırıcı (Settler) - birikmiş işlem sonuçlarını PostgreSQL'e kaydeder ve Redis önbelleğini günceller; bir sonraki blok döngüsü için yeni blok karmaları oluşturur. Mainnet uzlaşması (ReleaseFunds çağrısı) operator-private-channel servisi tarafından ayrıca gerçekleştirilir

Temel Özellikler

Gizlilik

Kanal katılımcıları arasındaki transferler Solana Mainnet'e kaydedilmez. Yalnızca yatırma işlemleri (kanala giriş) ve nihai çekimler (kanaldan çıkış) zincir üzerinde görünür. Karşı taraf kimlikleri ve transfer miktarları, kanal operasyonu sırasında dış gözlemcilere görünmez.

Performans

Zincir dışı işlem hattı, Solana'nın blok süresini kritik yoldan çıkarır. Transferler, bir Solana bloğu onaylandığında değil, sıralayıcı bunları işlediğinde onaylanır. Bu, uygulama katmanı transferleri için saniyenin altında kesinlik ve Solana'nın yerel TPS'ini aşan verim sağlar.

Uzlaşma

Her çekim, zincir üzerindeki bir Seyrek Merkle Ağacı kanıtıyla korunur. SMT kökü, Escrow Programındaki Instance.withdrawal_transactions_root alanında saklanır. ReleaseFunds çağrıldığında program önce mevcut zincir üstü köke karşı görülmemiş bir nonce için bir dışlama kanıtını doğrular, ardından o nonce için çağıran tarafından sağlanan yeni köke karşı ayrı bir dahil etme kanıtını doğrular. Her iki kontrol de geçtikten sonra yeni kökü saklar; bu da bir operatör anahtarı ele geçirilse bile çift harcamayı imkânsız kılar.

Güvenlik Modeli

Yönetici anahtarı - örnek oluşturma (CreateInstance) ve operatör sağlamayı (AddOperator / RemoveOperator) kontrol eder. Yönetici anahtarının ele geçirilmesi, rastgele operatör sağlamaya olanak tanır. SetNewAdmin, yönetici yetkisini tek bir adımda geri döndürülemez biçimde devreder; yönetici anahtarını buna göre koruyun.

Operatör anahtarları - ReleaseFunds ve ResetSmtRoot fonksiyonlarını çağırabilir. Ancak mevcut zincir üstü köke karşı geçerli bir SMT dışlama kanıtı olmadan fonları serbest bırakamazlar. Zincir üstü verify_smt_exclusion_proof kontrolü, yetkisiz çekimlere karşı son savunma hattıdır: ele geçirilmiş bir operatör anahtarı tek başına escrow'u boşaltmak için yeterli değildir.

SMT kökü - zincir üzerinde Instance.withdrawal_transactions_root alanında saklanır. Her ReleaseFunds çağrısıyla atomik olarak güncellenir. Her kanıtın görülmemiş bir nonce'a başvurması gerektiğinden, bir operatör anahtarı ele geçirilse bile aynı kanal bakiyesini çift harcamak imkânsızdır.

Ağaç rotasyonu - Instance.current_tree_index, ağaç epoch'larını takip eder. ResetSmtRoot çağrıldığında ağaç indeksini artırır ve önceki ağaç epoch'undaki tüm nonce'ları geçersiz kılar; yeni uzlaşma döngüleri için temiz bir başlangıç noktası sağlar.

Operasyonel Anahtar Güvenliği

Zincir dışı servisler, yukarıdaki Güvenlik Modeli'nde açıklanan zincir üstü yönetici/operatör yetkilerinden bağımsız olan kendi imzalayan söz dağarcığını kullanır. ADMIN_PRIVATE_KEY her operatör servisi için zorunludur ve işlem ücretlerini öder; ayrı ve isteğe bağlı olan OPERATOR_PRIVATE_KEY, ReleaseFunds ve ResetSmtRoot için zincir üstü Operatör imzasını sağlar ve ayarlanmadığında ADMIN_PRIVATE_KEY değerine geri döner. Protokol düzeyindeki örnek yönetici anahtarını (CreateInstance / AddOperator / SetNewAdmin için kullanılan) bu değişkenlerin hiçbirine koymayın veya çalışma zamanında açığa çıkarmayın; bu anahtarı soğuk ve çevrimdışı tutun.

ReleaseFunds ve ResetSmtRoot, iki zincir üstü imza gerektirir: ücret ödeyici (ADMIN_PRIVATE_KEY'den) ve Operatör PDA'sının yetkisi (OPERATOR_PRIVATE_KEY'den veya ayarlanmamışsa ADMIN_PRIVATE_KEY'den). Bu dağıtım kılavuzunun devnet rehberi, oluşturulan operatör keypair'ini ADMIN_PRIVATE_KEY'e koyar ve OPERATOR_PRIVATE_KEY'i ayarlamadan bırakır; böylece aynı keypair her iki imzalayan rolünü de üstlenir. ADMIN_PRIVATE_KEY'e hangi anahtar girerse, ona sıcak cüzdan özel anahtarıyla aynı kontrollerle davranın:

Yalnızca git tarafından yoksayılan .env dosyasında saklayın; .env.devnet veya işleme alınmış herhangi bir yapılandırma dosyasında asla saklamayın
Üretim dağıtımları için düz metin ortam değişkeni yerine bir gizli dizi yöneticisi (AWS Secrets Manager, HashiCorp Vault) kullanmayı değerlendirin
Protokol düzeyindeki örnek yönetici keypair'i (AddOperator / SetNewAdmin çağrısı için kullanılan) soğuk tutulmalıdır; yalnızca örnek kurulumu ve operatör sağlama sırasında gereklidir, çalışma zamanında değil

SetNewAdmin, yönetici haklarını tek bir işlemde geri döndürülemez biçimde devreder: mevcut yöneticinin, yeni yöneticinin işbirliği olmadan kurtarma yolu yoktur. Hedef adresi doğrulamadan çağırmayın.