Ledger Event Sozlesmeleri

Bu sayfa Ledger Servisi tarafindan uretilen eventlerin payload sozlesmelerini verir.

Event Haritasi

Event	Ne zaman kullanilir?	Producer	Consumer	Amac
ledger.committed.v1	Ledger halkasi basariyla yazildiginda	Ledger Servisi	Observer / Egress / Audit	Basarili zincir yazimini duyurmak
ledger.failed.v1	Ledger adimi teknik hatayla sonlandiginda	Ledger Servisi	Observer / Retry Worker	Hata gorunurlugu ve yeniden deneme

Ortak Envelope

{
  "event": "<name>.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "ldg-9f3f",
    "producer_service": "ledger-service",
    "produced_at": "2026-04-14T15:40:02.120Z",
    "process_ms": 18
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-14T15:39:58Z"
  },
  "data": {},
  "error": null
}

ledger.committed.v1

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: ledger.committed.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Sabit deger: ledger-service
meta.produced_at	datetime	Evet	Event uretim zamani
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kimligi
context.device_time	datetime	Evet	Cihaz zamani
data.payload_hash	string	Evet	Snapshot hash degeri
data.previous_hash	string	Evet	Bir onceki halka hash'i
data.transaction_hash	string	Evet	Bu halkaya ait hash
error	null	Evet	Basari eventinde null

Ornek

{
  "event": "ledger.committed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "ldg-9f3f",
    "producer_service": "ledger-service",
    "produced_at": "2026-04-14T15:40:02.120Z",
    "process_ms": 18
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-14T15:39:58Z"
  },
  "data": {
    "payload_hash": "sha256:ab12...",
    "previous_hash": "sha256:77fe...",
    "transaction_hash": "sha256:d0aa..."
  },
  "error": null
}

ledger.failed.v1

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: ledger.failed.v1
meta.*	object	Evet	Ortak metadata
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kimligi
error.failed_stage	string	Evet	payload, hash, persist, publish
error.error_code	string	Evet	Makine okunur hata kodu
error.error_message	string	Evet	Hata aciklamasi
error.retryable	boolean	Evet	Yeniden denenebilirlik
error.failed_at	datetime	Evet	Hata zamani

Ornek

{
  "event": "ledger.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "ldg-9f3f",
    "producer_service": "ledger-service",
    "produced_at": "2026-04-14T15:40:02.300Z",
    "process_ms": 31
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "data": null,
  "error": {
    "failed_stage": "persist",
    "error_code": "LEDGER_DB_WRITE_FAIL",
    "error_message": "ledger_transactions insert failed",
    "retryable": true,
    "failed_at": "2026-04-14T15:40:02Z"
  }
}

Retryable Karar Matrisi

• LEDGER_DB_WRITE_FAIL: true
• LEDGER_PREVIOUS_HASH_NOT_FOUND: true
• LEDGER_PAYLOAD_CANONICALIZATION_FAIL: false
• LEDGER_SCHEMA_INVALID: false