Προσθήκη Νέων Υπογραφόντων στο 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

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

Κάθε φάση ολοκλήρωσης αποτελεί το δικό της target [[test]] στο tests/Cargo.toml. Κάθε target εκκινεί ένα ενσωματωμένο surfnet μαζί με έναν κόμβο Kora μέσω του harness_context, ξεκινώντας από το μηδέν. Το Kora διατηρεί τη διαμόρφωση σε καθολική κατάσταση της διεργασίας, επομένως ένας νέος υπογράφων χρειάζεται ένα νέο target και όχι μια νέα ενότητα σε ένα υπάρχον.

1. Προσθήκη Fixture Υπογράφοντα

Δημιουργήστε μια διαμόρφωση υπογράφοντα στο 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. Προσθήκη Test Target

Καταχωρίστε τη φάση στο tests/Cargo.toml:

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

Στη συνέχεια, δημιουργήστε το tests/your_service/main.rs. Κατευθύνει το harness στο fixture σας και πρέπει να περιέχει τουλάχιστον ένα #[tokio::test] που δοκιμάζει τον υπογράφοντα:

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

Προσθέστε επίσης μια δοκιμή signTransaction, ώστε να εκτελείται η διαδρομή υπογραφής του υπογράφοντα και όχι μόνο η αναζήτηση κλειδιού. Το tests/multi_signer/ είναι ένα πλήρες παράδειγμα για αντιγραφή.

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

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

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

Κατά την υποβολή του 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

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

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

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

Για υλοποίηση signer: Ανοίξτε ένα issue στο αποθετήριο solana-keychain
Για ενσωμάτωση Kora: Ανοίξτε ένα issue στο αποθετήριο Kora για συζητήσεις σχεδιασμού
Εγγραφείτε στα κανάλια κοινότητάς μας
Ανατρέξτε στις υπάρχουσες διαμορφώσεις signer στο 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! Χαιρόμαστε που η λύση διαχείρισης κλειδιών σας αποτελεί μέρος της πλατφόρμας.

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