Private Key Wallets

Private key wallets accept raw extended signing keys (96 bytes, hex-encoded) directly—no mnemonic derivation. They work with keys generated externally or loaded from key management systems.

What They Are

Direct cryptographic signing keys in extended format (xprv), bypassing mnemonic derivation entirely. You provide 192-character hex strings representing 96-byte extended signing keys.

When to Use

Server automation: Backend services requiring automated signing
CI/CD pipelines: Automated testing with dedicated keys
Payment processors: High-volume transaction signing
Treasury systems: Programmatic fund management
External key integration: Keys from HSMs or enterprise vaults

Why They Work

Eliminate derivation overhead, integrate with hardware security modules (HSMs) and enterprise key vaults, enable programmatic key generation and rotation.

How to Secure

Critical: You manage raw cryptographic material with no backup mechanism.

Requirements for production:

Store in dedicated secret management (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
Rotate keys regularly with automated schedules
Encrypt at rest and in transit
Audit all key access
Use separate keys per service and environment

Never log or transmit keys in plaintext. Never store in environment variables as source of truth (use only for runtime injection). Never commit to version control.

Basic Setup

import {  } from "@evolution-sdk/evolution";

// Create signing-only client with private key (no provider)
// Can sign transactions but cannot query blockchain or submit
const  = ({
  : "preprod",
  : {
    : "private-key",
    : ..!  // 192 hex chars
    // Optional: stakeKey for staking operations
  }
});

const  = await .();
.("Payment address:", );

// To query blockchain or submit, attach a provider:
// const fullClient = client.attachProvider({ type: "blockfrost", ... });

Configuration Options

interface PrivateKeyWalletConfig {
  : "private-key"
  : string    // Extended signing key (96 bytes = 192 hex chars) (required)
  ?: string     // Extended staking key (optional)
}

Production Pattern with Vault

Load keys from secure secret management systems:

import {  } from "@evolution-sdk/evolution";

// Mock vault client for documentation purposes
declare const : {
  (: { : string }): {
    (): <{ : string }>
  }
};

async function () {
  // Load from secure vault (AWS Secrets Manager, Azure Key Vault, etc.)
  const  = await ("cardano-payment-key");
  
  return ({
    : "mainnet",
    : {
      : "private-key",
      : 
    }
  });
}

// Example vault integration pattern
async function (: string): <string> {
  // Example: AWS Secrets Manager pattern
  const {  } = await .({
    : 
  }).();
  
  return .().paymentKey;
}

Key Management Checklist

Generation: Use cryptographically secure RNG. Generate offline or in trusted environments. Move to secure storage before any network exposure. Never use predictable sources.

Storage: Use dedicated secret management systems. Consider hardware security modules (HSMs) for high-value operations. Encrypt at rest. Do not use environment variables as source of truth. Do not use configuration files.

Rotation: Implement automated schedules. Maintain previous keys during transition periods. Audit all rotation events. Test rotation procedures in staging environments first.

Access Control: Apply least privilege principles (only services that need signing). Use separate keys per service. Use separate keys per environment (dev/staging/prod). Use separate keys based on risk level.

Monitoring:

Log all key access events without logging the keys themselves. Alert on unusual access patterns. Track which service used which key and when. Never log key material.

AWS Secrets Manager Example

import {  } from "@evolution-sdk/evolution";

// Mock AWS SDK classes for documentation
declare class  {
  constructor(: { : string });
  (: ): <{ ?: string }>;
}

declare class  {
  constructor(: { : string });
}

const  = new ({ : "us-east-1" });

async function () {
  // Retrieve secret
  const  = new ({
    : "prod/cardano/payment-key"
  });
  
  const  = await .();
  const  = .(.!);
  
  // Create client with retrieved key
  return ({
    : "mainnet",
    : {
      : "private-key",
      : .paymentKey
    }
  });
}

Azure Key Vault Example

import {  } from "@evolution-sdk/evolution";

// Mock Azure SDK classes for documentation
declare class  {}

declare class  {
  constructor(: string, : any);
  (: string): <{ ?: string }>;
}

const  = new ();
const  = "https://your-vault.vault.azure.net";
const  = new (, );

async function () {
  // Retrieve secret
  const  = await .("cardano-payment-key");
  
  return ({
    : "mainnet",
    : {
      : "private-key",
      : .!
    }
  });
}

Key Rotation Strategy

import {  } from "@evolution-sdk/evolution";

async function () {
  // 1. Generate new key (offline, secure environment)
  const  = await ();
  
  // 2. Store new key in vault
  await ("cardano-payment-key-new", );
  
  // 3. Create client with new key
  const  = ({
    : "mainnet",
    : {
      : "private-key",
      : await ("cardano-payment-key-new")
    }
  });
  
  // 4. Monitor for issues
  await ();
  
  // 5. After confirmation period, promote new key
  await ("cardano-payment-key-new", "cardano-payment-key");
  
  // 6. Archive old key (don't delete immediately)
  await ("cardano-payment-key-old");
}

declare function (): <string>;
declare function (: string, : string): <void>;
declare function (: string): <string>;
declare function (: any): <void>;
declare function (: string, : string): <void>;
declare function (: string): <void>;

Environment Separation

import {  } from "@evolution-sdk/evolution";

// Development
const  = ({
  : "preprod",
  : {
    : "private-key",
    : await ("dev/cardano-payment-key")
  }
});

// Staging
const  = ({
  : "preprod",  // Still testnet
  : {
    : "private-key",
    : await ("staging/cardano-payment-key")  // Different key
  }
});

// Production
const  = ({
  : "mainnet",
  : {
    : "private-key",
    : await ("prod/cardano-payment-key")  // Different key
  }
});

declare function (: string): <string>;

Security Reminders

Critical Security Rules

Never hardcode keys in source code. Never commit keys to Git repositories. Never log key material to console or logging systems. Never transmit keys over unencrypted channels. Never reuse keys across different environments. Never share keys between different services.

Always use dedicated secret management solutions like AWS Secrets Manager or Azure Key Vault. Always implement key rotation with regular schedules. Always audit key access with comprehensive logging. Always encrypt keys both at rest and in transit.

Next Steps

API Wallets - User-facing applications
Client patterns - Backend architecture and client wiring
Security - Complete security guide

Private Key Wallets

On this page