pezkuwichain/pezkuwi-sdk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
9a52edf0dfbfa7bd9084433a6ae22e47dfd609aa
pezkuwi-sdk/CLAUDE.md
T

16 KiB
Raw Blame History

Claude Code Kuralları - Pezkuwi SDK

🚨 GITHUB ACTIONS KURALI - KESİNLİKLE UYULMALI

Workflow hata verdiğinde veya değişiklik yapılacağında:

  1. ÖNCE tüm mevcut workflow run'larını iptal et (gh run cancel)
  2. SONRA hepsini sil (gh run delete)
  3. EN SON tek bir commit/push ile temiz başlat

ASLA eski workflow'ların üzerine yeni workflow bırakma! ASLA kuyrukta onlarca workflow biriktirme!

# Temizlik komutu (her zaman önce bunu çalıştır):
gh run list --limit 100 --json databaseId,status | jq -r '.[] | select(.status == "queued" or .status == "in_progress" or .status == "pending") | .databaseId' | xargs -I{} gh run cancel {} 2>/dev/null
sleep 5
gh run list --limit 100 --json databaseId -q '.[].databaseId' | xargs -I{} gh run delete {} 2>/dev/null

⚠️ PEZKUWI SDK TERMİNOLOJİSİ - KRİTİK

ASLA POLKADOT SDK TERİMLERİ KULLANMA! Bu bağımsız bir blockchain projesi.

Doğru Terminoloji Tablosu:

YANLIŞ (Polkadot SDK) DOĞRU (Pezkuwi SDK)
parachain teyrchain
rococo pezkuwichain
westend zagros
kusama zagros
polkadot pezkuwichain
[[parachains]] [[teyrchains]]
[[parachains.collators]] [[teyrchains.collators]]
-lparachain=debug -lteyrchain=debug
parachain=debug teyrchain=debug

🔄 CRATE REBRAND KURALLARI (76 Crate)

Prefix Dönüşümleri:

Polkadot SDK Prefix Pezkuwi SDK Prefix Örnek
sp- pezsp- sp-core → pezsp-core
sc- pezsc- sc-client → pezsc-client
frame- pezframe- frame-support → pezframe-support
pezpallet- pezpallet- pezpallet-balances → pezpallet-balances
cumulus- pezcumulus- cumulus-client → pezcumulus-client
bridge-hub- pezbridge-hub- bridge-hub-runtime → pezbridge-hub-runtime
bridge-runtime- pezbridge-runtime- bridge-runtime-common → pezbridge-runtime-common
mmr- pezmmr- mmr-gadget → pezmmr-gadget
snowbridge- pezsnowbridge- snowbridge-core → pezsnowbridge-core

snowbridge-pezpallet- Dönüşümü:*

snowbridge-pezpallet-* → pezsnowbridge-pezpallet-*

Örnek: snowbridge-pezpallet-ethereum-client → pezsnowbridge-pezpallet-ethereum-client

Özel Dönüşümler:

Polkadot SDK Pezkuwi SDK
bp-runtime pezbp-runtime
bp-header-chain bp-header-pez-chain
asset-test-utils asset-test-pezutils
test-runtime-constants peztest-runtime-constants
xcm-docs xcm-pez-docs
xcm-emulator xcm-pez-emulator
xcm-procedural xcm-pez-procedural
xcm-runtime-apis xcm-runtime-pezapis
xcm-simulator xcm-pez-simulator

Genel pez- Prefix Eklenen Crate'ler:

Polkadot SDK Pezkuwi SDK
fork-tree pez-fork-tree
subkey pez-subkey
generate-bags pez-generate-bags
kitchensink-runtime pez-kitchensink-runtime
minimal-template-node pez-minimal-template-node
minimal-template-runtime pez-minimal-template-runtime
node-bench pez-node-bench
node-primitives pez-node-primitives
node-rpc pez-node-rpc
node-testing pez-node-testing
solochain-template-node pez-solochain-template-node
solochain-template-runtime pez-solochain-template-runtime
tracing-gum pez-tracing-gum
tracing-gum-proc-macro pez-tracing-gum-proc-macro
equivocation-detector pez-equivocation-detector
finality-relay pez-finality-relay
messages-relay pez-messages-relay
slot-range-helper pez-slot-range-helper
penpal-emulated-chain pez-penpal-emulated-chain
penpal-runtime pez-penpal-runtime

Dosya İsimlendirme Kuralı:

  • Cargo.toml name alanı rebrand edilmeli
  • Rust dosya isimleri mod bildirimleriyle eşleşmeli
  • Örnek: mod pezsnowbridge_pezpallet_system; → dosya pezsnowbridge_pezpallet_system.rs olmalı

Token'lar:

  • HEZ: Relay chain native token (200M genesis, inflationary)
  • PEZ: Asset Hub governance token (5B sabit supply)
  • TYR: Base unit (1 HEZ = 10^18 TYR)

System Teyrchains:

  • Asset Hub Teyrchain: ID 1000
  • People Chain Teyrchain: ID 1004

Zombienet Config Örneği (DOĞRU):

[relaychain]
default_args = ["-lteyrchain=debug"]
chain = "pezkuwichain-dev"

[[teyrchains]]
id = 1000
chain = "asset-hub-pezkuwichain-dev"

[[teyrchains.collators]]
args = ["-lteyrchain=debug"]

🎯 ANA HEDEF VE ÇALIŞMA PRENSİPLERİ

Hedef

Pezkuwi blockchain'i mainnet'e taşımak. Her test aşamasında (dev → local → alpha → beta → staging → mainnet) tüm bug/hataları kalıcı olarak çözmeden bir sonraki aşamaya GEÇİLMEZ.

Mevcut Aşama: DEV NETWORK

Başarı Kriterleri (hepsi sağlanmalı):

  • 3 runtime çalışmalı (Relay Chain, Asset Hub, People Chain)
  • Birbirini görmeli (peer discovery)
  • Bloklar üretilmeli
  • Finalized olmalı
  • Alice hesabında genesis token'ları görülmeli (HEZ, PEZ)

Test Aşamaları Sırası

  1. DEV (1 validator - Alice) ← ŞU AN BURADAYIZ
  2. LOCAL (2 validator - Alice + Bob)
  3. ALPHA (4 validator)
  4. BETA (8 validator)
  5. STAGING (21 validator)
  6. MAINNET (100 validator)

Çalışma Prensibi

Her aşamada:
1. Planlanan testleri yap
2. Tüm testlerden başarılı sonuç al
3. Hata/bug varsa → düzelt → tekrar test et
4. Başarılı olunca → blockchain upgrade → sonraki aşama

ÖNEMLİ: Ekranda geçici başarı görmek yeterli DEĞİL. Kalıcı çözümler, tam testler, sonra ilerleme.

Dizin Kuralları

Dizin Kullanım
/home/mamostehp/Pezkuwi-SDK Tüm işlemler burada yapılır (edit, commit, push)

Ekran Görüntüleri

Kullanıcı "ekran" veya "ekrana bak" dediğinde:

/home/mamostehp/DKSweb_ekran/Screenshot.png

dosyasını oku.

Gemini ile Koordinasyon

Gemini mesaj gönderdiğinde veya "gemini mesaj" denildiğinde:

/home/mamostehp/Pezkuwi-SDK/.ai-coordination/messages.md

dosyasını oku. Diğer koordinasyon dosyaları:

  • claude-status.md - Claude'un mevcut durumu
  • gemini-status.md - Gemini'nin mevcut durumu
  • task-board.md - Görev tablosu

Commit Kuralları

  • Commit mesajlarına 🤖 Generated with [Claude Code] ve Co-Authored-By: Claude EKLEME
  • Sadece düz commit mesajı yaz

Proje Bilgileri

  • Proje: Pezkuwi SDK - Bağımsız blockchain projesi
  • Teknoloji: Polkadot SDK fork'u (ama Polkadot DEĞİL, bağımsız)
  • Ana branch: main
  • GitHub: pezkuwichain/pezkuwi-sdk
  • Discord: https://discord.gg/Y3VyEC6h8W (Server: 1444335345935057049)

Önemli Notlar

  1. paritytech referansları pezkuwichain olmalı
  2. polkadot-sdk referansları pezkuwi-sdk olmalı
  3. Kaliteyi düşüren "kolay çözümler" yerine doğru çözümü uygula
  4. Geride iş bırakma - kapsamlı da olsa tamamla

🔗 UPSTREAM ISSUE TRACKING SİSTEMİ

Polkadot SDK'daki issue'ları Pezkuwi SDK'ya nasıl taşıyoruz:

Mantık

Upstream Polkadot SDK'de TODO/issue referansları varsa, bunları tracking issue sistemi ile takip ediyoruz.

Adımlar

1. Upstream'de Kontrol Et:

# Örnek: pezkuwichain/kurdistan-sdk/issues/133 için
grep -r "pezkuwichain/kurdistan-sdk/issues/133" /home/mamostehp/polkadot-sdk-check/

2. Tracking Issue Oluştur:

gh issue create --repo pezkuwichain/pezkuwi-sdk --label "upstream-tracking" \
  --title "[Upstream Tracking] paritytech/polkadot#2403" \
  --body "**Upstream:** https://github.com/pezkuwichain/kurdistan-sdk/issues/133

**Status Tracking:**
- [x] Pending - Upstream not yet resolved
- [ ] Resolved - Fix merged upstream
- [ ] Evaluated - Assessed if needed for PezkuwiChain
- [ ] Applied - Fix applied to our chain
- [ ] Closed - Upstream issue closed
- [ ] Skipped - Not relevant for us

**Last Check:** 2025-12-06
**Next Check:** 2026-01-06

**Notes:**
ValidatorIndex From<u32> trait implementation issue.
Periodically check upstream and update checkboxes above based on status changes."

3. Koddaki Linki Güncelle:

// ÖNCEKİ:
// https://github.com/pezkuwichain/kurdistan-sdk/issues/133

// SONRA (bizim tracking issue'ya işaret et):
// https://github.com/pezkuwichain/pezkuwi-sdk/issues/163

Örnek Tamamlanmış Tracking Issue'lar

Neden Böyle Yapıyoruz?

  1. Broken link olmasın: Upstream issue linklerini kendi repo'muza çeviriyoruz
  2. Takip: Upstream'de issue çözüldü mü, bizde uygulamamız gerekiyor mu takip ediyoruz
  3. Workflow: .github/workflows/upstream-issue-tracker.yml haftalık kontrol ediyor

✅ CI/CD QUICK-CHECKS DÜZELTMELERİ TAMAMLANDI

Son güncelleme: 2025-11-29

Tamamlanan İşler

  1. check-workspace.py düzeltmesi ✅

    • polkadot-sdk → pezkuwi-sdk değiştirildi
    • Umbrella crate için hem path hem workspace = true kabul ediliyor

  2. Bridge crate workspace inheritance (16 crate) ✅

    • Tüm bridge crate'leri workspace = true kullanıyor

  3. Markdown lint kuralları ✅

    • MD004 (ul-style): Devre dışı - çok fazla legacy dosya
    • MD013 (line-length): Devre dışı - URL'ler satırları uzatıyor

  4. TOML format (taplo) ✅

    • .config/taplo.toml path'leri polkadot → pezkuwi düzeltildi
    • 435+ TOML dosyası formatlandı

  5. Zepter check ✅

    • .config/zepter.yaml: -p=polkadot-sdk → -p=pezkuwi-sdk düzeltildi
    • Feature propagation: 36+ issue fix edildi
    • Duplicate deps: pezpallet-identity-kyc ve pezpallet-tiki düzeltildi

  6. Umbrella crate ✅

    • generate-umbrella.py çalıştırıldı
    • umbrella/Cargo.toml ve umbrella/src/lib.rs yeniden oluşturuldu

Değiştirilen Dosyalar (438 dosya)

  • Config dosyaları: .config/taplo.toml, .config/zepter.yaml, .github/.markdownlint.yaml
  • Script: .github/scripts/check-workspace.py
  • Pezpallet Cargo.toml: pezpallet-identity-kyc, pezpallet-tiki + 12 özel pezpallet feature propagation
  • Tüm Cargo.toml dosyaları (taplo format)
  • Umbrella crate dosyaları

Sonraki Adım

Commit atılıp push edilmeli - CI/CD artık geçmeli.

🧪 ZOMBIENET TEST ENVIRONMENT VARIABLES

Zombienet SDK test'leri için gerekli environment variable'lar:

Problem

zombienet_sdk::environment::get_images_from_env() fonksiyonu, test'lerde kullanılacak Docker image'larını environment variable'lardan alır. Pezkuwi SDK için bu variable'lar tanımlanmalı.

Çözüm

Lokal test için:

export ZOMBIENET_IMAGE_PEZKUWI="docker.io/pezkuwichain/pezkuwi:latest"
export ZOMBIENET_IMAGE_CUMULUS="docker.io/pezkuwichain/pezcumulus:latest"
cargo test --workspace --features runtime-benchmarks

CI/CD workflow'larına eklenecek:

Test yapan tüm workflow'lara (.github/workflows/tests*.yml) şu environment variable'lar eklenmelidir:

env:
  ZOMBIENET_IMAGE_PEZKUWI: "docker.io/pezkuwichain/pezkuwi:latest"
  ZOMBIENET_IMAGE_CUMULUS: "docker.io/pezkuwichain/pezcumulus:latest"

Not: Bu değişkenler compile-time'da image alanlarının doldurulması için gerekli. Gerçek image path'leri production'da güncellenebilir.

İlgili dosyalar:

  • bizinikiwi/client/transaction-pool/tests/zombienet/yap_test.rs:38
  • Tüm zombienet SDK test dosyaları

Tarih: 2025-12-09

🛑 SİSTEMATİK ÇALIŞMA KURALLARI - KRİTİK

Son güncelleme: 2025-12-13

Bu kurallar, tekrarlanan hatalardan öğrenilerek oluşturulmuştur. KESİNLİKLE uyulmalı.

1. ÇALIŞAN KODA DOKUNMA

"If it ain't broke, don't fix it"
  • Çalışan workflow'lara, test geçen dosyalara gereksiz değişiklik yapma
  • Bir şeyi "iyileştirmek" için çalışan kodu değiştirme
  • Düzeltme yaparken sadece hatalı olan yere odaklan

2. TEK DEĞİŞİKLİK → TEK TEST

Her seferinde SADECE BİR değişiklik yap
→ Test et
→ Sonucu gör
→ Sonra diğerine geç
  • Birden fazla değişikliği aynı anda yapmak = hangi değişikliğin hataya sebep olduğunu anlayamama
  • Bir commit'te birden fazla bağımsız fix varsa, sorun çıktığında rollback zor

3. LOKAL TEST ÖNCE

Mümkünse önce lokal test et, sonra push et
  • cargo check --workspace
  • cargo test -p <crate>
  • cargo clippy --workspace

GitHub'a push edip sonucu beklemek = zaman kaybı + gereksiz workflow kuyruğu

4. GERİ DÖNÜŞ NOKTASI BELİRLE

Her başarılı durumda commit at ve işaretle
  • "Bu çalışıyor" diye bilinen commit SHA'sını not al
  • Sorun çıkarsa o commit'e dön, karmaşık düzeltmeler deneme
  • Git history'si temiz tutulmalı

5. PANİK YAPMA

İlk hata geldiğinde:
1. DURMA
2. Hata mesajını OKU
3. Root cause analizi YAP
4. Sonra düzelt
  • Hızlıca "düzeltme" yapmaya çalışmak = durumu daha da kötüleştirmek
  • Bir düzeltme işe yaramazsa → geri al → farklı yaklaşım dene
  • Aynı şeyi tekrar tekrar deneme

6. ROLLBACK > DEBUG

Düzeltme 2-3 denemede işe yaramazsa → ROLLBACK
  • Çalışan versiyona geri dön
  • Temiz bir başlangıç noktasından tekrar başla
  • Sonsuz debug döngüsüne girme

Örnek Senaryo (YANLIŞ):

1. Clippy hatası var → düzelt
2. Düzeltme sırasında isdraft workflow'una dokundum (gereksiz)
3. isdraft patladı
4. isdraft'ı düzeltmeye çalıştım (5 farklı deneme)
5. Hepsi başarısız
6. Sonunda revert ettim
7. Zaman kaybı: 2 saat

Örnek Senaryo (DOĞRU):

1. Clippy hatası var → düzelt
2. Sadece clippy ile ilgili dosyalara dokun
3. Test et, push et
4. Başka bir şey patlarsa → o dosyalara bak
5. Çalışan koda dokunma

🔧 DEVAM EDEN GÖREV: pezpallet-revive-eth-rpc DERLEME

Son güncelleme: 2025-12-19 14:50 UTC

Mevcut Durum

pezpallet-revive-eth-rpc crate'i compile edilemiyor. İlerleme kaydedildi ama henüz tamamlanmadı.

TAMAMLANAN ADIMLAR ✅

  1. ✅ pez-revive-dev-node başarıyla derlendi
  2. ✅ Dev node çalıştırıldı
  3. ✅ Yeni metadata generate edildi (revive_chain.scale)
    • Artık sadece pezsp_runtime, pezpallet_revive path'leri var
    • sp_runtime, pallet_revive (upstream) yok
  4. ✅ no_default_substitutions eklendi (subxt_client.rs)

KALAN SORUNLAR

SORUN 1: subxt hala sp_runtime arıyor

no_default_substitutions eklense de subxt bazı type'lar için hala sp_runtime path'i kullanıyor:

error[E0433]: could not find `sp_runtime` in `runtime_types`

Olası çözüm: crate_path veya ek substitute_type direktifleri gerekebilir.

SORUN 2: H160, H256 type substitutions eksik

no_default_substitutions ile varsayılan type mapping'ler de kayboluyor:

error[E0277]: the trait bound `H160: From<[u8; 20]>` is not satisfied

Çözüm: Eksik type'lar için substitute_type ekle:

substitute_type(
    path = "primitive_types::H160",
    with = "::subxt::utils::Static<::pezsp_core::H160>"
),
substitute_type(
    path = "primitive_types::H256",
    with = "::subxt::utils::Static<::pezsp_core::H256>"
),

SORUN 3: SQLX Query Cache

error: `SQLX_OFFLINE=true` but there is no cached data for this query

Çözüm seçenekleri:

  1. cargo sqlx prepare ile cache regenerate (PostgreSQL/SQLite gerekli)
  2. query! → query_unchecked! ile compile-time check'i devre dışı bırak

SONRAKİ ADIMLAR

  1. H160, H256 ve diğer primitive_types için substitute_type ekle
  2. crate_path veya alternatif subxt yapılandırması araştır
  3. SQLX sorununu çöz (unchecked query veya cache regenerate)
  4. cargo check -p pezpallet-revive-eth-rpc başarılı olmalı
  5. cargo check --workspace başarılı olmalı

İlgili Dosyalar

  • bizinikiwi/pezframe/revive/rpc/src/subxt_client.rs - subxt macro
  • bizinikiwi/pezframe/revive/rpc/revive_chain.scale - YENİ metadata (tamamen rebranded)
  • bizinikiwi/pezframe/revive/rpc/.sqlx/ - SQLX query cache (güncellenmeli)
Reference in New Issue View Git Blame Copy Permalink