Ana içeriğe geç

Blockchain Servisi

Blockchain Servisi, Cınga veri hattında üretilen ham stream kayıtlarının değişmezlik (immutability) ve bütünlük (integrity) garantisini sağlamak için tasarlanmış doğrulama katmanıdır.

Temel amaç:

  • Ham assembled verinin sonradan değiştirilmediğini kanıtlamak
  • Cihaz bazında zincirli kayıt (hash-only chain) tutmak
  • Üçüncü taraf doğrulamasını mümkün kılmak (firma/kişi kendi node’unu çalıştırabilir)

Sorumluluk​

  • stream.assembled.v1 eventini tüketmek
  • Cihaz bazında canonical payload hash üretmek
  • Önceki blok hash’i ile zincirleyerek yeni blok kaydı oluşturmak
  • Blok kaydını yerel/dağıtık blockchain node’larına yazmak
  • Başarıda blockchain.committed.v1, hatada blockchain.failed.v1 üretmek

Hash-Only Chain Politikası (V1)​

Bu mimaride blockchain'e ham payload yazılmaz.

Zincire yazılanlar:

  • payload_hash
  • prev_hash
  • block_hash
  • minimal doğrulama metadatası (device_id, stream_id, zaman, imza referansları)

Zincire yazılmayanlar:

  • assembly.payload_merged ham içerik
  • cihazın özel anahtar bilgisi

Böylece üçüncü taraf node’lar doğrulama yapabilir, fakat ham veriyi göremez.

Neden Stream.Assembled Aşaması?​

Bu servis ham veriyi en erken güvenli noktada zincirlemek için stream.assembled.v1 sonrası çalışır.

  • Ingest seviyesinde paketler parçalı olabilir.
  • Stream assembled aşamasında payload bütünleştiği için hash üretimi deterministik olur.
  • Sonraki katmanlar (calibration/synth/window) veriyi türetebilir; blockchain ham setin kanıtını taşır.

İşlem Akışı​

Veri Modeli​

Canonical Hash Girdisi​

Hash girdi seti deterministik olmalıdır:

  • device_id
  • stream_id
  • device_time
  • stream_time
  • assembly.payload_merged (sorted-key canonical JSON)

Öneri:

  • Canonical JSON serialize (sorted keys, stable number format)
  • Hash algoritması: SHA-256

Block Header (Örnek)​

{
  "block_version": 1,
  "device_id": "400000011D081B70",
  "stream_id": 9823412,
  "payload_hash": "sha256:ab12...",
  "prev_hash": "sha256:77fe...",
  "device_pubkey_id": "devkey-400000011D081B70-v3",
  "committed_at": "2026-03-12T20:10:02Z"
}

Cihaz Anahtar Yönetimi​

Cihaz güvenli anahtarı/anahtar referansı device detail katmanından çözümlenebilir.

Önerilen kaynak sırası:

  1. Redis device:{device_id}:detail
  2. DB devices tablosu (fallback)

Önerilen alanlar:

  • device_pubkey
  • device_pubkey_id
  • key_version
  • key_status

Not: Private key cihaz tarafında kalır; backend doğrulama için public key kullanır.

Dağıtık Node / Third-Party Doğrulama​

Servis mimarisi federasyon dostu olmalıdır:

  • Firma/üçüncü taraf kendi doğrulama node’unu çalıştırabilir.
  • Node’lar block stream’i çekip zincir bütünlüğünü bağımsız doğrular.
  • Consensus zorunluluğu V1’de hafif tutulabilir (permissioned append + signed proof).

V1 yaklaşımı:

  • Primary commit node + replica doğrulama node’ları
  • Node health bozuksa commit kuyruğa alınır, geri basılmaz

Topic ve Event Standardı​

  • Kafka topic:
    • cinga.blockchain.committed
    • cinga.blockchain.failed
  • Event:
    • blockchain.committed.v1
    • blockchain.failed.v1

Event Örnekleri​

blockchain.committed.v1​

{
  "event": "blockchain.committed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "bc-9f3f...",
    "producer_service": "blockchain-service",
    "produced_at": "2026-03-12T20:10:02.220Z",
    "process_ms": 24
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-03-12T20:09:58Z",
    "stream_time": "2026-03-12T20:10:00Z"
  },
  "data": {
    "payload_hash": "sha256:ab12...",
    "prev_hash": "sha256:77fe...",
    "block_hash": "sha256:d0aa...",
    "node_id": "chain-node-1",
    "key_version": 3
  },
  "error": null
}

blockchain.failed.v1​

{
  "event": "blockchain.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "bc-9f3f...",
    "producer_service": "blockchain-service",
    "produced_at": "2026-03-12T20:10:02.400Z",
    "process_ms": 45
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "data": null,
  "error": {
    "failed_stage": "blockchain",
    "error_code": "BLOCKCHAIN_COMMIT_FAIL",
    "error_message": "primary node write timeout",
    "retryable": true,
    "failed_at": "2026-03-12T20:10:02Z"
  }
}

V1 Locked Decisions​

Consensus Modeli (V1)​

  • Model: permissioned single-writer + multi-verifier
  • Zincire yazma yetkisi yalnız Cınga Blockchain Servisindedir.
  • Primary chain node yalnız bu servisten gelen imzalı commit taleplerini kabul eder.
  • Diğer node’lar doğrulayıcı/replica olarak çalışır.
  • PoW/PoS gibi ağır consensus mekanizmaları V1 kapsamı dışındadır.

Chain Scope (V1)​

  • Zincir kapsamı cihaz bazlıdır.
  • chain_id = device_id
  • Her cihaz kendi prev_hash zincirinde ilerler.

Canonicalization Standardı (V1)​

  • Hash girdi formatı deterministic canonical JSON olmalıdır.
  • V1 referans: JCS (RFC 8785) uyumlu canonicalization.
  • Aynı payload her node’da aynı hash’i üretmelidir.

İmza Modeli (V1)​

  • Her cihaz için imza kimliği device_id tabanlıdır.
  • device_sig_id = device_id (veya versiyonlu: device_id:vN)
  • device_sig: cihazın payload hash imzası (device private key)
  • server_sig: Cınga Blockchain Servisi'nin block header imzası (server private key)
  • Doğrulama için public key’ler device detail üzerinden çözülür.

Fork / Reorg Politikası (V1)​

  • V1’de no-fork policy uygulanır.
  • Primary dışı yazım kabul edilmez.
  • Replica divergence durumunda node read-only degraded moda alınır ve primary’den resync edilir.

Proof ve Doğrulama Arayüzü (V1)​

Önerilen doğrulama endpointleri:

  • get_block(device_id, stream_id)
  • verify_proof(device_id, stream_id, payload_hash, signatures)

Önerilen günlük audit çıktısı:

  • Günlük checkpoint/root hash yayını (3rd-party doğrulama için)

Key Rotation Politikası (V1)​

  • Her block kaydı key_version taşımalıdır.
  • Key rotation sırasında eski public key'ler doğrulama amaçlı arşivde tutulur.
  • Yeni key aktif olduktan sonra üretilen block'lar yeni key_version ile imzalanır.
  • Doğrulama katmanı geçmiş block doğrulamasında ilgili sürüm anahtarı kullanır.

Timestamp Politikası (V1)​

  • produced_at ve committed_at alanları UTC zorunludur.
  • Kabul toleransı: ±60s (clock skew koruması).
  • Tolerans dışı kayıtlar BLOCKCHAIN_TIME_SKEW hatasıyla rejected/logged edilir.

Commit Durability Kuralı (V1)​

blockchain.committed.v1 eventi yalnız şu koşulda üretilir:

  • Primary node yazımı başarılı + disk fsync tamamlandıktan sonra.

Replica ack gereksinimi:

  • V1'de zorunlu değildir (async verifier modeli).
  • V2'de opsiyonel quorum-ack modu eklenebilir.

Retry / Backfill Politikası​

  • Retryable commit hatalarında exponential backoff
  • Başarısız kayıtlar blockchain_commit_queue içinde saklanır
  • Backfill sırasında aynı device_id + stream_id için idempotent commit doğrulaması yapılır
  • Otomatik backfill aralığı: son 7 gün
  • Daha eski backfill yalnız manuel operasyon onayı ile çalıştırılır

Security Hardening (V1)​

  • Node erişimi mTLS veya güçlü API key ile sınırlandırılmalıdır.
  • get_block / verify_proof endpointleri rate-limit ile korunmalıdır.
  • Tüm commit/retry/backfill aksiyonları audit log’a yazılmalıdır.
  • Yetkisiz node yazım denemeleri BLOCKCHAIN_UNAUTHORIZED_NODE olarak loglanmalıdır.

Çıktı​

Blockchain Servisinin çıktısı:

  • Cihaz bazlı hash-zinciriyle değişmezlik kanıtı
  • Üçüncü taraf node’lar için doğrulanabilir block stream
  • Kafka’da commit/fail event görünürlüğü