Ethereum İşlem Hataları Açıklandı: Her Mesajın Anlamı ve Çözümü

1. Bu hata mesajları nereden geliyor?

Hemen her cüzdan, kütüphane ve RPC sağlayıcısı, en yaygın çalıştırılan Ethereum istemcisi olan go-ethereum tarafından üretilen hata metnini olduğu gibi iletir ve Layer 2 ağlarının istemcileri de aynı dizgileri yeniden kullanır. MetaMask bunları kendi iletişim kutusuna sarar, ethers.js NONCE_EXPIRED ya da REPLACEMENT_UNDERPRICED gibi bir kod ekler, bir RPC sağlayıcısı ise -32000 koduyla JSON-RPC hatası olarak döndürür. Altta yatan mesaj aynıdır.

Düğüm iki farklı kontrol kümesi çalıştırır. İlki işlemi aldığında yapılır: nonce doğru mu, ücret kabul edilebilir mi, gas limiti makul mu, gönderen ödeyebilir mi. Burada takılan bir işlem düşürülür ve zincire hiçbir şey kaydedilmez. İkincisi işlem bir bloğun içinde yürütülürken yapılır: sözleşme kodu gas limiti içinde, geri alınmadan tamamlanıyor mu. Burada başarısız olan bir işlem yine de kazılır, gezginde Fail durumuyla görünür ve ücret harcanmış olur.

Bir hatanın hangi aileye ait olduğunu bilmek iki şeyi birden söyler: para kaybedip kaybetmediğinizi ve çözümün sizin tarafınızda mı (işlem) yoksa sözleşmenin tarafında mı (girdiler) olduğunu.

2. Hızlı başvuru: yaygın hataların tamamı

Tam dizgiler, karşılaşma olasılığınıza göre sıralanmış. İfadeler go-ethereum kaynak kodundan alınmıştır; cüzdanlar bazen kısaltır.

3. "nonce too low" ne anlama gelir?

Her hesap işlemlerini sıfırdan başlayarak numaralandırır ve her numara bir kez kullanılabilir. "Nonce too low", az önce gönderdiğiniz işlemin, ağın o hesap için zaten onayladığı bir numarayı taşıdığı anlamına gelir. Düğüm işleminizdeki nonce'u hesabın beklenen sıradaki nonce'uyla karşılaştırır ve onun altındaki her şeyi reddeder.

Cüzdanın sıradaki nonce hakkındaki bilgisi bayatladığında olur: aynı hesaptan başka bir cüzdanda ya da cihazda işlem gönderilmiştir, bir hızlandırma ya da iptal numarayı çoktan almıştır ya da yerel bir geliştirme zinciri yeniden başlatıldığı için hesabın sayacı sıfıra dönmüş, MetaMask ise saymaya devam etmiştir. Donanım cüzdanında bir işlem iki kez imzalandığında da ortaya çıkar.

Çözüm, cüzdanın yeniden eşitlenmesine izin vermektir. Önce adrese gezginde bakın: yapmaya çalıştığınız şey o nonce ile zaten geçtiyse yeniden göndermeyin. Cüzdan bayat bir numara önermeye devam ediyorsa MetaMask'in "Delete activity and nonce data" (etkinlik ve nonce verilerini sil) seçeneği (Ayarlar, Geliştirici araçları) mevcut ağ için yerel sayacı temizler. MetaMask bunun geri alınamaz olduğunu, yalnızca mevcut ağı etkilediğini ve bakiyenize dokunmadığını belirtir. Kodda ise kendi sayacınızı tutmak yerine imzalamadan önce sıradaki nonce'u eth_getTransactionCount ile "pending" etiketini kullanarak okuyun.

4. "nonce too high" ne anlama gelir?

Ters yöndeki boşluk. İşlemin nonce'u hesabın beklenen sıradaki değerinin üstündedir, dolayısıyla arada bir delik vardır: daha düşük bir numara henüz onaylanmamıştır. Düğümler böyle bir işlemi yürütmek yerine kuyrukta tutar; bazıları ise bu mesajla doğrudan reddeder.

Tipik neden: öncekilerden birinin düşürüldüğü bir işlem serisi ya da ters yönde bir yerel zincir sıfırlaması (zincir sıfırlanmış ama cüzdan sıfırlanmamıştır, dolayısıyla cüzdan nonce 0 bekleyen bir zincire nonce 40 gönderir). Boşluğu eksik nonce'u göndererek doldurun ya da cüzdanın etkinlik verilerini yukarıdaki gibi temizleyin.

5. "replacement transaction underpriced" ne anlama gelir?

Bekleyen bir işlemi değiştirmeye çalıştınız (hızlandırma, iptal ya da aynı nonce ile yeniden gönderme) ve yenisi eskisinden yeterince fazla ödemiyor. Düğüm bekleyen bir işlemi aynı nonce'lu bir başkasıyla ancak ücret asgari bir yüzde kadar artarsa değiştirir; go-ethereum'da bu fiyat artışı varsayılan olarak yüzde 10'dur ve hem maksimum ücrete hem öncelik ücretine uygulanır.

Nonce doğrudur; sorun fiyattadır. İki ücret alanını da mevcut ağ fiyatının değil, bekleyen işlemin en az yüzde 10 üstüne çıkarın. MetaMask'in ilgili "transaction underpriced" iletişim kutusu için kendi önerisi, en az yüzde 10 daha yüksek bir öncelik ücreti ve en az yüzde 30 daha yüksek bir maksimum ücrettir. Hızlandırmak yerine iptal etmek için, MetaMask'in hata rehberinde anlatıldığı gibi aynı nonce ve artırılmış ücretle kendi adresinize 0 ETH gönderin. Her iki durumda da yerine geçen işlem yeni bir işlem hash'i alır ve eskisi düşürülür.

6. "transaction underpriced" ne anlama gelir?

"Replacement" sözcüğü olmadan bu düz bir fiyat kontrolüdür: işleminizin ücreti, düğümün havuzunda tutmaya razı olduğu seviyenin altındadır. Düğümler spam'i dışarıda tutmak için asgari bir gas fiyatı belirler ve yoğun bir dönemde cüzdanın "düşük" ücret tahmini bunun altına düşebilir. Kardeş mesaj "transaction gas price below minimum" aynı anlama gelir.

Maksimum ücreti ve öncelik ücretini yükseltip yeniden gönderin. Zincire hiçbir şey kaydedilmedi, dolayısıyla temizlenecek takılı bir işlem yok. Bunu tek bir ağda tekrar tekrar görüyorsanız o ağın asgarisi cüzdanınızın varsayılanından yüksektir; gas takipçisinin ağ sayfaları güncel fiyatı gösterir.

7. "insufficient funds for gas * price + value" ne anlama gelir?

Gönderenin yerel coin bakiyesi, gönderilen tutar artı en kötü durum ücretini, yani gas limiti çarpı gas başına maksimum ücreti karşılamak zorundadır. Bu kural EIP-1559 standardında yazılıdır: imzalayan, değerin üstüne gas_limit çarpı max_fee_per_gas tutarını karşılayabilmelidir. Düğüm bunu işlemin gerçekte tutacağı miktara göre değil, azami değere göre kontrol eder; dolayısıyla nihai ücret sığacak olsa bile bir işlem bu kontrolden geçemeyebilir.

Üç neden hemen her durumu açıklar. Token'ınız var ama yerel coin'iniz yok: Base'de USDC için gas olarak ETH, Polygon'da USDT için POL, BNB Smart Chain'de her şey için BNB gerekir. Bakiyenizin tamamını gönderiyorsunuz ve ücrete hiçbir şey bırakmadınız: önce azami ücreti düşün. Ya da gas limiti bir sözleşme çağrısı yüzünden şişmiştir ve en kötü durum gerçek maliyetin çok üstündedir.

Çözüm: yerel coin yükleyin, daha küçük bir tutar gönderin ya da şişirilmişlerse maksimum ücreti veya gas limitini düşürün. İlgili "insufficient funds for transfer" mesajı, gas hesaba katılmadan önce değerin tek başına bakiyeyi aştığı anlamına gelir.

8. Intrinsic gas too low, out of gas ve gas limiti hataları

Dört mesaj gas limitiyle ilgilidir ve farklı anlarda başarısız olurlar. "Intrinsic gas too low" dahil edilme öncesi bir rettir: her işlemin herhangi bir kod çalışmadan önce sabit bir taban maliyeti vardır, düz bir transfer için 21.000 gas artı veri baytı başına bir ücret, ve gas limitiniz bunun altındadır. ethereum.org gas dokümantasyonu standart transferi 21.000 birim olarak verir; bir token transferi ya da sözleşme çağrısı daha fazlasına ihtiyaç duyar. Limiti yükseltin ya da cüzdanın veya kütüphanenin tahmin etmesine izin verin.

"Out of gas" bunun dahil edilme sonrası sürümüdür. Limit taban maliyeti karşılamış, işlem kazılmış ve sözleşme kodu sonra limitin izin verdiğinden fazlasına ihtiyaç duymuştur. EVM her durum değişikliğini geri alır ama, aynı dokümantasyonun dediği gibi, yapılan iş için sağlanan gas'ın tamamı yine de tüketilir. Ücret gitmiştir ve işlem gezginde başarısız görünür. Daha yüksek bir limitle yeniden gönderin; cüzdanların tahminin üstüne pay eklemesinin nedeni budur.

"Exceeds block gas limit", belirlediğiniz limitin o ağda bir bloğun tamamının alabileceğinden büyük olduğu anlamına gelir. "Transaction gas limit too high" daha yenidir: EIP-7825 ile birlikte tek bir işlem 16.777.216 gas'tan (2 üzeri 24) fazlasını isteyemez ve tavanın üstündeki bir işlem reddedilir. İkisi de limiti düşürerek çözülür; meşru bir işlemin bu sayılara yakın bir şeye asla ihtiyacı olmaz.

9. Maksimum ücret ve öncelik ücreti hataları

EIP-1559'dan beri bir işlem iki ücret alanı taşır: gas başına maksimum ücret (max fee per gas), yani birim başına ödeyeceğiniz en yüksek tutar, ve gas başına maksimum öncelik ücreti (max priority fee per gas), yani doğrulayıcıya giden bahşiş. Protokol bunlarla bloğun taban ücreti (base fee) arasında iki ilişkiyi zorunlu kılar ve her birinin kendi hatası vardır.

"Max fee per gas less than block base fee": maksimum ücretiniz mevcut taban ücretin altındadır, dolayısıyla işlem hiçbir bahşişle dahil edilemez. Bu, sakin bir dönemde imzalanıp taban ücret yükseldikten sonra yayınlanan işlemlerin ve sabit kodlanmış ücretle oluşturulan işlemlerin başına gelir. Maksimum ücreti yükseltin ya da bekleyin: taban ücret blok blok hareket eder ve tavanınızın altına düşerse işlem yeniden geçerli olur.

"Max priority fee per gas higher than max fee per gas": bahşiş toplam tavanı aşıyor; spesifikasyon bunu yasaklar, çünkü önce taban ücret doldurulur ve bahşiş ancak kalandan gelebilir. Öncelik ücretini maksimum ücrete eşit ya da onun altında ayarlayın. Doğru kurulmuş bir işlemde maksimum ücret kabaca taban ücretin iki katı artı bahşiştir; bu, işlem beklerken taban ücretin yükselmesine yer bırakır.

10. "execution reverted" ne anlama gelir?

Çağırdığınız sözleşme yürütmeyi bilerek durdurdu. Solidity'nin require, revert ve assert ifadelerinin hepsi bu mesajla biter; ardından çoğu zaman sözleşmenin kendi gerekçe dizgisi gelir: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" ve benzerleri. Gerekçe boşsa yalnızca "execution reverted" ya da ham hata verisini görürsünüz.

Çoğu zaman bunu göndermeden önce görürsünüz, çünkü cüzdan çağrıyı eth_estimateGas üzerinden çalıştırır ve simülasyon geri alınır; MetaMask de gas'ı tahmin edemediğini bildirir. Bu ucuz sürümdür: hiçbir şey gönderilmemiştir. Pahalı sürüm, simülasyondan geçen, kazılan ve arada durum değiştiği için zincirde geri alınan işlemdir (bir takas fiyatı kayma payınızın dışına çıkmıştır, son parçayı başkası almıştır, bir son tarih geçmiştir). Gezginde Fail olarak görünür ve ücret ödenir.

Çözüm asla daha yüksek bir gas limiti değildir. Gerekçe dizgisini okuyun, sonra girdileri değiştirin: önce token'ı onaylayın (approve), kayma payını genişletin ya da tutarı düşürün, sözleşmenin duraklatılmadığından emin olun ve sözleşmenin bulunduğu ağda olduğunuzu doğrulayın. Gezginin işlem sayfası kazılmış başarısızlıklar için geri alma gerekçesini gösterir; Etherscan rehberi nerede bulacağınızı gösterir.

11. Already known, invalid sender ve oversized data

"Already known" pratikte bir hata sayılmaz. Düğüm gönderdiğiniz işlemin aynısını zaten tutuyordur; genellikle bir kütüphane yayını yeniden denemiştir ya da iki cüzdan aynı imzalı baytları göndermiştir. İlk işlemin onaylanmasını bekleyin.

"Invalid sender", düğümün imzadan geçerli bir imzalayan çıkaramadığı anlamına gelir. EIP-155'ten beri zincir kimliği imzalanan verinin parçasıdır; dolayısıyla zincir 1 için imzalanıp zincir 137'ye gönderilen bir işlem anlamsız bir adrese çözülür ve reddedilir. İmzalama yapılandırmasındaki zincir kimliğini RPC uç noktasının bildirdiğiyle karşılaştırın; zincir kimliği listesi numaraları ve uyuşmazlık durumunu kapsar.

"Oversized data", işlemin bayt boyutunun düğümün havuzuna kabul ettiğinin üstünde olduğu anlamına gelir; bu yalnızca çok büyük sözleşme dağıtımlarında ya da calldata'da olur. Veriyi bölün ya da bir factory üzerinden dağıtın.

12. Başarısız bir işlem gas'a mal olur mu?

Nerede başarısız olduğuna bağlı. Bu rehberin ilk ailesindeki her şey (nonce, underpriced, insufficient funds, intrinsic gas, ücret tavanı, already known, invalid sender, oversized data) bir rettir: düğüm işlemi düşürmüştür ve hiçbir blok onu içermez, dolayısıyla ücret kesilmemiştir ve gezginde bulunacak bir şey yoktur. Yeniden göndermenin ek bir maliyeti yoktur.

"Out of gas" ile kazılmış bir "execution reverted" ikinci ailedir: işlem Fail durumuyla bir bloktadır, doğrulayıcı işi yapmıştır ve ücret tam olarak ödenir. ethereum.org dokümantasyonu, ücretin işlem başarılı da olsa başarısız da olsa ödendiğini açıkça belirtir. Taşımaya çalıştığınız ETH ya da token'lar oldukları yerde kalır; yalnızca ücret kaybedilir.

13. Bu hatalardan kodda nasıl kaçınılır

Dört alışkanlık bu listenin çoğunu bir gönderim servisinden siler: sayaç tutmak yerine bekleyen nonce'u düğümden okumak, ücret tahminlerini bulunduğunuz ağ için düğümden almak, imzalamadan önce gas'ı tahmin edip pay eklemek ve yayınlamadan önce bakiyeyi tutar artı en kötü durum ücretiyle karşılaştırmak. ChainGate SDK dördünü de transfer() içinde yapar ve kendinizin ele alması gereken tek durumu tipli bir hata olarak sunar:

import { ChainGate, importWallet, NotEnoughFundsError } from 'chaingate';

const cg = new ChainGate({ apiKey: process.env.CHAINGATE_API_KEY });
const wallet = importWallet({ phrase: process.env.MNEMONIC });
const eth = cg.connect(cg.networks.ethereum, wallet);

try {
  // Nonce, gas limit and EIP-1559 fees are read from the node for you
  const tx = await eth.transfer(cg.networks.ethereum.amount('0.05'), '0x...');
  tx.setFee(tx.recommendedFees().normal);

  if (!tx.enoughFunds()) {
    // amount + worst-case fee exceeds the balance: nothing is broadcast
    console.log('short by', tx.missingFunds());
    return;
  }

  const sent = await tx.signAndBroadcast();
  console.log(sent.transactionId);
} catch (err) {
  if (err instanceof NotEnoughFundsError) {
    console.error('Not enough ETH for amount + fee');
  }
  throw err;
}

Ethereum ve UTXO zincirleri için akışın tamamını JavaScript ile kripto gönderme rehberi gösterir; transfer dokümantasyonu ise ücret seviyelerini ve tam olarak ne kadar yerel coin eksik olduğunu söyleyen missingFunds alanını listeler.

14. Buradan nereye

Bu hataların çoğu ücretlerle ilgili, dolayısıyla okunacak sıradaki sayfa gas ücretlerinin ne olduğunu ve maksimum ücret, öncelik ücreti ile taban ücretin nasıl bir araya geldiğini anlatan rehber, ardından da her ağdaki güncel fiyatlar için gas takipçisi. Bir işlem gerçekten çıktıysa ve ona ne olduğunu öğrenmeniz gerekiyorsa işlem hash'i rehberi nasıl sorgulayacağınızı gösterir. Ethereum, EVM Layer 2'leri ve Bitcoin'de nonce'ları, ücretleri ve bakiye kontrollerini halleden bir TypeScript kütüphanesi için ise ChainGate bu sitenin arkasındaki SDK'dır.

Sıkça sorulan sorular