khadhroony-solana-project/crates/ksp-wallet-lib/src/metadata.rs

// file: crates/ksp-wallet-lib/src/metadata.rs
// version: 5

/// Protected metadata requested when creating a new native Wallet.
///
/// Alias and note texts are never rendered by `Debug`. Wallet generates stable random note identifiers when the metadata is sealed into the V1 payload.
#[derive(Default, Eq, PartialEq)]
pub struct WalletCreateMetadataV1 {
    alias: std::option::Option<std::string::String>,
    note_texts: std::vec::Vec<std::string::String>,
}

impl WalletCreateMetadataV1 {
    /// Creates protected initial Wallet metadata.
    #[must_use]
    pub fn new(alias: std::option::Option<std::string::String>, note_texts: std::vec::Vec<std::string::String>) -> Self {
        return Self { alias, note_texts };
    }

    /// Consumes this value and returns parts.
    pub(crate) fn into_parts(self) -> (std::option::Option<std::string::String>, std::vec::Vec<std::string::String>) {
        return (self.alias, self.note_texts);
    }
}

impl std::fmt::Debug for WalletCreateMetadataV1 {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter
            .debug_struct("WalletCreateMetadataV1")
            .field("alias", &self.alias.as_ref().map(|_| return "<redacted>"))
            .field("note_count", &self.note_texts.len())
            .finish();
    }
}

/// One protected Wallet note exposed only after VIEW or OWNER authorization.
#[derive(Clone, Eq, PartialEq)]
pub struct WalletNote {
    id: std::string::String,
    text: std::string::String,
}

impl WalletNote {
    /// Creates a new `WalletNote` value.
    pub(crate) fn new(id: std::string::String, text: std::string::String) -> Self {
        return Self { id, text };
    }

    /// Returns the stable note identifier used by Wallet administration operations.
    #[must_use]
    pub fn id(&self) -> &str {
        return self.id.as_str();
    }

    /// Returns the protected note text after authorization.
    #[must_use]
    pub fn text(&self) -> &str {
        return self.text.as_str();
    }
}

impl std::fmt::Debug for WalletNote {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter.debug_struct("WalletNote").field("id", &"<redacted>").field("text", &"<redacted>").finish();
    }
}

/// Safe metadata projection produced after VIEW or OWNER authorization.
#[derive(Clone, Eq, PartialEq)]
pub struct WalletInfo {
    format_version: u32,
    capability: crate::WalletCapability,
    pubkey: ksp_core_lib::Pubkey,
    alias: std::option::Option<std::string::String>,
    notes: std::vec::Vec<crate::WalletNote>,
}

impl WalletInfo {
    /// Creates a new `WalletInfo` value.
    pub(crate) fn new(
        format_version: u32,
        capability: crate::WalletCapability,
        pubkey: ksp_core_lib::Pubkey,
        alias: std::option::Option<std::string::String>,
        notes: std::vec::Vec<crate::WalletNote>,
    ) -> Self {
        return Self { format_version, capability, pubkey, alias, notes };
    }

    /// Returns the native Wallet format version parsed for this projection.
    #[must_use]
    pub const fn format_version(&self) -> u32 {
        return self.format_version;
    }

    /// Returns the authorization capability that produced this projection.
    #[must_use]
    pub const fn capability(&self) -> crate::WalletCapability {
        return self.capability;
    }

    /// Returns the authorized Solana public key using the KSP Core re-export.
    #[must_use]
    pub const fn pubkey(&self) -> &ksp_core_lib::Pubkey {
        return &self.pubkey;
    }

    /// Returns the protected internal alias after authorization, when present.
    #[must_use]
    pub fn alias(&self) -> std::option::Option<&str> {
        return self.alias.as_deref();
    }

    /// Returns the protected Wallet notes after authorization.
    #[must_use]
    pub fn notes(&self) -> &[crate::WalletNote] {
        return self.notes.as_slice();
    }
}

impl std::fmt::Debug for WalletInfo {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter
            .debug_struct("WalletInfo")
            .field("format_version", &self.format_version)
            .field("capability", &self.capability)
            .field("pubkey", &self.pubkey)
            .field("alias", &self.alias.as_ref().map(|_| return "<redacted>"))
            .field("note_count", &self.notes.len())
            .finish();
    }
}

/// Minimal non-secret information available while a native Wallet remains locked.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct LockedWalletInfo {
    format_version: u32,
    view_enabled: bool,
}

impl LockedWalletInfo {
    /// Creates a new `LockedWalletInfo` value.
    pub(crate) const fn new(format_version: u32, view_enabled: bool) -> Self {
        return Self { format_version, view_enabled };
    }

    /// Returns the native Wallet format version.
    #[must_use]
    pub const fn format_version(&self) -> u32 {
        return self.format_version;
    }

    /// Reports whether a VIEW capability slot exists without exposing its protected contents.
    #[must_use]
    pub const fn view_enabled(&self) -> bool {
        return self.view_enabled;
    }
}

#[cfg(test)]
#[path = "../unit_tests/metadata.rs"]
mod tests;