Menambahkan Penanda Tangan Baru ke Kora

Gambaran Umum Arsitektur

Kora menggunakan crate eksternal solana-keychain untuk semua operasi penandatanganan. Arsitektur ini menyediakan antarmuka penandatanganan terpadu untuk menandatangani transaksi Solana. Untuk menambahkan penanda tangan baru ke Kora, Anda perlu:

Pertama: Tambahkan implementasi penanda tangan Anda ke crate solana-keychain
Kedua: Tambahkan dukungan konfigurasi untuk penanda tangan Anda di Kora

Panduan Integrasi Langkah demi Langkah

Daftar Periksa Integrasi Cepat

Bagian 1: Tambahkan Penanda Tangan ke Crate solana-keychain

Implementasikan penanda tangan Anda dengan mengikuti panduan integrasi solana-keychain
Tunggu persetujuan PR dan publikasi crate

Bagian 2: Tambahkan Dukungan Konfigurasi Kora

Menambahkan Dukungan Signer di Kora

Pertama, pastikan signer Anda didukung dalam crate solana-keychain. Jika belum, ikuti panduan di: https://github.com/solana-foundation/solana-keychain/blob/main/docs/ADDING_SIGNERS.md

Langkah 1: Perbarui Cargo.toml

Perbarui dependensi Cargo.toml sehingga crate solana-keychain menggunakan versi terbaru (yang mencakup signer Anda):

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

Langkah 2: Definisikan Struct Konfigurasi Anda

Di crates/lib/src/signer/config.rs, tambahkan struct konfigurasi baru untuk signer Anda yang mendefinisikan variabel lingkungan mana yang diperlukan. Misalnya:

/// 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,
}

Langkah 2: Tambahkan Signer Anda ke Enum `SignerTypeConfig`

Tambahkan varian signer Anda ke enum SignerTypeConfig di crates/lib/src/signer/config.rs:

/// 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,
    },
}

Langkah 3: Tambahkan Logika Build

Di file yang sama (config.rs), tambahkan metode untuk membangun signer Anda dari konfigurasi dalam implementasi SignerConfig:

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)
                ))
            })
    }
}

Catatan: Nama metode Signer::from_your_service() harus sesuai dengan yang Anda implementasikan dalam crate solana-keychain.

Langkah 4: Tambahkan Logika Validasi

Tambahkan validasi untuk konfigurasi signer Anda dalam metode validate_individual_signer_config:

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(())
    }
}

Langkah 5: Ekspor Konfigurasi Anda

Tambahkan struct konfigurasi baru Anda ke ekspor modul di crates/lib/src/signer/mod.rs (atau di bagian atas file jika bersifat publik):

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

Menguji Integrasi Anda

Tambahkan Test Mock Builder

Untuk mempermudah pengujian, tambahkan metode builder ke SignerPoolConfigBuilder di crates/lib/src/tests/config_mock.rs:

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
    }
}

Ini memungkinkan pengujian lain untuk dengan mudah membuat konfigurasi mock yang menyertakan penanda tangan Anda:

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();

Variabel Lingkungan

Tambahkan contoh variabel lingkungan ke file-file berikut:

.env.example (root proyek)
.env (root proyek, untuk pengujian lokal)
./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

Pengujian Integrasi

Setiap fase integrasi adalah target [[test]] tersendiri di tests/Cargo.toml. Setiap target menjalankan surfnet tertanam beserta node Kora melalui harness_context, dengan data awal dibuat dari nol. Kora menyimpan konfigurasi dalam status global proses, sehingga penanda tangan baru membutuhkan target baru, bukan modul baru di dalam target yang sudah ada.

1. Tambahkan Fixture Penanda Tangan

Buat konfigurasi penanda tangan di tests/src/common/fixtures/:

# 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. Tambahkan Target Pengujian

Daftarkan fase tersebut di tests/Cargo.toml:

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

Kemudian buat tests/your_service/main.rs. File ini mengarahkan harness ke fixture Anda dan harus memuat setidaknya satu #[tokio::test] yang menguji penanda tangan:

#[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());
}

Tambahkan juga pengujian signTransaction agar jalur penandatanganan milik penanda tangan ikut dijalankan, bukan hanya pencarian kunci. tests/multi_signer/ adalah contoh lengkap yang dapat Anda salin.

3. Menjalankan Pengujian

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

Persyaratan Dokumentasi

Saat mengirimkan PR Anda, sertakan:

1. Perbarui Panduan Penanda Tangan

Tambahkan dokumentasi penanda tangan mengikuti panduan ADDING_SIGNERS.md, jelaskan prasyarat, pengaturan, dan penggunaan.

## 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 \```

Untuk implementasi penanda tangan: Buka isu di repositori solana-keychain
Untuk integrasi Kora: Buka isu di repositori Kora untuk diskusi desain
Bergabunglah dengan saluran komunitas kami
Tinjau konfigurasi penanda tangan yang ada di crates/lib/src/signer/config.rs

Contoh Struktur PR

Untuk repositori Kora:

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

Selamat datang di ekosistem Kora! Kami sangat antusias menyambut solusi manajemen kunci Anda sebagai bagian dari platform ini.