> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jetstream v2 Protokol Referansı

> OrbitFlare Jetstream v2 için Protocol Buffer belirtimi

## Mevcut Uç Noktalar

Jetstream v2, **v1 ile aynı uç noktalarda** sunulur; ayrı bir ana bilgisayar yoktur. `JetstreamV2` hizmeti, aynı
HTTP/2 bağlantısı üzerinden sunulur ve gRPC metot yoluna göre yönlendirilir, bu nedenle tıpkı v1'de yapacağınız
gibi altyapınıza en yakın bölgeye bağlanırsınız.

<Tabs>
  <Tab title="US">
    | Şehir          | Bölge Kodu | Uç Nokta                              |
    | -------------- | ---------- | ------------------------------------- |
    | New York       | `ny`       | `http://ny.jetstream.orbitflare.com`  |
    | Salt Lake City | `slc`      | `http://slc.jetstream.orbitflare.com` |
  </Tab>

  <Tab title="Europe">
    | Şehir               | Bölge Kodu | Uç Nokta                               |
    | ------------------- | ---------- | -------------------------------------- |
    | Frankfurt           | `fra`      | `http://fra.jetstream.orbitflare.com`  |
    | Amsterdam           | `ams`      | `http://ams.jetstream.orbitflare.com`  |
    | London              | `lon`      | `http://lon.jetstream.orbitflare.com`  |
    | Dublin              | `dub`      | `http://dub.jetstream.orbitflare.com`  |
    | Siauliai, Lithuania | `siau`     | `http://siau.jetstream.orbitflare.com` |
  </Tab>

  <Tab title="Asia Pacific">
    | Şehir     | Bölge Kodu | Uç Nokta                              |
    | --------- | ---------- | ------------------------------------- |
    | Tokyo     | `jp`       | `http://jp.jetstream.orbitflare.com`  |
    | Singapore | `sgp`      | `http://sgp.jetstream.orbitflare.com` |
  </Tab>
</Tabs>

<Note>
  Jetstream, gRPC bağlantıları için düz `http://` kullanır (`https://` değil). gRPC, HTTP/2 üzerinde kendi taşıma
  güvenliği müzakeresini kullanır. `https://` yalnızca özel düğümünüz bunu açıkça gerektiriyorsa kullanın.
</Note>

## Kimlik Doğrulama

Kimlik doğrulama v1 ile aynıdır: API anahtarınızı `x-token` gRPC meta veri başlığında sağlayın veya
IP beyaz listesi kimlik doğrulamasını kullanın. Ayrıntılar için bkz. [Kimlik Doğrulama](/tr/authentication).

## Protocol Buffer Belirtimi

Bu belge, OrbitFlare Jetstream v2 tarafından kullanılan Protocol Buffer (protobuf) belirtimini özetlemektedir. Tam
belirtim [GitHub depomuzda](https://github.com/orbitflare/orbitflare-sdk-proto-rs/blob/HEAD/protos/jetstream_v2.proto)
bulunabilir; istemcinizi oluşturmak için `jetstream_v2.proto` dosyasını oradan indirin veya aşağıda çoğaltılan
tanımı kullanın. `jetstream.v2` paketi v1'den tamamen bağımsızdır; ondan ayrı bir istemci oluşturun.

### Hizmet Tanımı

```protobuf theme={null}
syntax = "proto3";

package jetstream.v2;

import "google/protobuf/timestamp.proto";

service JetstreamV2 {
  rpc SubscribeTransactions(stream SubscribeTransactionsRequest) returns (stream SubscribeTransactionsResponse) {}

  // Server-streaming slot lifecycle events.
  rpc SubscribeSlots(SubscribeSlotsRequest) returns (stream SlotEvent) {}

  // Unary health/version probes.
  rpc Ping(PingRequest) returns (PongResponse) {}
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}
```

### İstek Mesajları

`SubscribeTransactions`, çift yönlü bir akıştır. İstemci, akış açıkken aboneliğini yönetmek için bir dizi istek
mesajı, her biri tam olarak bir yük taşıyan, gönderir.

#### SubscribeTransactionsRequest

```protobuf theme={null}
message SubscribeTransactionsRequest {
  oneof payload {
    Ping          ping           = 1;
    AddFilters    add_filters    = 2;
    RemoveFilters remove_filters = 3;
  }
}

message Ping {
  int32 ping_id = 1;
}
```

#### Filtre Ekleme

Filtreler, akış açıkken dinamik olarak eklenir. Her filtre, eşleşen her işlemde ve doğrulama onayında geri
yansıtılan, istemci tarafından seçilen bir `filter_id` taşır.

```protobuf theme={null}
message AddFilters {
  repeated TxFilter filters = 1;
}

message TxFilter {
  string                             filter_id = 1;  // client-provided, max 127 chars
  SubscribeRequestFilterTransactions filter    = 2;
}

message SubscribeRequestFilterTransactions {
  repeated string account_include  = 1;
  repeated string account_exclude  = 2;
  repeated string account_required = 3;
  // account_required matches a tx that references AT LEAST ONE of these accounts
  // (any-of — identical to account_include, and identical to v1). It is NOT the
  // "tx must contain ALL of these accounts" meaning.

  // Opt-in enrichment. Default false = lean response (core fields only). Set
  // true to also receive fee_payer / writable_accounts / program_ids /
  // compute_unit_price / compute_limit / tx_size. Applies to the whole
  // subscription: if any of your active filters sets this true, every
  // transaction you receive is enriched.
  bool include_enrichment = 4;
}
```

<Note>
  Bir filtre, `account_include` / `account_exclude` / `account_required` alanlarından en az birini belirtmelidir.
  Boş (her şeyle eşleşen) filtreler reddedilir; bkz. [FilterResult](#filter-validation).
</Note>

#### Filtre Kaldırma

```protobuf theme={null}
message RemoveFilters {
  repeated string filter_ids = 1;
}
```

### Yanıt Mesajları

#### SubscribeTransactionsResponse

Akıştaki her mesaj, istemcilerin boşlukları tespit edebilmesi için bir sunucu zaman damgası ve monoton olarak artan
bir `sequence` numarası (akış başına) taşır. Tam olarak bir yük ayarlanır.

```protobuf theme={null}
message SubscribeTransactionsResponse {
  google.protobuf.Timestamp created_at = 1;

  oneof payload {
    FilteredTransaction transaction       = 2;
    Pong                pong              = 3;
    FilterResult        filter_validation = 5;
    Heartbeat           heartbeat         = 6;
  }

  uint64 sequence = 4;
}

message Pong {
  int32 ping_id = 1;
}
```

#### Filtre Doğrulama

Her `AddFilters` / `RemoveFilters` sonrasında sunucu, kabulü onaylayan veya reddi açıklayan, filtre başına bir
`FilterResult` döndürür.

```protobuf theme={null}
message FilterResult {
  string filter_id        = 1;
  bool   accepted         = 2;
  string rejection_reason = 3;  // empty string when accepted=true (proto3 default elision)
}
```

#### Heartbeat

```protobuf theme={null}
message Heartbeat {
  // Server wall-clock at emit time, milliseconds since Unix epoch. Lets
  // clients measure one-way skew / network delay and age out stale
  // connections.
  uint64 server_ts_ms = 1;
}
```

#### Filtrelenmiş İşlem

Her eşleşen işlem, eşleştiği `filter_id` değerlerini listeler, ardından işlemin kendisi gelir.

```protobuf theme={null}
message FilteredTransaction {
  repeated string    filter_ids  = 1;
  TransactionMessage transaction = 2;
}

// TransactionMessage — a flat transaction representation (all fields inline).
// Fields 1-13 are the core transaction and are always present (the default
// "lean" output). Fields 14-22 are optional enrichment, emitted only when the
// session opts in via SubscribeRequestFilterTransactions.include_enrichment.
message TransactionMessage {
  // Identity / placement
  uint64 slot      = 1;
  bytes  signature = 2;  // primary signature (signatures[0])
  uint32 tx_index  = 3;  // position of this tx within its entry

  // Full signature set (repeated bytes)
  repeated bytes signatures = 4;

  // Always false: vote transactions are filtered out and never delivered (v1 and v2).
  bool is_vote = 5;

  // Message header
  uint32 num_required_signatures        = 6;
  uint32 num_readonly_signed_accounts   = 7;
  uint32 num_readonly_unsigned_accounts = 8;

  // Recent blockhash
  bytes recent_blockhash = 9;

  // Versioned-transaction flag.
  bool versioned = 10;

  // Core body contents
  repeated bytes                     account_keys          = 11;
  repeated CompiledInstruction       instructions          = 12;
  repeated MessageAddressTableLookup address_table_lookups = 13;

  // Enrichment — emitted only when the session opts in via
  // SubscribeRequestFilterTransactions.include_enrichment.
  bytes          fee_payer         = 14;
  repeated bytes writable_accounts = 15;
  repeated bytes program_ids       = 16;
  // Compute-unit price (micro-lamports per CU) from SetComputeUnitPrice; 0 if unset.
  // The per-CU price, NOT the total priority fee — total priority fee in lamports
  // ~= compute_unit_price * compute_limit / 1_000_000.
  uint64         compute_unit_price = 17;
  // Explicit SetComputeUnitLimit only; 0 if the tx sets none (no implicit
  // 200k-CU-per-instruction default is applied).
  uint32         compute_limit     = 18;
  uint32         tx_size           = 19;

  // Resolved addresses from a versioned tx's address_table_lookups. Emitted
  // only when enrichment is opted in (same gate as fields 14-19). Empty for a
  // legacy (non-versioned) tx; when a lookup can't be fully resolved,
  // alt_resolution_incomplete (field 22) is set and any addresses that did
  // resolve are still included.
  repeated bytes loaded_writable_addresses = 20;
  repeated bytes loaded_readonly_addresses = 21;

  // Set true when one or more of this transaction's address_table_lookups could
  // NOT be fully resolved, so the loaded_writable_addresses /
  // loaded_readonly_addresses above are INCOMPLETE. When true, resolve the tx's
  // accounts yourself from address_table_lookups (fetch the tables via
  // RPC). Default false = fully resolved. Emitted only under
  // enrichment (same gate as fields 14-21).
  bool alt_resolution_incomplete = 22;
}
```

#### Paylaşılan Türler

```protobuf theme={null}
message CompiledInstruction {
  uint32 program_id_index = 1;
  bytes  accounts         = 2;
  bytes  data             = 3;
}

message MessageAddressTableLookup {
  bytes account_key      = 1;
  bytes writable_indexes = 2;
  bytes readonly_indexes = 3;
}
```

### Slot Akışı

`SubscribeSlots`, slot yaşam döngüsü olaylarının bir sunucu akışıdır. Parametre almaz; akışı açın ve slotlar
ilerledikçe olayları alın.

```protobuf theme={null}
// SubscribeSlots takes no request parameters.
message SubscribeSlotsRequest {
}

enum SlotStatus {
  SLOT_STATUS_UNSPECIFIED = 0;
  SLOT_STATUS_ALIVE       = 1;  // first shred of this slot received
  SLOT_STATUS_COMPLETE    = 2;  // last shred of this slot received
  SLOT_STATUS_DEAD        = 3;  // slot skipped, or superseded by later slots without completing
}

message SlotEvent {
  uint64     slot           = 1;
  SlotStatus status         = 2;
  // 32-byte pubkey. Empty bytes (proto3 default) means the current leader is
  // unavailable.
  bytes      current_leader = 3;
  // Parent slot, from the first shred received for this slot. 0 means
  // "unknown parent" (e.g. a DEAD event for a slot that was never observed).
  uint64     parent_slot    = 4;
  uint64     sequence       = 5;  // monotonic per-stream
}
```

### Akışsız Metotlar

```protobuf theme={null}
message PingRequest {
  int32 count = 1;
}

message PongResponse {
  int32 count = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  string version = 1;
}
```

## Protokolü Kullanma

Tipik bir v2 istemcisi:

1. Yukarıdaki `jetstream.v2` tanımından istemci kodu oluşturur.
2. `SubscribeTransactions` çift yönlü akışını açar ve kimlik doğrulaması yapar (`x-token` başlığı veya IP beyaz listesi).
3. Her biri benzersiz bir `filter_id` içeren bir veya daha fazla `TxFilter` girişiyle bir `AddFilters` isteği gönderir.
4. `FilterResult` onaylarını, ardından `FilteredTransaction` mesajlarının akışını okur.
5. Akışı yeniden açmadan istediği zaman filtre ekler veya kaldırır.
6. Boşlukları tespit etmek için `sequence` izler ve bir bağlantı kapanmasını yeniden bağlanma sinyali olarak değerlendirir.
7. İsteğe bağlı olarak, slot yaşam döngüsü olayları için `SubscribeSlots` (ayrı bir akış) açar.

### Kod Oluşturma

TypeScript/JavaScript için:

```bash theme={null}
protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=. \
  --ts_proto_opt=esModuleInterop=true \
  jetstream_v2.proto
```

Rust için:

```bash theme={null}
protoc --rust_out=. jetstream_v2.proto
```

## En İyi Uygulamalar

1. **Filtreleme**
   * Her zaman en az bir hesap kısıtlaması ayarlayın; boş filtreler reddedilir.
   * Eşleşmeleri ilişkilendirebilmek ve filtreleri daha sonra kaldırabilmek için filtre başına kararlı, benzersiz bir `filter_id` kullanın.

2. **Zenginleştirme**
   * Ek alanlara ihtiyacınız olmadıkça `include_enrichment` alanını kapalı bırakın; sade çıktı daha küçüktür. Bunu
     etkinleştirmek gecikme eklemez; tek maliyet biraz daha büyük bir mesajdır.
   * Zenginleştirme abonelik genelindedir: herhangi bir filtrede etkinleştirmek, oturumun aldığı her işlemi zenginleştirir.

3. **Sıra ve Yeniden Bağlanma**
   * Bırakılan mesajları tespit etmek için `sequence` numarasını izleyin.
   * Otomatik yeniden bağlanma uygulayın; yeniden bağlanırken `AddFilters` isteğinizi yeniden gönderin.

4. **Canlılık**
   * Akışın sağlıklı olduğunu doğrulamak ve gecikmeyi ölçmek için `Heartbeat` ve `Ping`/`Pong` kullanın.

## Ayrıca Bakınız

<CardGroup cols={2}>
  <Card title="Jetstream v2 Genel Bakış" icon="bolt" href="/tr/data-streaming/jetstream-v2">
    v2'nin v1'e neler eklediği, akış modeli ve başlangıç.
  </Card>

  <Card title="Jetstream (v1) Referansı" icon="book" href="/tr/data-streaming/jetstream-reference">
    v1 Protocol Buffer belirtimi.
  </Card>
</CardGroup>

## Destek

v2 protokolü veya uygulama ayrıntıları hakkındaki teknik sorularınız için lütfen
[Discord topluluğumuza](https://discord.gg/orbitflare) katılın.