Kora'ya Yeni İmzalayıcılar Ekleme

Mimari Genel Bakış

Kora, tüm imzalama işlemleri için harici solana-keychain crate'ini kullanır. Bu mimari, Solana işlemlerini imzalamak için birleşik bir imzalama arayüzü sağlar. Kora'ya yeni bir imzalayıcı eklemek için şunları yapmanız gerekecek:

İlk olarak: İmzalayıcı uygulamanızı solana-keychain crate'ine ekleyin
İkinci olarak: Kora'da imzalayıcınız için yapılandırma desteği ekleyin

Adım Adım Entegrasyon Kılavuzu

Hızlı Entegrasyon Kontrol Listesi

Bölüm 1: solana-keychain Crate'ine İmzalayıcı Ekleme

İmzalayıcınızı solana-keychain entegrasyon kılavuzunu takip ederek uygulayın
PR onayı ve crate yayınını bekleyin

Bölüm 2: Kora Yapılandırma Desteği Ekleme

Kora'da İmzalayıcı Desteği Ekleme

Öncelikle, imzalayıcınızın solana-keychain crate'inde desteklendiğinden emin olun. Desteklenmiyorsa, aşağıdaki kılavuzu takip edin: https://github.com/solana-foundation/solana-keychain/blob/main/docs/ADDING_SIGNERS.md

Adım 1: Cargo.toml Dosyasını Güncelleyin

solana-keychain crate'inin en son sürümü (imzalayıcınızı içeren) kullanması için Cargo.toml bağımlılığını güncelleyin:

[dependencies]
solana-keychain = { version = "X.Y.Z", default-features = false, features = [
    "all",
    "sdk-v3",
] }

Adım 2: Yapılandırma Yapınızı Tanımlayın

crates/lib/src/signer/config.rs dosyasında, hangi ortam değişkenlerinin gerekli olduğunu tanımlayan imzalayıcınız için yeni bir yapılandırma yapısı ekleyin. Örneğin:

/// YourService signer configuration
#[derive(Clone, Serialize, Deserialize)]
pub struct YourServiceSignerConfig {
    pub api_key_env: String,
    pub api_secret_env: String,
    pub wallet_id_env: String,
}

Adım 2: İmzalayıcınızı `SignerTypeConfig` Enum'una Ekleyin

crates/lib/src/signer/config.rs dosyasındaki SignerTypeConfig enum'una imzalayıcı varyantınızı ekleyin:

/// Signer type-specific configuration
#[derive(Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum SignerTypeConfig {
    // Existing signer variants
    Memory { #[serde(flatten)] config: MemorySignerConfig },
    // ... existing variants ...

    // Add your signer here
    YourService {
        #[serde(flatten)]
        config: YourServiceSignerConfig,
    },
}

Adım 3: Yapılandırma Mantığını Ekleyin

Aynı dosyada (config.rs), SignerConfig implementasyonunda yapılandırmadan imzalayıcınızı oluşturmak için bir metod ekleyin:

impl SignerConfig {
    pub async fn build_signer_from_config(config: &SignerConfig) -> Result<Signer, KoraError> {
        match &config.config {
            // ... existing cases

            SignerTypeConfig::YourService { config: your_service_config } => {
                Self::build_your_service_signer(your_service_config, &config.name).await
            }
        }
    }

    // Add this new method
    async fn build_your_service_signer(
        config: &YourServiceSignerConfig,
        signer_name: &str,
    ) -> Result<Signer, KoraError> {
        // Update the environment variable names to match your signer's configuration
        let api_key = get_env_var_for_signer(&config.api_key_env, signer_name)?;
        let api_secret = get_env_var_for_signer(&config.api_secret_env, signer_name)?;
        let wallet_id = get_env_var_for_signer(&config.wallet_id_env, signer_name)?;

        // Call the constructor from solana-keychain crate
        Signer::from_your_service(api_key, api_secret, wallet_id)
            .await
            .map_err(|e| {
                KoraError::SigningError(format!(
                    "Failed to create YourService signer '{signer_name}': {}",
                    sanitize_error!(e)
                ))
            })
    }
}

Not: Signer::from_your_service() metod adı, solana-keychain crate'inde uyguladığınız adla eşleşmelidir.

Adım 4: Doğrulama Mantığını Ekleyin

validate_individual_signer_config metodunda imzalayıcınızın yapılandırması için doğrulama ekleyin:

impl SignerConfig {
    pub fn validate_individual_signer_config(&self, index: usize) -> Result<(), KoraError> {
        // ... existing validation

        match &self.config {
            // ... existing cases

            SignerTypeConfig::YourService { config } => {
                Self::validate_your_service_config(config, &self.name)
            }
        }
    }

    // Add this new validation method
    fn validate_your_service_config(
        config: &YourServiceSignerConfig,
        signer_name: &str,
    ) -> Result<(), KoraError> {
        // Update the environment variable names to match your signer's configuration
        let env_vars = [
            ("api_key_env", &config.api_key_env),
            ("api_secret_env", &config.api_secret_env),
            ("wallet_id_env", &config.wallet_id_env),
        ];

        for (field_name, env_var) in env_vars {
            if env_var.is_empty() {
                return Err(KoraError::ValidationError(format!(
                    "YourService signer '{signer_name}' must specify non-empty {field_name}"
                )));
            }
        }
        Ok(())
    }
}

Adım 5: Yapılandırmanızı Dışa Aktarın

crates/lib/src/signer/mod.rs dosyasındaki modül dışa aktarımlarına (veya dosyanın üst kısmında public ise) yeni yapılandırma yapınızı ekleyin:

pub use config::{
    MemorySignerConfig,
    PrivySignerConfig,
    SignerTypeConfig,
    TurnkeySignerConfig,
    VaultSignerConfig,
    YourServiceSignerConfig,  // Add this
    // ... other exports
};

Entegrasyonunuzu Test Etme

Test Mock Builder'ı Ekleyin

Test etmeyi kolaylaştırmak için crates/lib/src/tests/config_mock.rs dosyasında SignerPoolConfigBuilder'e bir builder metodu ekleyin:

impl SignerPoolConfigBuilder {
    // ... existing methods

    pub fn with_your_service_signer(
        mut self,
        name: String,
        api_key_env: String,
        api_secret_env: String,
        wallet_id_env: String,
        weight: Option<u32>,
    ) -> Self {
        let signer = SignerConfig {
            name,
            weight,
            config: SignerTypeConfig::YourService {
                config: YourServiceSignerConfig {
                    api_key_env,
                    api_secret_env,
                    wallet_id_env,
                },
            },
        };
        self.config.signers.push(signer);
        self
    }
}

Bu, diğer testlerin imzalayıcınızı içeren sahte yapılandırmaları kolayca oluşturmasını sağlar:

use crate::tests::config_mock::SignerPoolConfigBuilder;

let config = SignerPoolConfigBuilder::new()
    .with_your_service_signer(
        "yourservice_test".to_string(),
        "YOUR_SERVICE_API_KEY".to_string(),
        "YOUR_SERVICE_API_SECRET".to_string(),
        "YOUR_SERVICE_WALLET_ID".to_string(),
        Some(1)
    )
    .build();

Ortam Değişkenleri

Örnek ortam değişkenlerini aşağıdaki dosyalara ekleyin:

.env.example (projenin kök dizini)
.env (yerel test için projenin kök dizini)
./sdks/ts/.env.example
./sdks/ts/.env

# YourService Signer Configuration
YOUR_SERVICE_API_KEY=your_api_key_here
YOUR_SERVICE_API_SECRET=your_api_secret_here
YOUR_SERVICE_WALLET_ID=your_wallet_id_here

Entegrasyon Testleri

Her entegrasyon aşaması, tests/Cargo.toml içinde kendi [[test]] hedefine sahiptir. Her hedef, harness_context aracılığıyla gömülü bir surfnet ile bir Kora düğümünü sıfırdan hazırlanmış verilerle başlatır. Kora yapılandırmayı süreç genelindeki global durumda tuttuğundan, yeni bir imzalayıcı mevcut bir hedefe yeni modül eklemek yerine yeni bir hedef gerektirir.

1. İmzalayıcı Fixture'ı Ekleme

tests/src/common/fixtures/ içinde bir imzalayıcı yapılandırması oluşturun:

# tests/src/common/fixtures/signers-your-service.toml
[signer_pool]
strategy = "round_robin"

[[signers]]
name = "yourservice_main"
type = "your_service"
api_key_env = "YOUR_SERVICE_API_KEY"
api_secret_env = "YOUR_SERVICE_API_SECRET"
wallet_id_env = "YOUR_SERVICE_WALLET_ID"

2. Test Hedefi Ekleme

Aşamayı tests/Cargo.toml içine kaydedin:

[[test]]
name = "your_service"
path = "your_service/main.rs"

Ardından tests/your_service/main.rs dosyasını oluşturun. Bu dosya, harness'ı fixture'ınıza yönlendirir ve imzalayıcıyı çalıştıran en az bir #[tokio::test] içermelidir:

#[path = "../src/common/mod.rs"]
mod common;

use common::*;
use jsonrpsee::rpc_params;

pub async fn ctx() -> TestContext {
    harness_context(KoraSpec {
        config: "tests/src/common/fixtures/kora-test.toml",
        signers: "tests/src/common/fixtures/signers-your-service.toml",
        initialize_payments_atas: false,
    })
    .await
}

#[tokio::test]
async fn test_your_service_signs_as_fee_payer() {
    let ctx = ctx().await;

    let response: serde_json::Value = ctx
        .rpc_call("getPayerSigner", rpc_params![])
        .await
        .expect("Failed to get payer signer");

    response.assert_success();
    assert!(response["signer_address"].as_str().is_some());
}

Ayrıca bir signTransaction testi ekleyin; böylece yalnızca anahtar aramasının değil, imzalayıcının imzalama yolunun da çalışması sağlanır. tests/multi_signer/ kopyalayabileceğiniz eksiksiz bir örnektir.

3. Testleri Çalıştırma

just install

export YOUR_SERVICE_API_KEY="your_key"
export YOUR_SERVICE_API_SECRET="your_secret"
export YOUR_SERVICE_WALLET_ID="your_wallet"

# Run only your phase
cargo test -p tests --test your_service

# Run every integration phase
just integration-test

Dokümantasyon Gereksinimleri

PR'ınızı gönderirken şunları ekleyin:

1. İmzalayıcılar Kılavuzunu Güncelleme

Ön koşulları, kurulumu ve kullanımı açıklayan imzalayıcı dokümantasyonunu ADDING_SIGNERS.md kılavuzunu takip ederek ekleyin.

## YourService Signer

[YourService](https://yourservice.com) provides [brief description of your
service].

### Prerequisites

- YourService account
- API credentials
- Funded wallet

### Setup

1. Get your API credentials from [dashboard link]
2. Create a wallet...
3. Configure environment variables:

\```bash YOUR_SERVICE_API_KEY="your_api_key"
YOUR_SERVICE_API_SECRET="your_api_secret"
YOUR_SERVICE_WALLET_ID="your_wallet_id" \```

### Configure signers.toml

\```toml [signer_pool] strategy = "round_robin"

[[signers]] name = "yourservice_main" type = "your_service" api_key_env =
"YOUR_SERVICE_API_KEY" api_secret_env = "YOUR_SERVICE_API_SECRET" wallet_id_env
= "YOUR_SERVICE_WALLET_ID" weight = 1 \```

### Run Kora with YourService Signer

\```bash kora rpc start --signers-config signers.toml \```

İmzalayan uygulaması için: solana-keychain deposunda bir konu açın
Kora entegrasyonu için: Tasarım tartışmaları için Kora deposunda bir konu açın
Topluluk kanallarımıza katılın
crates/lib/src/signer/config.rs içindeki mevcut imzalayan yapılandırmalarını inceleyin

Örnek PR Yapısı

Kora deposu için:

feat(signer): add YourService signer configuration support

- Add YourServiceSignerConfig struct
- Add YourService variant to SignerTypeConfig enum
- Add build and validation logic for YourService
- Add example configuration files
- Add documentation to SIGNERS.md
- Add integration tests

Kora ekosistemine hoş geldiniz! Anahtar yönetim çözümünüzü platformun bir parçası olarak aramızda görmekten heyecan duyuyoruz.