Uusien Allekirjoittajien Lisääminen Koraan

Arkkitehtuurin Yleiskatsaus

Kora käyttää ulkoista solana-keychain crate-pakettia kaikkiin allekirjoitusoperaatioihin. Tämä arkkitehtuuri tarjoaa yhtenäisen allekirjoitusrajapinnan Solana-tapahtumien allekirjoittamiseen. Uuden allekirjoittajan lisäämiseksi Koraan sinun täytyy:

Ensin: Lisää allekirjoittajatoteutuksesi solana-keychain crate-pakettiin
Toiseksi: Lisää määritystuki allekirjoittajallesi Korassa

Vaiheittainen Integrointiopas

Pikaintegroinnin Tarkistuslista

Osa 1: Lisää Allekirjoittaja solana-keychain Crate-pakettiin

Toteuta allekirjoittajasi noudattaen solana-keychain-integrointiopasta
Odota PR-hyväksyntää ja crate-julkaisua

Osa 2: Lisää Koran Määritystuki

Lisää allekirjoittajatuki Koraan

Varmista ensin, että allekirjoittajasi on tuettu solana-keychain-crate:ssa. Jos sitä ei tueta, noudata ohjetta osoitteessa: https://github.com/solana-foundation/solana-keychain/blob/main/docs/ADDING_SIGNERS.md

Vaihe 1: Päivitä Cargo.toml

Päivitä Cargo.toml:n riippuvuus siten, että solana-keychain-crate käyttää uusinta versiota (joka sisältää allekirjoittajasi):

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

Vaihe 2: Määrittele konfiguraatiorakenne

Lisää crates/lib/src/signer/config.rs-tiedostoon uusi konfiguraatiorakenne allekirjoittajallesi, joka määrittelee tarvittavat ympäristömuuttujat. Esimerkiksi:

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

Vaihe 2: Lisää allekirjoittajasi `SignerTypeConfig`-enumiin

Lisää allekirjoittajavarianttisi SignerTypeConfig-enumiin crates/lib/src/signer/config.rs-tiedostossa:

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

Vaihe 3: Lisää rakennuslogiikka

Lisää samaan tiedostoon (config.rs) metodi, joka rakentaa allekirjoittajasi konfiguraatiosta SignerConfig-toteutuksessa:

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

Huomautus: Metodin nimen Signer::from_your_service() tulisi vastata sitä, minkä toteutit solana-keychain-cratessa.

Vaihe 4: Lisää validointilogiikka

Lisää validointi allekirjoittajasi konfiguraatiolle validate_individual_signer_config-metodissa:

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

Vaihe 5: Vie konfiguraatiosi

Lisää uusi config-rakenteesi moduulin vienteihin crates/lib/src/signer/mod.rs-tiedostossa (tai tiedoston alussa, jos se on julkinen):

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

Integraation testaaminen

Lisää testimock-rakentaja

Testauksen helpottamiseksi lisää rakentajametodi SignerPoolConfigBuilder-rakenteeseen crates/lib/src/tests/config_mock.rs-tiedostossa:

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

Tämä mahdollistaa muiden testien luoda helposti mock-konfiguraatioita, jotka sisältävät allekirjoittajasi:

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

Ympäristömuuttujat

Lisää esimerkin ympäristömuuttujat seuraaviin tiedostoihin:

.env.example (projektin juuressa)
.env (projektin juuressa, paikallista testausta varten)
./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

Integraatiotestit

Jokainen integraatiovaihe on oma [[test]]-kohteensa tiedostossa tests/Cargo.toml. Jokainen kohde käynnistää upotetun surfnetin ja Kora-solmun harness_context-kontekstin kautta, alustettuna tyhjästä. Kora säilyttää konfiguraation prosessikohtaisessa globaalissa tilassa, joten uusi allekirjoittaja tarvitsee uuden kohteen eikä uutta moduulia olemassa olevaan kohteeseen.

1. Lisää allekirjoittajan testipohja

Luo allekirjoittajan konfiguraatio hakemistoon 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. Lisää testikohde

Rekisteröi vaihe tiedostossa tests/Cargo.toml:

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

Luo sitten tiedosto tests/your_service/main.rs. Se ohjaa testikehyksen käyttämään fixture-määritystäsi ja sen on sisällettävä vähintään yksi #[tokio::test], joka testaa allekirjoittajaa:

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

Lisää myös signTransaction-testi, jotta allekirjoittajan allekirjoituspolku tulee testattua eikä vain avaimen haku. tests/multi_signer/ on täydellinen esimerkki, jota voit käyttää mallina.

3. Testien suorittaminen

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

Dokumentointivaatimukset

Sisällytä PR:ääsi lähetettäessä:

1. Päivitä allekirjoittajien opas

Lisää allekirjoittajan dokumentaatio noudattaen ADDING_SIGNERS.md-opasta, selittäen esivalmistelut, asennuksen ja käytön.

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

Allekirjoittajan toteutukseen: Avaa issue solana-keychain -repositoriossa
Kora-integraatioon: Avaa issue Kora-repositoriossa suunnittelukeskusteluja varten
Liity yhteisökanavillemme
Tutustu olemassa oleviin allekirjoittajakonfiguraatioihin crates/lib/src/signer/config.rs

Esimerkki PR-rakenteesta

Kora-repositoriolle:

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

Tervetuloa Kora-ekosysteemiin! Olemme innoissamme siitä, että avaintenhallintatoteutuksesi on osa alustaa.