Προσθήκη Νέων Υπογραφόντων στο Kora

Επισκόπηση Αρχιτεκτονικής

Το Kora χρησιμοποιεί το εξωτερικό solana-keychain crate για όλες τις λειτουργίες υπογραφής. Αυτή η αρχιτεκτονική παρέχει μια ενοποιημένη διεπαφή υπογραφής για την υπογραφή συναλλαγών Solana. Για να προσθέσετε έναν νέο υπογράφοντα στο Kora, θα χρειαστεί να:

Πρώτα: Προσθέστε την υλοποίηση του υπογράφοντά σας στο solana-keychain crate
Δεύτερον: Προσθέστε υποστήριξη διαμόρφωσης για τον υπογράφοντά σας στο Kora

Οδηγός Ενσωμάτωσης Βήμα προς Βήμα

Γρήγορη Λίστα Ελέγχου Ενσωμάτωσης

Μέρος 1: Προσθήκη Υπογράφοντα στο solana-keychain Crate

Υλοποιήστε τον υπογράφοντά σας ακολουθώντας τον οδηγό ενσωμάτωσης solana-keychain
Περιμένετε την έγκριση του PR και τη δημοσίευση του crate

Μέρος 2: Προσθήκη Υποστήριξης Διαμόρφωσης Kora

Προσθήκη Υποστήριξης Υπογράφοντος στο Kora

Πρώτα, βεβαιωθείτε ότι ο υπογράφων σας υποστηρίζεται στο crate solana-keychain. Εάν δεν υποστηρίζεται, ακολουθήστε τον οδηγό στο: https://github.com/solana-foundation/solana-keychain/blob/main/docs/ADDING_SIGNERS.md

Βήμα 1: Ενημέρωση του Cargo.toml

Ενημερώστε την εξάρτηση του Cargo.toml ώστε το crate solana-keychain να χρησιμοποιεί την πιο πρόσφατη έκδοση (που περιλαμβάνει τον υπογράφοντά σας):

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

Βήμα 2: Ορισμός της Δομής Διαμόρφωσης

Στο crates/lib/src/signer/config.rs, προσθέστε μια νέα δομή διαμόρφωσης για τον υπογράφοντά σας που ορίζει ποιες μεταβλητές περιβάλλοντος χρειάζονται. Για παράδειγμα:

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

Βήμα 2: Προσθήκη του Υπογράφοντός σας στο Enum `SignerTypeConfig`

Προσθέστε την παραλλαγή του υπογράφοντός σας στο enum SignerTypeConfig στο 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,
    },
}

Βήμα 3: Προσθήκη Λογικής Κατασκευής

Στο ίδιο αρχείο (config.rs), προσθέστε μια μέθοδο για να δημιουργήσετε τον υπογράφοντά σας από τη διαμόρφωση στην υλοποίηση 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)
                ))
            })
    }
}

Σημείωση: Το όνομα της μεθόδου Signer::from_your_service() θα πρέπει να ταιριάζει με αυτό που υλοποιήσατε στο crate solana-keychain.

Βήμα 4: Προσθήκη Λογικής Επικύρωσης

Προσθέστε επικύρωση για τη διαμόρφωση του υπογράφοντός σας στη μέθοδο 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(())
    }
}

Βήμα 5: Εξαγωγή της Διαμόρφωσής σας

Προσθέστε τη νέα δομή διαμόρφωσής σας στις εξαγωγές του module στο crates/lib/src/signer/mod.rs (ή στην κορυφή του αρχείου εάν είναι δημόσια):

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

Δοκιμή της Ενσωμάτωσής σας

Προσθήκη Mock Builder Δοκιμών

Για να διευκολυνθεί η δοκιμή, προσθέστε μια μέθοδο builder στο SignerPoolConfigBuilder στο 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
    }
}

Αυτό επιτρέπει σε άλλες δοκιμές να δημιουργούν εύκολα εικονικές διαμορφώσεις που περιλαμβάνουν τον υπογράφοντά σας:

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

Μεταβλητές Περιβάλλοντος

Προσθέστε τις παραδειγματικές μεταβλητές περιβάλλοντος στα ακόλουθα αρχεία:

.env.example (ρίζα του έργου)
.env (ρίζα του έργου, για τοπική δοκιμή)
./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

Δοκιμές Ενσωμάτωσης

Το Kora χρησιμοποιεί ενοποιημένο εκτελεστή δοκιμών (tests/src/bin/test_runner.rs) που διαχειρίζεται όλες τις φάσεις δοκιμών ενσωμάτωσης συμπεριλαμβανομένων των δοκιμών TypeScript. Για να προσθέσετε δοκιμές για τον νέο υπογράφοντά σας:

1. Προσθήκη Διαμόρφωσης Δοκιμών

Δημιουργήστε ένα νέο αρχείο διαμόρφωσης υπογράφοντα στο 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. Προσθήκη Φάσης Δοκιμών στον Εκτελεστή Δοκιμών

Ενημερώστε το tests/src/test_runner/test_cases.toml ώστε να περιλαμβάνει μια φάση δοκιμών για τον υπογράφοντά σας:

[test.your_service]
name = "YourService Signer Tests"
config = "tests/src/common/fixtures/kora-test.toml"
signers = "tests/src/common/fixtures/signers-your-service.toml"
port = "8090"  # Use a unique port
tests = ["your_service"]

3. Εκτέλεση Δοκιμών

Βεβαιωθείτε ότι το περιβάλλον σας είναι ρυθμισμένο:

# Install binaries and dependencies
just install
just install-ts-sdk
just build-ts-sdk

# Set environment variables for your service
export YOUR_SERVICE_API_KEY="your_key"
export YOUR_SERVICE_API_SECRET="your_secret"
export YOUR_SERVICE_WALLET_ID="your_wallet"

Εκτελέστε τις δοκιμές χρησιμοποιώντας τον ενοποιημένο εκτελεστή δοκιμών:

# Run all integration tests (includes your new signer phase)
just test-integration

# Run tests with verbose output
just test-integration-verbose

# Run specific test phase with filter
cargo run -p tests --bin test_runner -- --phases your_service

Απαιτήσεις Τεκμηρίωσης

Κατά την υποβολή του PR σας, συμπεριλάβετε:

1. Ενημέρωση του Οδηγού Υπογραφόντων

Προσθέστε τεκμηρίωση υπογράφοντα ακολουθώντας τον οδηγό ADDING_SIGNERS.md, εξηγώντας τις προϋποθέσεις, τη ρύθμιση και τη χρήση.

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

```

```

`

### 2. Ενημέρωση README

Προσθέστε την υπηρεσία σας στη λίστα υπογραφέων του κύριου README.

## Λίστα Ελέγχου Υποβολής

- [ ] Η υπογραφή σας υποστηρίζεται στο crate `solana-keychain`
- [ ] Ενημερώθηκε η εξάρτηση `solana-keychain` στο Cargo.toml στην τελευταία
      έκδοση
- [ ] Προστέθηκε struct διαμόρφωσης για την υπογραφή σας
- [ ] Προστέθηκε παραλλαγή `SignerTypeConfig`
- [ ] Προστέθηκε λογική κατασκευής στο `build_signer_from_config`
- [ ] Προστέθηκε λογική επικύρωσης στο `validate_individual_signer_config`
- [ ] Εξήχθη το struct διαμόρφωσης στο `mod.rs`
- [ ] (Προαιρετικό) Προστέθηκε μέθοδος δημιουργίας mock δοκιμής στο
      `config_mock.rs`
- [ ] Ο κώδικας μεταγλωττίζεται χωρίς προειδοποιήσεις
- [ ] Όλες οι δοκιμές περνούν επιτυχώς (`make test` και `make test-integration`)
- [ ] Προστέθηκε τεκμηρίωση ακολουθώντας το
      [`ADDING_SIGNERS.md`](https://github.com/solana-foundation/solana-keychain/blob/main/docs/ADDING_SIGNERS.md)
- [ ] Δημιουργήθηκαν αρχεία παραδειγμάτων διαμόρφωσης (`.toml` και
      `.env.example`)
- [ ] Δεν υπάρχουν σταθερά κωδικοποιημένες τιμές ή μυστικά
- [ ] Τα μηνύματα σφάλματος είναι κατατοπιστικά
- [ ] Ακολουθούνται οι συμβάσεις ονοματοδοσίας της Rust (snake_case)
- [ ] Το linting περνάει επιτυχώς (`make lint`)
- [ ] Επικοινωνήστε με την ομάδα Kora με API Keys για δοκιμές ενσωμάτωσης

## Λήψη Βοήθειας

- **Για υλοποίηση υπογραφέα**: Ανοίξτε ένα ζήτημα στο αποθετήριο
  [`solana-keychain`](https://github.com/solana-foundation/solana-keychain)
- **Για ενσωμάτωση Kora**: Ανοίξτε ένα ζήτημα στο αποθετήριο Kora για συζητήσεις
  σχεδιασμού
- Συμμετάσχετε στα κανάλια της κοινότητάς μας
- Εξετάστε τις υπάρχουσες διαμορφώσεις υπογραφέων στο
  [`crates/lib/src/signer/config.rs`](https://github.com/solana-foundation/kora/blob/v2.0.5/crates/lib/src/signer/config.rs)

## Παράδειγμα Δομής PR

**Για αποθετήριο 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
```

Καλώς ήρθατε στο οικοσύστημα Kora! Είμαστε ενθουσιασμένοι που η λύση διαχείρισης
κλειδιών σας αποτελεί μέρος της πλατφόρμας.

Πίνακας Περιεχομένων