> ## 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.

# EVM SDK

> OrbitFlare'ın EVM zincirleri için Rust SDK: orbitflare-evm-sdk crate'i.

OrbitFlare'ın EVM zincirleri - Polygon, BNB Smart Chain ve Robinhood Chain - artı kendi tanımladığınız her EVM zinciri için tek bir Rust istemcisi. Baştan sona [alloy](https://github.com/alloy-rs/alloy) tipleri üzerine kuruludur (`Address`, `U256`, `B256`, `Filter`, `TransactionRequest`, tiplenmiş bloklar, işlemler, makbuzlar ve günlükler) ve OrbitFlare'ın kendi taşıma katmanıyla gelir: yedek uç nokta, geri çekilmeli yeniden deneme ve kendi kendini onaran WebSocket abonelikleri.

İstemciler zincir üzerinde geneldir (`RpcClient<C>`, `WsClient<C>`); aşağıdaki takma adlar kolaylık sağlayan kısaltmalardır. gRPC şu anda yalnızca Polygon içindir (Bor).

## Desteklenen zincirler

| Zincir           | Chain ID | Takma ad                                    |
| ---------------- | -------- | ------------------------------------------- |
| Polygon          | 137      | `PolygonRpcClient`, `PolygonWsClient`       |
| BNB Smart Chain  | 56       | `BnbRpcClient`, `BnbWsClient`               |
| Robinhood Chain  | 4663     | `RobinhoodRpcClient`, `RobinhoodWsClient`   |
| Kendi zinciriniz | herhangi | `impl Chain for C` olduğunda `RpcClient<C>` |

<Note>
  `orbitflare-robinhood-sdk`'ten mi geçiyorsunuz? Robinhood Chain artık burada `RobinhoodRpcClient` / `RobinhoodWsClient` ile kapsanıyor. RPC ve WebSocket yüzeyi aynıdır; bağımsız crate kullanımdan kaldırılmıştır.
</Note>

## Kurulum

```bash theme={null}
cargo add orbitflare-evm-sdk
```

Varsayılan olarak yalnızca RPC istemcisi etkindir. İhtiyacınız olanı etkinleştirin:

```bash theme={null}
cargo add orbitflare-evm-sdk --features ws
cargo add orbitflare-evm-sdk --features grpc
cargo add orbitflare-evm-sdk --features all
```

## RPC

<CodeGroup>
  ```rust Örnek theme={null}
  let client = PolygonRpcClient::builder()
      .url("https://ams.poly.rpc.orbitflare.com")
      .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
      .build()?;

  let block = client.get_block_number().await?;
  let gas_price = client.get_gas_price().await?;
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::{primitives::address, PolygonRpcClient, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = PolygonRpcClient::builder()
          .url("https://ams.poly.rpc.orbitflare.com")
          .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
          .build()?;

      let block = client.get_block_number().await?;
      let gas_price = client.get_gas_price().await?;

      let wallet = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
      let balance = client.get_balance(wallet).await?;

      println!("block {block}, gas {gas_price} wei, balance {balance} wei");
      Ok(())
  }
  ```
</CodeGroup>

Yerleşik varsayılan uç nokta yoktur: URL'yi `.url()` ile veya bir ortam değişkeni aracılığıyla ayarlayın (bkz. [Uç noktalar](#endpoints)) ve API anahtarını `.api_key()` ile veya `ORBITFLARE_LICENSE_KEY` ile ayarlayın.

### Builder yöntemleri

**`.url(url)`** - Birincil uç nokta. Çözümleme sırası: builder üzerindeki `.url()`, sonra `ORBITFLARE_RPC_URL` ortam değişkeni.

**`.urls(&[...])`** - Birincil ve tüm yedekleri tek çağrıda ayarlar. İlk eleman birincil, kalanlar yedeklerdir.

**`.fallback_url(url)` / `.fallback_urls(&[...])`** - Yedek uç noktalar ekler. Başarısız olan uç noktalar üstel bekleme süresiyle (10 sn, 20 sn, 40 sn, en çok 60 sn) karantinaya alınır ve süre dolduğunda otomatik olarak yeniden denenir; sağlıklı uç noktalar her zaman tercih edilir.

**`.api_key(key)`** - OrbitFlare lisans anahtarınız. Ayarlanmazsa SDK `ORBITFLARE_LICENSE_KEY`'i kontrol eder. Anahtar istek zamanında uç nokta URL'sine `?api_key=<key>` olarak eklenir.

**`.block_tag(tag)`** - Durum sorgularının (`get_balance`, `call`, `get_code`, ...) kullandığı varsayılan blok etiketi. Varsayılan: `Latest`.

**`.retry(policy)`** - Geçici hatalarda (5xx, 429, bağlantı kopmaları, JSON-RPC hata kodu -32005) sonraki uç noktaya geçmeden önce üstel geri çekilmeli yeniden denemeyi denetler.

**`.timeout(duration)`** - Her tekil istek için HTTP zaman aşımı.

### Kullanılabilir yöntemler

| Yöntem                                                       | Döndürdüğü                                              |
| ------------------------------------------------------------ | ------------------------------------------------------- |
| `get_block_number()`                                         | `u64`                                                   |
| `get_chain_id()`                                             | `u64`                                                   |
| `get_balance(Address)`                                       | `U256` wei                                              |
| `get_transaction_count(Address)`                             | `u64` nonce                                             |
| `get_gas_price()`                                            | `u128` wei                                              |
| `max_priority_fee_per_gas()`                                 | `u128` wei                                              |
| `get_block_by_number(impl Into<BlockNumberOrTag>, full_txs)` | `Option<Block>`                                         |
| `get_block_by_hash(B256, full_txs)`                          | `Option<Block>`                                         |
| `get_transaction_by_hash(B256)`                              | `Option<Transaction>`                                   |
| `get_transaction_receipt(B256)`                              | `Option<TransactionReceipt>`                            |
| `get_logs(&Filter)`                                          | `Vec<Log>`                                              |
| `get_code(Address)`                                          | `Bytes`                                                 |
| `get_storage_at(Address, B256)`                              | `B256`                                                  |
| `call(&TransactionRequest)`                                  | `Bytes`                                                 |
| `estimate_gas(&TransactionRequest)`                          | `u64`                                                   |
| `send_raw_transaction(&[u8])`                                | `B256` işlem hash'i                                     |
| `fee_history(blocks, newest, percentiles)`                   | `FeeHistory`                                            |
| `request(method, params)`                                    | Ada göre herhangi bir RPC yöntemi (`serde_json::Value`) |
| `request_raw(body)`                                          | Ham JSON-RPC gövde dizgesi                              |

### Günlük filtreleri

`get_logs`, alloy'un `Filter` tipini doğrudan alır:

<CodeGroup>
  ```rust Örnek theme={null}
  let filter = Filter::new()
      .from_block(60_000_000u64)
      .to_block(BlockNumberOrTag::Latest)
      .address(address!("0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270"))
      .event_signature(transfer_topic);

  let logs = client.get_logs(&filter).await?;
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::{primitives::{address, b256}, BlockNumberOrTag, Filter, PolygonRpcClient, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = PolygonRpcClient::builder()
          .url("https://ams.poly.rpc.orbitflare.com")
          .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
          .build()?;

      let transfer_topic =
          b256!("ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef");

      let filter = Filter::new()
          .from_block(60_000_000u64)
          .to_block(BlockNumberOrTag::Latest)
          .address(address!("0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270"))
          .event_signature(transfer_topic);

      let logs = client.get_logs(&filter).await?;
      println!("{} logs", logs.len());
      Ok(())
  }
  ```
</CodeGroup>

### Kontrat çağrıları ve işlemler

`call` ve `estimate_gas`, alloy'un `TransactionRequest` tipini alır. İşlem göndermek için işlemi alloy ile (`alloy-signer`, `alloy-network`) oluşturup imzalayın, ardından SDK üzerinden yayınlayın:

```rust theme={null}
let hash = client.send_raw_transaction(&signed_tx_rlp).await?;
let receipt = client.get_transaction_receipt(hash).await?;
```

### Rastgele yöntemler

`request`, herhangi bir RPC yöntemini ada göre çağırır - SDK JSON-RPC zarfını oluşturur, yeniden deneme ve yedek uç noktayı yönetir ve `result` alanını döndürür. `request_raw` ham JSON-RPC gövde dizgesi gönderir.

```rust theme={null}
use serde_json::json;

let syncing = client.request("eth_syncing", json!([])).await?;
```

## WebSocket

`ws` özelliğini etkinleştirin. `.build()` asenkrondur - döndürmeden önce bağlantıyı kurar.

<CodeGroup>
  ```rust Örnek theme={null}
  let client = PolygonWsClient::builder()
      .url("wss://ams.poly.rpc.orbitflare.com")
      .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
      .build()
      .await?;

  let mut heads = client.new_heads_subscribe().await?;
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::{PolygonWsClient, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = PolygonWsClient::builder()
          .url("wss://ams.poly.rpc.orbitflare.com")
          .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
          .build()
          .await?;

      let mut heads = client.new_heads_subscribe().await?;

      while let Some(head) = heads.next().await {
          println!("block {} (gas used {})", head.number, head.gas_used);
      }
      Ok(())
  }
  ```
</CodeGroup>

Builder; `.urls()`, `.fallback_url(s)`, `.api_key()` ve `.retry()` yöntemlerini RPC builder ile paylaşır; WebSocket'e özgü seçenekler `.ping_interval_secs(n)` (varsayılan 10) ve `.max_missed_pongs(n)` (varsayılan 3) yöntemleridir.

### Abonelikler

Abonelikler tiplenmiştir - her biri ham JSON yerine karşılık gelen alloy tipini üretir:

| Yöntem                                 | Ürettiği                    |
| -------------------------------------- | --------------------------- |
| `new_heads_subscribe()`                | Her yeni blok için `Header` |
| `logs_subscribe(&Filter)`              | Filtreyle eşleşen `Log`     |
| `new_pending_transactions_subscribe()` | `B256` işlem hash'i         |

Tüm abonelikler bir `WsSubscription<T>` döndürür. Sonraki tiplenmiş olay için `.next()` çağırın (`None`, aboneliğin kapatıldığı anlamına gelir); tiplenmemiş `serde_json::Value` yükü için `.next_raw()` kullanın. `sub.unsubscribe().await` bir aboneliği açıkça kaldırır; aboneliği düşürmek de işe yarar.

### Yeniden bağlanma

Bağlantı koparsa arka plan görevi üstel geri çekilme ile yeniden bağlanır ve tüm etkin abonelikleri otomatik olarak yeniden abone eder. `.next()` çağrılarınız çalışmaya devam eder. Ölü bağlantılar etkin ping/pong ile tespit edilir.

## Polygon gRPC

Polygon, düşük yüklü blok, başlık ve makbuz erişimi için bir Bor gRPC arayüzü sunar. `grpc` özelliğini etkinleştirin. gRPC, düz metin HTTP/2 üzerinden çalışır; `.api_key()` aracılığıyla bir token ile kimlik doğrulaması yapın (`x-token` olarak gönderilir) veya IP beyaz listesi kullanın.

<CodeGroup>
  ```rust Örnek theme={null}
  let client = PolygonGrpcClient::builder()
      .url("http://your-bor-grpc-endpoint:3131")
      .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
      .build()?;

  let header = client.header_by_number(BlockNumber::Latest).await?;
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::grpc::{BlockNumber, PolygonGrpcClient};
  use orbitflare_evm_sdk::Result;

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = PolygonGrpcClient::builder()
          .url("http://your-bor-grpc-endpoint:3131")
          .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
          .build()?;

      let header = client.header_by_number(BlockNumber::Latest).await?;
      let author = client.author(header.number).await?;

      println!("block {} authored by {author}", header.number);
      Ok(())
  }
  ```
</CodeGroup>

| Yöntem                                     | Döndürdüğü          |
| ------------------------------------------ | ------------------- |
| `header_by_number(impl Into<BlockNumber>)` | `Header`            |
| `block_by_number(impl Into<BlockNumber>)`  | `Block`             |
| `transaction_receipt(B256)`                | `Receipt`           |
| `bor_block_receipt(B256)`                  | `Receipt`           |
| `author(impl Into<BlockNumber>)`           | `Address`           |
| `td_by_hash(B256)` / `td_by_number(...)`   | `u64` toplam zorluk |
| `root_hash(start, end)`                    | `String`            |
| `block_info_in_batch(start, end)`          | `Vec<BlockInfo>`    |

H160/H256 değerleri `ToAlloy` trait'i ile alloy `Address`/`B256` tiplerine dönüşür.

## Özel zincirler

Her EVM zinciri çalışır: bir işaretçi tip için `Chain`'i uygulayın ve genel bir `RpcClient<C>`'yi onun URL'sine yönlendirin. `CHAIN_ID` meta veridir (`RpcClient::<C>::chain_id_const()` olarak erişilebilir); istekleri kısıtlamaz.

<CodeGroup>
  ```rust Örnek theme={null}
  struct Base;

  impl Chain for Base {
      const CHAIN_ID: u64 = 8453;
  }

  let client = RpcClient::<Base>::builder()
      .url("https://mainnet.base.org")
      .build()?;
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::{Chain, RpcClient, Result};

  struct Base;

  impl Chain for Base {
      const CHAIN_ID: u64 = 8453;
  }

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = RpcClient::<Base>::builder()
          .url("https://mainnet.base.org")
          .build()?;

      println!("chain id: {}", client.get_chain_id().await?);
      println!("block:    {}", client.get_block_number().await?);
      Ok(())
  }
  ```
</CodeGroup>

## Arbitrum ve Nitro blok alanları

Robinhood Chain bir Arbitrum Nitro ağıdır, bu yüzden blokları standart EVM blok tiplerinin düşürdüğü ekstra alanlar (`l1BlockNumber`, `sendRoot`, `sendCount`) taşır. SDK bunları korur ve `NitroBlockExt` aracılığıyla tiplenmiş erişimciler sunar. Diğer standart dışı alanlar hâlâ `block.other` üzerinde kullanılabilir.

<CodeGroup>
  ```rust Örnek theme={null}
  let block = client
      .get_block_by_number(client.block_tag(), false)
      .await?
      .expect("block");

  let l1 = block.l1_block_number();
  let send_root = block.send_root();
  ```

  ```rust Tam Örnek theme={null}
  use orbitflare_evm_sdk::{NitroBlockExt, RobinhoodRpcClient, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
      let client = RobinhoodRpcClient::builder()
          .url("https://robinhood.rpc.orbitflare.com")
          .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
          .build()?;

      let block = client
          .get_block_by_number(client.block_tag(), false)
          .await?
          .expect("block");

      println!("l1 block:   {:?}", block.l1_block_number());
      println!("send root:  {:?}", block.send_root());
      println!("send count: {:?}", block.send_count());
      Ok(())
  }
  ```
</CodeGroup>

Arbitrum ön derlemelerine (ArbSys, ArbGasInfo, ...) diğer her kontrat gibi `call()` üzerinden erişilebilir.

## Uç noktalar

Varsayılan uç nokta yoktur. URL'yi her istemci için `.url()` ile veya bir ortam değişkeni aracılığıyla ayarlayın. Çözümleme sırası: builder üzerindeki `.url()`, sonra ortam değişkeni.

| Zincir          | RPC                                    | WebSocket                            |
| --------------- | -------------------------------------- | ------------------------------------ |
| Polygon         | `https://ams.poly.rpc.orbitflare.com`  | `wss://ams.poly.rpc.orbitflare.com`  |
| BNB Smart Chain | `https://bsc.rpc.orbitflare.com`       | `wss://bsc.rpc.orbitflare.com`       |
| Robinhood Chain | `https://robinhood.rpc.orbitflare.com` | `wss://robinhood.rpc.orbitflare.com` |

OrbitFlare panonuzdaki tam uç noktaları kullanın.

## Ortam değişkenleri

| Değişken                 | Kullanan             | Amaç                                                           |
| ------------------------ | -------------------- | -------------------------------------------------------------- |
| `ORBITFLARE_LICENSE_KEY` | RPC, WebSocket, gRPC | Uç nokta URL'lerine eklenen API anahtarı (gRPC için `x-token`) |
| `ORBITFLARE_RPC_URL`     | RPC                  | `.url()` çağrılmazsa kullanılan uç nokta                       |
| `ORBITFLARE_WS_URL`      | WebSocket            | `.url()` çağrılmazsa kullanılan uç nokta                       |
| `ORBITFLARE_GRPC_URL`    | gRPC                 | `.url()` çağrılmazsa kullanılan uç nokta                       |

## Kaynak

SDK açık kaynaktır: [github.com/orbitflare/orbitflare-evm-sdk-rs](https://github.com/orbitflare/orbitflare-evm-sdk-rs)