OnyxOnyx
API Reference/StealthMetaAddress

StealthMetaAddress

The core identity primitive for stealth payments. A meta-address encapsulates both spending and viewing capabilities in a shareable format.

Quick Overview

Module:onyx_sdk::core
Traits:Clone, Debug, Serialize, Deserialize

Definition

struct
rust
pub struct StealthMetaAddress {
    /// Private spending key - controls fund access
    spending_key: SecretKey,
    /// Private viewing key - enables payment detection
    viewing_key: SecretKey,
    /// Public spending key derived from spending_key
    pub spending_pubkey: PublicKey,
    /// Public viewing key derived from viewing_key
    pub viewing_pubkey: PublicKey,
}

Constructor Methods

generate
pub fn generate() -> Result<Self>

Creates a new meta-address with cryptographically secure random keys.

use onyx_sdk::prelude::*;

let meta = StealthMetaAddress::generate()?;
println!("New identity created!");
from_seed
pub fn from_seed(seed: &[u8; 32]) -> Result<Self>

Derives a deterministic meta-address from a 32-byte seed. Same seed always produces the same keys.

use onyx_sdk::prelude::*;

// Derive from a known seed (e.g., from BIP-39 mnemonic)
let seed = [0u8; 32]; // Your seed bytes
let meta = StealthMetaAddress::from_seed(&seed)?;

Security Note: Never hardcode seeds. Use proper key derivation from secure sources.

from_keys
pub fn from_keys(spending: SecretKey, viewing: SecretKey) -> Self

Constructs a meta-address from existing secret keys.

use onyx_sdk::prelude::*;

let spending = SecretKey::generate();
let viewing = SecretKey::generate();

let meta = StealthMetaAddress::from_keys(spending, viewing);

Serialization Methods

save_to_file
pub fn save_to_file(&self, path: &str) -> Result<()>

Saves the complete meta-address (including private keys) to an encrypted JSON file.

let meta = StealthMetaAddress::generate()?;

// Save to file (creates directory if needed)
meta.save_to_file("~/.onyx/keys.json")?;
load_from_file
pub fn load_from_file(path: &str) -> Result<Self>

Loads a meta-address from an encrypted JSON file.

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

println!("Loaded: {}", meta.to_public().encode());

Public Key Methods

to_public
pub fn to_public(&self) -> PublicMetaAddress

Extracts the public portion suitable for sharing. This is what you give to senders.

let meta = StealthMetaAddress::generate()?;

// Get the shareable public address
let public_meta = meta.to_public();

// Encode for display/transmission
let encoded = public_meta.encode();
println!("Share this: {}", encoded);
// Output: onyx1q2w3e4r5t6y7u8i9o0p...
encode
pub fn encode(&self) -> String

Encodes the public meta-address as a bech32 string with 'onyx' prefix.

let public_meta = meta.to_public();
let encoded = public_meta.encode();

// Parse it back
let decoded = PublicMetaAddress::decode(&encoded)?;
assert_eq!(public_meta, decoded);

Stealth Address Generation

generate_stealth_address
pub fn generate_stealth_address(&self) -> Result<(Pubkey, [u8; 32])>

Generates a one-time stealth address and the ephemeral public key needed for the recipient to claim it.

use onyx_sdk::prelude::*;

// Sender has recipient's public meta-address
let recipient_public = PublicMetaAddress::decode("onyx1...")?;

// Generate a stealth address for payment
let (stealth_address, ephemeral_pubkey) = recipient_public.generate_stealth_address()?;

// stealth_address: The Solana address to send funds to
// ephemeral_pubkey: Must be published for recipient to find the payment
println!("Send to: {}", stealth_address);

View-Only Access

to_view_only
pub fn to_view_only(&self) -> ViewOnlyMetaAddress

Creates a view-only version that can detect incoming payments but cannot spend funds.

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

// Create view-only version for a watch service
let view_only = meta.to_view_only();

// Can scan for payments
let scanner = Scanner::new_view_only(&view_only);
let payments = scanner.scan(&announcements)?;

// But cannot derive spending keys
// view_only.derive_spending_key() -> Error!

Type Relationships

TypeContainsCan Do
StealthMetaAddressAll keys (public + private)Scan + Spend
ViewOnlyMetaAddressPublic + viewing private keyScan Only
PublicMetaAddressPublic keys onlyGenerate Stealth Addresses

Complete Example

full_workflow.rs
rust
use onyx_sdk::prelude::*;

fn main() -> Result<()> {
    // === RECIPIENT SETUP ===
    // Generate new identity (do this once)
    let meta = StealthMetaAddress::generate()?;
    meta.save_to_file("~/.onyx/keys.json")?;

    // Share this with senders
    let my_address = meta.to_public().encode();
    println!("My stealth address: {}", my_address);

    // === SENDER WORKFLOW ===
    // Sender parses recipient's public address
    let recipient = PublicMetaAddress::decode(&my_address)?;

    // Generate one-time payment address
    let (stealth_addr, ephemeral_pk) = recipient.generate_stealth_address()?;

    // Sender transfers funds to stealth_addr
    // Sender publishes ephemeral_pk to announcement registry

    // === RECIPIENT CLAIMING ===
    // Recipient scans and finds the payment
    let scanner = Scanner::new(&meta);
    let payments = scanner.scan(&announcements)?;

    for payment in payments {
        // Derive the spending keypair
        let keypair = StealthKeypair::derive(&meta, &payment.ephemeral_pubkey)?;

        // Now can sign transactions to move funds
        println!("Can spend {} SOL", payment.balance / LAMPORTS_PER_SOL);
    }

    Ok(())
}
Scanning PaymentsStealthPayment