Uusien allekirjoittajien lisääminen

Tämä opas on tarkoitettu lompakopalveluntarjoajille ja kehittäjille, jotka haluavat integroida uusia avaintenhallintaratkaisuja solana-keychain-kirjastoon. Lisäämällä oman allekirjoittajatoteutuksesi mahdollistat kehittäjille palvelusi käytön turvalliseen Solana-transaktioiden allekirjoitukseen yhtenäisen rajapinnan kautta.

Käytätkö LLM:ää? Tutustu Adding Signers Skill -taitoon.

Arkkitehtuurin yleiskatsaus

Kirjasto käyttää trait-pohjaista arkkitehtuuria, jossa kaikki allekirjoittajat toteuttavat SolanaSigner-traitin, joka on määritelty src/traits.rs-tiedostossa. Kirjasto tarjoaa myös yhtenäisen Signer-enumin, joka kapseloi kaikki toteutukset mahdollistaen allekirjoitustaustaosien ajonaikaisen valinnan säilyttäen samalla yhtenäisen API:n.

Pikaintegroinnin tarkistuslista

Luo allekirjoittajamoduulisi toteutuksineen
Toteuta SolanaSigner-trait (3 async-metodia + pubkey())
Lisää ominaisuuslippu Cargo.toml-tiedostoon
Päivitä Signer-enum src/lib.rs-tiedostossa (4 match-haaraa)
Päivitä src/error.rs reqwest From -toteutuksen cfg-portti (jos allekirjoittajasi käyttää reqwestiä)
Pakota HTTPS ja konfiguroi HTTP-asiakkaiden aikakatkaisut
Lisää kattavat testit
Päivitä dokumentaatio
Lähetä PR

Vaihe 1: Luo allekirjoittajamoduulisi

Luo uusi hakemisto src/-hakemiston alle toteutuksellesi:

src/
├── your_service/
│   ├── mod.rs      # Main implementation with SolanaSigner trait
│   └── types.rs    # API request/response types (if needed)

Vaihe 2: Määritä allekirjoittaja-struct

Määritä src/your_service/mod.rs-tiedostossa allekirjoittaja-struct:

//! YourService API signer integration

use crate::{error::SignerError, traits::SolanaSigner};
use solana_sdk::{pubkey::Pubkey, signature::Signature, transaction::Transaction};
use std::str::FromStr;

/// YourService-based signer using YourService's API
#[derive(Clone)]
pub struct YourServiceSigner {
    api_key: String,
    api_secret: String,
    wallet_id: String,
    api_base_url: String,
    client: reqwest::Client,
    public_key: Pubkey,
}

impl std::fmt::Debug for YourServiceSigner {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("YourServiceSigner")
            .field("public_key", &self.public_key)
            .finish_non_exhaustive()
    }
}

Vaihe 3: Toteuta konstruktori ja apumetodit

Etäallekirjoittajien on pakko pakottaa HTTPS ja konfiguroida HTTP-aikakatkaisut. Käytä jaettua HttpClientConfig-structia aikakatkaisuasetusten hallintaan.

use crate::http_client_config::HttpClientConfig;

impl YourServiceSigner {
    pub fn new(
        api_key: String,
        api_secret: String,
        wallet_id: String,
        public_key: String,
        http_config: Option<HttpClientConfig>,
    ) -> Result<Self, SignerError> {
        let pubkey = Pubkey::from_str(&public_key)
            .map_err(|e| SignerError::InvalidPublicKey(format!("Invalid public key: {e}")))?;

        let http = http_config.unwrap_or_default();
        let builder = reqwest::Client::builder()
            .timeout(http.resolved_request_timeout())
            .connect_timeout(http.resolved_connect_timeout());

        // Enforce HTTPS in production; wiremock uses HTTP in tests
        #[cfg(not(test))]
        let builder = builder.https_only(true);

        let client = builder.build().map_err(|e| {
            SignerError::ConfigError(format!("Failed to build HTTP client: {e}"))
        })?;

        Ok(Self {
            api_key,
            api_secret,
            wallet_id,
            api_base_url: "https://api.yourservice.com/v1".to_string(),
            client,
            public_key: pubkey,
        })
    }

    /// Sign raw bytes using your service's API
    async fn sign(&self, message: &[u8]) -> Result<Signature, SignerError> {
        let encoded_message = base64::engine::general_purpose::STANDARD.encode(message);

        let url = format!("{}/sign", self.api_base_url);
        let response = self
            .client
            .post(&url)
            .header("Authorization", format!("Bearer {}", self.api_key))
            .json(&serde_json::json!({
                "wallet_id": self.wallet_id,
                "message": encoded_message,
            }))
            .send()
            .await?;

        // Use generic error messages — never expose raw API response text
        if !response.status().is_success() {
            let status = response.status().as_u16();
            return Err(SignerError::RemoteApiError(format!(
                "YourService API returned status {status}"
            )));
        }

        // Parse response — always use map_err, never .expect() or .unwrap()
        let response_data: SignResponse = response
            .json()
            .await
            .map_err(|e| SignerError::SerializationError(format!("Failed to parse response: {e}")))?;
        let sig_bytes = base64::engine::general_purpose::STANDARD
            .decode(&response_data.signature)
            .map_err(|e| SignerError::SerializationError(format!("Failed to decode signature: {e}")))?;

        let sig_array: [u8; 64] = sig_bytes
            .try_into()
            .map_err(|_| SignerError::SigningFailed("Invalid signature length".to_string()))?;

        Ok(Signature::from(sig_array))
    }
}

Vaihe 4: Toteuta SolanaSigner-trait

Traitissa on 3 async-metodia (sign_transaction, sign_message, is_available) sekä pubkey(). Huomaa, että sign_transaction palauttaa SignTransactionResult-tyypin — merkityn enumin, joka ilmaisee, onko transaktio täysin allekirjoitettu vai osittain allekirjoitettu.

Käytä jaettuja TransactionUtil-apufunktioita allekirjoitukseen ja sarjallistamiseen.

use crate::transaction_util::TransactionUtil;
use crate::traits::SignTransactionResult;

#[async_trait::async_trait]
impl SolanaSigner for YourServiceSigner {
    fn pubkey(&self) -> Pubkey {
        self.public_key
    }

    async fn sign_transaction(
        &self,
        tx: &mut Transaction,
    ) -> Result<SignTransactionResult, SignerError> {
        let tx_bytes = bincode::serialize(tx)
            .map_err(|e| SignerError::SerializationError(format!("Failed to serialize: {e}")))?;

        let signature = self.sign(&tx_bytes).await?;

        // Add the signature at the correct position
        TransactionUtil::add_signature_to_transaction(tx, &self.public_key, signature)?;

        // Serialize and classify as Complete or Partial
        let serialized = TransactionUtil::serialize_transaction(tx)?;
        Ok(TransactionUtil::classify_signed_transaction(
            tx,
            (serialized, signature),
        ))
    }

    async fn sign_message(&self, message: &[u8]) -> Result<Signature, SignerError> {
        self.sign(message).await
    }

    async fn is_available(&self) -> bool {
        let url = format!("{}/health", self.api_base_url);
        self.client
            .get(&url)
            .send()
            .await
            .map(|r| r.status().is_success())
            .unwrap_or(false)
    }
}

Vaihe 5: Lisää API-tyypit (valinnainen)

Jos API:si tarvitsee mukautettuja tyyppejä, luo src/your_service/types.rs:

use serde::{Deserialize, Serialize};

#[derive(Serialize)]
pub struct SignRequest {
    pub wallet_id: String,
    pub message: String,
}

#[derive(Deserialize)]
pub struct SignResponse {
    pub signature: String,
}

Vaihe 6: Lisää ominaisuuslippu

Päivitä Cargo.toml lisätäksesi allekirjoittajasi valinnaisena ominaisuutena:

[features]
default = ["memory"]
memory = []
vault = ["dep:reqwest", "dep:vaultrs", "dep:base64"]
privy = ["dep:reqwest", "dep:base64"]
turnkey = ["dep:reqwest", "dep:base64", "dep:p256", "dep:hex", "dep:chrono"]
your_service = ["dep:reqwest", "dep:base64"]  # Add your feature
all = ["memory", "vault", "privy", "turnkey", "your_service"]  # Update all

Vaihe 7: Päivitä allekirjoittaja-enum

Lisää allekirjoittajasi kohteeseen src/lib.rs. Tarvitset 4 match-haaraa SolanaSigner-toteutuksessa: pubkey, sign_transaction, sign_message ja is_available.

// Add feature-gated module
#[cfg(feature = "your_service")]
pub mod your_service;

// Re-export your signer type
#[cfg(feature = "your_service")]
pub use your_service::YourServiceSigner;

// Add to Signer enum
#[derive(Debug)]
pub enum Signer {
    #[cfg(feature = "memory")]
    Memory(MemorySigner),

    // ... existing variants

    #[cfg(feature = "your_service")]
    YourService(YourServiceSigner),  // Add your variant
}

// Add constructor method
impl Signer {
    #[cfg(feature = "your_service")]
    pub fn from_your_service(
        api_key: String,
        api_secret: String,
        wallet_id: String,
        public_key: String,
    ) -> Result<Self, SignerError> {
        Ok(Self::YourService(YourServiceSigner::new(
            api_key,
            api_secret,
            wallet_id,
            public_key,
            None, // uses default HttpClientConfig
        )?))
    }
}

// Update trait implementation — 4 match arms
#[async_trait::async_trait]
impl SolanaSigner for Signer {
    fn pubkey(&self) -> sdk_adapter::Pubkey {
        match self {
            // ... existing variants
            #[cfg(feature = "your_service")]
            Signer::YourService(s) => s.pubkey(),
        }
    }

    async fn sign_transaction(
        &self,
        tx: &mut sdk_adapter::Transaction,
    ) -> Result<SignTransactionResult, SignerError> {
        match self {
            // ... existing variants
            #[cfg(feature = "your_service")]
            Signer::YourService(s) => s.sign_transaction(tx).await,
        }
    }

    async fn sign_message(
        &self,
        message: &[u8],
    ) -> Result<sdk_adapter::Signature, SignerError> {
        match self {
            // ... existing variants
            #[cfg(feature = "your_service")]
            Signer::YourService(s) => s.sign_message(message).await,
        }
    }

    async fn is_available(&self) -> bool {
        match self {
            // ... existing variants
            #[cfg(feature = "your_service")]
            Signer::YourService(s) => s.is_available().await,
        }
    }
}

Jos allekirjoittajasi käyttää reqwest-komentoa, lisää ominaisuutesi #[cfg(any(...))]-porttiin From<reqwest::Error>-toteutuksessa kohteessa src/error.rs.

Vaihe 8: Lisää kattavat testit

Lisää testit moduuliisi (src/your_service/mod.rs-tiedoston loppuun):

#[cfg(test)]
mod tests {
    use super::*;
    use solana_sdk::{signature::Keypair, signer::Signer};
    use wiremock::{
        matchers::{header, method, path},
        Mock, MockServer, ResponseTemplate,
    };

    #[tokio::test]
    async fn test_new() {
        let keypair = Keypair::new();
        let signer = YourServiceSigner::new(
            "test-key".to_string(),
            "test-secret".to_string(),
            "test-wallet".to_string(),
            keypair.pubkey().to_string(),
            None,
        );
        assert!(signer.is_ok());
    }

    #[tokio::test]
    async fn test_sign_message() {
        let mock_server = MockServer::start().await;
        let keypair = Keypair::new();
        let message = b"test message";
        let signature = keypair.sign_message(message);

        Mock::given(method("POST"))
            .and(path("/sign"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
                "signature": base64::engine::general_purpose::STANDARD.encode(signature.as_ref())
            })))
            .expect(1)
            .mount(&mock_server)
            .await;

        let mut signer = YourServiceSigner::new(
            "test-key".to_string(),
            "test-secret".to_string(),
            "test-wallet".to_string(),
            keypair.pubkey().to_string(),
            None,
        ).unwrap();
        signer.api_base_url = mock_server.uri();

        let result = signer.sign_message(message).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn test_sign_unauthorized() {
        let mock_server = MockServer::start().await;
        let keypair = Keypair::new();

        Mock::given(method("POST"))
            .and(path("/sign"))
            .respond_with(ResponseTemplate::new(401))
            .expect(1)
            .mount(&mock_server)
            .await;

        let mut signer = YourServiceSigner::new(
            "bad-key".to_string(),
            "bad-secret".to_string(),
            "test-wallet".to_string(),
            keypair.pubkey().to_string(),
            None,
        ).unwrap();
        signer.api_base_url = mock_server.uri();

        let result = signer.sign_message(b"test").await;
        assert!(result.is_err());
    }
}

Vaihe 9: Päivitä dokumentaatio

Lisää allekirjoittajasi tuettujen taustajärjestelmien taulukkoon README.md-tiedostossa:

Taustajärjestelmä	Käyttötarkoitus	Ominaisuuslippu
Memory	Paikalliset avainparit, kehitys, testaus	`memory`
Vault	Yritystason avainten hallinta HashiCorp Vaultilla	`vault`
Privy	Upotetut lompakot Privy-infrastruktuurilla	`privy`
Turnkey	Ei-säilytettävä avainten hallinta Turnkey-palvelun kautta	`turnkey`
YourService	Lyhyt kuvaus palvelustasi	`your_service`

Lisää käyttöesimerkki:

use solana_keychain::{Signer, SolanaSigner};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let signer = Signer::from_your_service(
        "your-api-key".to_string(),
        "your-api-secret".to_string(),
        "your-wallet-id".to_string(),
        "your-public-key".to_string(),
    )?;

    let pubkey = signer.pubkey();
    println!("Public key: {}", pubkey);

    Ok(())
}

Integraation testaaminen

Suorita testit ominaisuudellesi:

# Test only your signer
cargo test --features your_service

# Test with all features
cargo test --all-features

TypeScript-allekirjoittaja

Jos lisäät myös TypeScript-allekirjoittajapaketin, luo se sijaintiin typescript/packages/your-signer/. Keskeiset mallit:

Tehdas-funktio createYourSigner() palauttaa SolanaSigner<TAddress>
Vie config-rajapinta (YourSignerConfig)
Pakota HTTPS apiBaseUrl config-kentissä
Puhdista etä-API:n virheteksti käyttäen sanitizeRemoteErrorResponse() moduulista @solana/keychain-core
Suojaudu virheelliseltä JSON:lta valinnaisen ketjutuksen ja try/catch:n avulla
Käytä throwSignerError(SignerErrorCode.*, { cause, message }) moduulista @solana/keychain-core
Lisää @throws JSDoc tehdas-funktioihin listaten virhekoodit

Päivitä Kattopaketti

Päivitä typescript/packages/keychain/ — 6 tiedostoa muokattavana:

src/types.ts — Lisää YourSignerConfig KeychainSignerConfig erottelevaan unioniin
src/create-keychain-signer.ts — Tuo tehdas, lisää switch-case
src/resolve-address.ts — Lisää nopean polun tai haun polun switch-caseen
src/index.ts — Lisää config-tyyppi, nimiavaruus, tehdas-funktio ja luokkavientiä
package.json — Lisää @solana/keychain-your-signer: "workspace:*" riippuvuus
tsconfig.json — Lisää { "path": "../your-signer" } viite

Switch-lauseilla on tyhjentävät never tarkistukset — TypeScript antaa virheen, jos lisäät unioniin mutta unohdat casen.

Lähetyksen Tarkistuslista

Ennen PR:n lähettämistä:

Koodi kääntyy ilman varoituksia (just build)
Kaikki testit menevät läpi (just test)
Koodi on muotoiltu/linting menee läpi (just fmt)
Ei kovakoodattuja arvoja tai salaisuuksia koodissa
Virheilmoitukset ovat yleisiä (ei raakaa API-vastaustekstiä)
HTTPS pakotettu etä-HTTP-asiakkaissa
HTTP-aikakatkaisut määritetty HttpClientConfig kautta
Noudattaa Rustin nimeämiskäytäntöjä (snake_case)
Lisätty README.md:n tuettujen backendsien taulukkoon

Toteutusvinkkejä

Virheenkäsittely

Käytä aina olemassa olevia SignerError variantteja. Älä koskaan käytä .expect() tai .unwrap() epäluotettavissa API-vastauksissa:

// Good — uses existing error types with generic messages
return Err(SignerError::RemoteApiError(
    format!("YourService API returned status {}", status)
));

// Good — converts from standard errors
let bytes = base64::decode(data)
    .map_err(|e| SignerError::SerializationError(format!("Failed to decode: {e}")))?;

Turvallisuuden Parhaat Käytännöt

Älä koskaan lokita arkaluonteisia tietoja (yksityiset avaimet, API-salaisuudet)
Käytä Debug toteutusta, joka piilottaa arkaluonteiset kentät
Validoi kaikki syötteet (julkiset avaimet, allekirjoitukset)
Käytä HTTPS:ää kaikissa etä-API-kutsuissa (pakotettu https_only(true) kautta)
Määritä pyynnön ja yhteyden aikakatkaisut HttpClientConfig kautta
Älä koskaan paljasta raakaa etä-API:n virhetekstiä virheilmoituksissa
Käytä Option<Pubkey> (ei Pubkey::default()) julkisen avaimen kentälle ennen init()

Testaus mock-objekteilla

Käytä wiremock HTTP-rajapintojen mock-testaukseen. Tarkista vain virhetyyppi, ei virheviestin tekstiä:

#[cfg(test)]
mod tests {
    use wiremock::{MockServer, Mock, ResponseTemplate};

    #[tokio::test]
    async fn test_api_call() {
        let mock_server = MockServer::start().await;

        Mock::given(method("POST"))
            .respond_with(ResponseTemplate::new(200))
            .mount(&mock_server)
            .await;

        // Use mock_server.uri() as your api_base_url
    }
}

Avun saaminen

Tutustu olemassa oleviin allekirjoittajatoteutuksiin malleiksi:
- src/memory/mod.rs — Yksinkertainen, synkroninen
- src/para/mod.rs — Vaatii alustuksen (käytä mallina uusille allekirjoittajille)
- src/turnkey/mod.rs — Monimutkainen allekirjoituskäsittely
- src/vault/mod.rs — Ulkoinen asiakaskirjasto
Keskeiset tiedostot: src/traits.rs (trait-määrittely), src/transaction_util.rs (jaetut apufunktiot), src/http_client_config.rs (aikakatkaisu-asetukset)
Avaa issue suunnittelukeskusteluja varten ennen työn aloittamista

Esimerkki PR-rakenteesta

feat(signer): add YourService signer integration

Adds support for YourService as a signing backend.

- [X] Code compiles without warnings (`just build`)
- [X] Code is formatted/linting passes (`just fmt`)
- [X] Add comprehensive tests with wiremock - All tests pass (`just test`)
- [X] Implemented SolanaSigner trait for YourServiceSigner
- [X] Added feature flag 'your_service'
- [X] HTTPS enforced, HTTP timeouts configured
- [X] Added to README.md supported backends table

Closes #1337

Sisällysluettelo