Concepts/Key Management

Key Management

Understanding how Onyx SDK handles cryptographic keys for stealth address generation, payment detection, and spending.

Overview

Onyx uses a dual-key system based on elliptic curve cryptography. This design separates the ability to view incoming payments from the ability to spend them, enabling powerful delegation scenarios.

🔐

Spending Key

The master private key that controls funds. Required to sign transactions and spend from stealth addresses.

👁

Viewing Key

Derived from the spending key. Allows detection of incoming payments without spending capability.

Meta-Address Structure

A stealth meta-address contains two public keys that recipients share publicly to receive payments:

st:sol:<spending_pubkey>:<viewing_pubkey>

st:sol:Protocol prefix (stealth address on Solana)

spending_pubkeyBase58-encoded spending public key

viewing_pubkeyBase58-encoded viewing public key

Generating Keys

Generate a new stealth meta-address with cryptographically secure random keys:

generate_keys.rs

rust

use onyx_sdk::prelude::*;

// Generate new stealth meta-address
let meta = StealthMetaAddress::generate()?;

// Access the public meta-address (safe to share)
let public_meta = meta.to_public();
println!("Share this address: {}", public_meta.encode());

// The meta-address contains private keys - keep it secret!
// Never share or expose the StealthMetaAddress itself

Secure Key Storage

Onyx provides file-based key storage with JSON serialization. Keys are stored locally and never transmitted.

key_storage.rs

rust

use onyx_sdk::prelude::*;

// Save keys to a file
let meta = StealthMetaAddress::generate()?;
meta.save_to_file("~/.onyx/keys.json")?;

// Load keys from file
let loaded_meta = StealthMetaAddress::load_from_file("~/.onyx/keys.json")?;

// Verify they match
assert_eq!(
    meta.to_public().encode(),
    loaded_meta.to_public().encode()
);

Security Warning

The key file contains your spending key. Anyone with access to this file can spend your funds. Use appropriate file permissions and consider encrypting the file at rest.

View-Only Access

You can share viewing keys with third parties (like accounting software or auditors) to let them detect your incoming payments without giving them spending access.

view_only.rs

rust

use onyx_sdk::prelude::*;

let meta = StealthMetaAddress::load_from_file("~/.onyx/keys.json")?;

// Extract viewing key (cannot spend, only detect payments)
let viewing_key = meta.viewing_key();

// Create a view-only scanner
let scanner = Scanner::new_view_only(&viewing_key);

// Scan for payments - can detect but not spend
let payments = scanner.scan(&announcements)?;
for payment in payments {
    println!("Found payment to: {}", payment.stealth_address);
    // Cannot derive spending key with view-only access
}

Key Derivation for Spending

When a payment is detected, the spending key for that specific stealth address is derived using ECDH (Elliptic Curve Diffie-Hellman) with the ephemeral public key.

derive_spending.rs

rust

use onyx_sdk::prelude::*;

let meta = StealthMetaAddress::load_from_file("~/.onyx/keys.json")?;

// After detecting a payment with ephemeral_pubkey...
let ephemeral_pubkey: [u8; 32] = /* from announcement */;

// Derive the stealth keypair for this specific payment
let stealth_keypair = StealthKeypair::derive(&meta, &ephemeral_pubkey)?;

// Get the Solana keypair for signing transactions
let solana_keypair = stealth_keypair.to_solana_keypair()?;

// Now you can sign transactions to spend from this address
println!("Can spend from: {}", solana_keypair.pubkey());

Best Practices

Backup your keys — Use the export command to create encrypted backups of your meta-address.
Use file permissions — Set restrictive permissions (chmod 600) on your key files.
Separate viewing access — Share viewing keys instead of full access when possible.
Rotate keys periodically — Generate new meta-addresses for enhanced privacy over time.

Stealth Addresses Scanning Payments