Nieuwe Ondertekenaars Toevoegen

Deze handleiding is bedoeld voor wallet service providers en ontwikkelaars die nieuwe key management-oplossingen willen integreren in de solana-keychain library. Door jouw signer-implementatie toe te voegen, stel je ontwikkelaars in staat om jouw service te gebruiken voor veilige Solana-transactieondertekening via een uniforme interface.

Gebruik je een LLM? Bekijk dan de Adding Signers Skill.

Architectuuroverzicht

De library gebruikt een trait-gebaseerde architectuur waarbij alle signers de SolanaSigner trait implementeren die gedefinieerd is in src/traits.rs. De library biedt ook een uniforme Signer enum die alle implementaties omhult, waardoor runtime-selectie van signing backends mogelijk is met behoud van een consistente API.

Snelle Integratie Checklist

Creëer je signer-module met implementatie
Implementeer de SolanaSigner trait (3 async methods + pubkey())
Voeg een feature flag toe in Cargo.toml
Update de Signer enum in src/lib.rs (4 match arms)
Update src/error.rs reqwest From impl cfg gate (als jouw signer reqwest gebruikt)
Forceer HTTPS en configureer timeouts op HTTP-clients
Voeg uitgebreide tests toe
Update documentatie
Dien PR in

Stap 1: Creëer Je Signer-Module

Maak een nieuwe directory aan onder src/ voor jouw implementatie:

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

Stap 2: Definieer Je Signer Struct

Definieer in src/your_service/mod.rs je signer 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()
    }
}

Stap 3: Implementeer Constructor en Hulpmethoden

Remote signers moeten HTTPS afdwingen en HTTP-timeouts configureren. Gebruik de gedeelde HttpClientConfig struct voor timeout-instellingen.

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

Stap 4: Implementeer de SolanaSigner Trait

De trait heeft 3 async methods (sign_transaction, sign_message, is_available) plus pubkey(). Merk op dat sign_transaction SignTransactionResult retourneert — een tagged enum die aangeeft of de transactie volledig ondertekend of gedeeltelijk ondertekend is.

Gebruik de gedeelde TransactionUtil helpers voor ondertekening en serialisatie.

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

Stap 5: API-types toevoegen (optioneel)

Als je API aangepaste types nodig heeft, maak dan src/your_service/types.rs aan:

use serde::{Deserialize, Serialize};

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

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

Stap 6: Feature flag toevoegen

Update Cargo.toml om je signer als optionele feature toe te voegen:

[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

Stap 7: De signer-enum updaten

Voeg je signer toe aan src/lib.rs. Je hebt 4 match arms nodig in de SolanaSigner impl: pubkey, sign_transaction, sign_message en 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,
        }
    }
}

Als je signer reqwest gebruikt, voeg dan je feature toe aan de #[cfg(any(...))] gate op de From<reqwest::Error> impl in src/error.rs.

Stap 8: Uitgebreide tests toevoegen

Voeg tests toe aan je module (onderaan src/your_service/mod.rs):

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

Stap 9: Documentatie updaten

Voeg je signer toe aan de tabel met ondersteunde backends in README.md:

Backend	Gebruikssituatie	Feature flag
Memory	Lokale keypairs, ontwikkeling, testen	`memory`
Vault	Enterprise key management met HashiCorp Vault	`vault`
Privy	Embedded wallets met Privy-infrastructuur	`privy`
Turnkey	Non-custodial key management via Turnkey	`turnkey`
YourService	Korte beschrijving van je service	`your_service`

Voeg gebruiksvoorbeeld toe:

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

Je integratie testen

Voer tests uit voor je feature:

# Test only your signer
cargo test --features your_service

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

TypeScript Signer

Als je ook een TypeScript signer-package toevoegt, maak deze dan aan op typescript/packages/your-signer/. Belangrijkste patronen:

Factory-functie createYourSigner() retourneert SolanaSigner<TAddress>
Exporteer config-interface (YourSignerConfig)
Dwing HTTPS af op apiBaseUrl config-velden
Saneer externe API-fouttekst met sanitizeRemoteErrorResponse() van @solana/keychain-core
Bescherm tegen misvormde JSON met optionele chaining en try/catch
Gebruik throwSignerError(SignerErrorCode.*, { cause, message }) van @solana/keychain-core
Voeg @throws JSDoc toe aan factory-functies met een lijst van foutcodes

Update Overkoepelend Pakket

Update typescript/packages/keychain/ — 6 bestanden om te wijzigen:

src/types.ts — Voeg YourSignerConfig toe aan KeychainSignerConfig discriminated union
src/create-keychain-signer.ts — Importeer factory, voeg switch case toe
src/resolve-address.ts — Voeg toe aan fast-path of fetch-path switch case
src/index.ts — Voeg config-type, namespace, factory-functie en class-exports toe
package.json — Voeg @solana/keychain-your-signer: "workspace:*" dependency toe
tsconfig.json — Voeg { "path": "../your-signer" } referentie toe

De switch-statements hebben exhaustieve never controles — TypeScript geeft een foutmelding als je aan de union toevoegt maar een case mist.

Indiening Checklist

Voordat je je PR indient:

Code compileert zonder waarschuwingen (just build)
Alle tests slagen (just test)
Code is geformatteerd/linting slaagt (just fmt)
Geen hardcoded waarden of secrets in code
Foutmeldingen zijn generiek (geen ruwe API-response tekst)
HTTPS afgedwongen op externe HTTP-clients
HTTP-timeouts geconfigureerd via HttpClientConfig
Volgt Rust-naamgevingsconventies (snake_case)
Toegevoegd aan README.md supported backends tabel

Implementatietips

Foutafhandeling

Gebruik altijd de bestaande SignerError varianten. Gebruik nooit .expect() of .unwrap() op onbetrouwbare API-responses:

// 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}")))?;

Best Practices voor Beveiliging

Log nooit gevoelige gegevens (private keys, API-secrets)
Gebruik Debug impl die gevoelige velden verbergt
Valideer alle inputs (public keys, handtekeningen)
Gebruik HTTPS voor alle externe API-calls (afgedwongen via https_only(true))
Configureer request- en connect-timeouts via HttpClientConfig
Laat nooit ruwe externe API-fouttekst zien in foutmeldingen
Gebruik Option<Pubkey> (niet Pubkey::default()) voor het public key veld vóór init()

Testen met Mocks

Gebruik wiremock voor het mocken van HTTP-API's. Assert alleen op het fouttype, niet op de fouttekst:

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

Hulp krijgen

Bekijk bestaande signer-implementaties voor patronen:
- src/memory/mod.rs — Eenvoudig, synchroon
- src/para/mod.rs — Vereist initialisatie (gebruik als patroon voor nieuwe signers)
- src/turnkey/mod.rs — Complexe signature-handling
- src/vault/mod.rs — Externe clientbibliotheek
Belangrijke bestanden: src/traits.rs (trait-definitie), src/transaction_util.rs (gedeelde helpers), src/http_client_config.rs (timeout-configuratie)
Open een issue voor ontwerpbesprekingen voordat je aan het werk gaat

Voorbeeld PR-structuur

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

Inhoudsopgave