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::keys
Traits:Clone, Debug, Serialize, Deserialize

Definition

struct
rust
pub struct StealthMetaAddress {
    /// Private spending key (keep secret!)
    spending_key: [u8; 32],
    /// Private viewing key (keep secret!)
    viewing_key: [u8; 32],
    /// Public spending key (share publicly)
    spending_pubkey: [u8; 32],
    /// Public viewing key (share publicly)
    viewing_pubkey: [u8; 32],
}

Constructor Methods

generate
pub fn generate() -> Self

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

use onyx_sdk::StealthMetaAddress;

let meta = StealthMetaAddress::generate();
println!("New identity created!");

Serialization Methods

save_to_file
pub fn save_to_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

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

let meta = StealthMetaAddress::generate();

// Save to file
meta.save_to_file("~/.onyx/keys.json")?;
load_from_file
pub fn load_from_file<P: AsRef<Path>>(path: P) -> Result<Self>

Loads a meta-address from a JSON file.

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

println!("Loaded: {}", meta.public_meta_address().to_string());

Public Key Methods

public_meta_address
pub fn public_meta_address(&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.public_meta_address();

// Encode for display/transmission
println!("Share this: {}", public_meta.to_string());
// Output: stealth1Abc123...
to_public_string
pub fn to_public_string(&self) -> String

Shorthand for encoding the public meta-address to a string.

let meta = StealthMetaAddress::generate();

// Quick way to get shareable string
let address = meta.to_public_string();
println!("Share this: {}", address);

Key Accessor Methods

spending_key
pub fn spending_key(&self) -> &[u8; 32]

Returns the private spending key. Keep this secret!

viewing_key
pub fn viewing_key(&self) -> &[u8; 32]

Returns the private viewing key used for scanning payments.

spending_pubkey
pub fn spending_pubkey(&self) -> &[u8; 32]

Returns the public spending key.

viewing_pubkey
pub fn viewing_pubkey(&self) -> &[u8; 32]

Returns the public viewing key.

Spend Key Derivation

derive_spend_key
pub fn derive_spend_key(&self, ephemeral_pubkey: &[u8; 32]) -> Result<[u8; 32]>

Derives the spending key seed for a specific payment. Used internally by StealthKeypair::derive.

use onyx_sdk::StealthMetaAddress;

let meta = StealthMetaAddress::generate();

// Given an ephemeral pubkey from a payment
let ephemeral_pubkey: [u8; 32] = /* from announcement */;

// Derive the spend key seed
let seed = meta.derive_spend_key(&ephemeral_pubkey)?;

Type Relationships

TypeContainsCan Do
StealthMetaAddressAll keys (public + private)Scan + Spend
PublicMetaAddressPublic keys onlyGenerate Stealth Addresses

Complete Example

full_workflow.rs
rust
use onyx_sdk::{StealthMetaAddress, StealthPayment, StealthKeypair, Scanner, Announcement};

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

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

    // === SENDER WORKFLOW ===
    // Sender creates a payment using the public address
    let payment = StealthPayment::create(&my_address, 1_000_000_000).unwrap();
    println!("Send SOL to: {}", payment.stealth_address);

    // === RECIPIENT SCANNING ===
    // Recipient scans announcements
    let announcement = Announcement {
        ephemeral_pubkey: payment.ephemeral_pubkey,
        stealth_address: payment.stealth_address,
        timestamp: 0,
    };

    let scanner = Scanner::new(&meta);
    let payments = scanner.scan_announcements_list(&[announcement]).unwrap();

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

        // Now can sign transactions to move funds
        println!("Can spend from: {}", keypair.address());
    }
}
Scanning PaymentsStealthPayment