miden-multisig-client 0.14.6

//! Main MultisigClient implementation.
//!
//! This module provides the [`MultisigClient`] type for interacting with multisig accounts.
//! The implementation is split across submodules for better organization:
//!
//! - `account` - Account lifecycle operations (create, pull, push, sync)
//! - `proposals` - Proposal workflow (list, sign, execute, propose)
//! - `offline` - Offline proposal operations
//! - `notes` - Note filtering and listing
//! - `io` - Export/import functionality
//! - `helpers` - Internal GUARDIAN client helpers

mod account;
mod helpers;
mod io;
mod notes;
mod offline;
mod proposals;

use std::path::PathBuf;
use std::sync::Arc;

use guardian_client::GetStateResponse;
use miden_client::rpc::Endpoint;
use miden_protocol::Word;
use miden_protocol::account::AccountId;

use crate::MidenSdkClient;
use crate::account::MultisigAccount;
use crate::builder::MultisigClientBuilder;
use crate::error::{MultisigError, Result};
use crate::export::ExportedProposal;
use crate::keystore::KeyManager;
use crate::proposal::Proposal;

pub use notes::{ConsumableNote, NoteFilter};

/// Result of a proposal creation attempt.
///
/// When creating a proposal, it may either succeed online (via GUARDIAN) or
/// fall back to offline mode if GUARDIAN is unavailable.
#[derive(Debug)]
pub enum ProposalResult {
    /// Proposal successfully created on GUARDIAN and ready for cosigners to sign.
    Online(Box<Proposal>),
    /// Offline proposal created when GUARDIAN is unavailable (`SwitchGuardian` transactions only).
    Offline(Box<ExportedProposal>),
}

/// Result of explicit local-vs-on-chain account state verification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StateVerificationResult {
    /// Account ID that was verified.
    pub account_id: AccountId,
    /// Local account commitment hex (with 0x prefix).
    pub local_commitment_hex: String,
    /// On-chain account commitment hex (with 0x prefix).
    pub on_chain_commitment_hex: String,
}

/// Main client for interacting with multisig accounts.
///
/// This client manages a single multisig account connected to a GUARDIAN server,
/// providing a high-level API for creating and managing multisig accounts,
/// proposals, and transactions.
///
/// # Example
///
/// ```ignore
/// use miden_multisig_client::MultisigClient;
/// use miden_client::rpc::Endpoint;
///
///
/// let mut client = MultisigClient::builder()
///     .miden_endpoint(Endpoint::new("http://localhost:57291"))
///     .guardian_endpoint("http://localhost:50051")
///     .data_dir("/tmp/multisig")
///     .generate_key()
///     .build()
///     .await?;
///
///
/// let account = client.create_account(2, vec![signer1, signer2]).await?;
/// ```
pub struct MultisigClient {
    pub(crate) miden_client: MidenSdkClient,
    pub(crate) key_manager: Arc<dyn KeyManager>,
    /// Guardian server endpoint.
    pub(crate) guardian_endpoint: String,
    /// The multisig account managed by this client.
    pub(crate) account: Option<MultisigAccount>,
    /// Account directory for miden-client storage (for recovery).
    pub(crate) account_dir: PathBuf,
    /// Miden node endpoint (for recovery).
    pub(crate) miden_endpoint: Endpoint,
}

impl MultisigClient {
    /// Creates a new MultisigClientBuilder.
    pub fn builder() -> MultisigClientBuilder {
        MultisigClientBuilder::new()
    }

    /// Creates a new MultisigClient (internal use, prefer builder).
    pub(crate) fn new(
        miden_client: MidenSdkClient,
        key_manager: Arc<dyn KeyManager>,
        guardian_endpoint: String,
        account_dir: PathBuf,
        miden_endpoint: Endpoint,
    ) -> Self {
        Self {
            miden_client,
            key_manager,
            guardian_endpoint,
            account: None,
            account_dir,
            miden_endpoint,
        }
    }

    /// Returns the GUARDIAN endpoint.
    pub fn guardian_endpoint(&self) -> &str {
        &self.guardian_endpoint
    }

    /// Returns the current account, if any.
    pub fn account(&self) -> Option<&MultisigAccount> {
        self.account.as_ref()
    }

    /// Returns the current account ID, if any.
    pub fn account_id(&self) -> Option<AccountId> {
        self.account.as_ref().map(|a| a.id())
    }

    /// Returns true if an account is loaded.
    pub fn has_account(&self) -> bool {
        self.account.is_some()
    }

    /// Returns the user's public key commitment as a Word.
    pub fn user_commitment(&self) -> Word {
        self.key_manager.commitment()
    }

    /// Returns the user's public key commitment as a hex string.
    pub fn user_commitment_hex(&self) -> String {
        self.key_manager.commitment_hex()
    }

    /// Returns a reference to the key manager.
    pub fn key_manager(&self) -> &dyn KeyManager {
        self.key_manager.as_ref()
    }

    /// Recover the set of accounts the configured signer authorizes by
    /// querying GUARDIAN's `/state/lookup` endpoint and fetching state for
    /// each match. Mirrors `MultisigClient.recoverByKey` in the TS SDK.
    /// Returns an empty list when no account on the configured GUARDIAN
    /// authorizes this commitment (distinct from "wrong key", which fails
    /// authentication first).
    pub async fn recover_by_key(&self) -> Result<Vec<RecoveredAccount>> {
        let mut guardian_client = self.create_authenticated_guardian_client().await?;
        let commitment_hex = self.user_commitment_hex();

        let lookup = guardian_client
            .lookup_account_by_key_commitment(&commitment_hex)
            .await
            .map_err(|e| MultisigError::GuardianServer(format!("lookup failed: {}", e)))?;

        let mut recovered = Vec::with_capacity(lookup.accounts.len());
        for entry in lookup.accounts {
            let account_id = AccountId::from_hex(&entry.account_id).map_err(|e| {
                MultisigError::InvalidConfig(format!(
                    "GUARDIAN returned non-AccountId hex '{}': {}",
                    entry.account_id, e
                ))
            })?;
            let state = guardian_client.get_state(&account_id).await.map_err(|e| {
                MultisigError::GuardianServer(format!(
                    "get_state failed for {}: {}",
                    entry.account_id, e
                ))
            })?;
            recovered.push(RecoveredAccount {
                account_id: entry.account_id,
                state,
            });
        }
        Ok(recovered)
    }
}

/// One match returned by [`MultisigClient::recover_by_key`]. Pairs the
/// discovered `account_id` with the current state response so callers do not
/// need to do a second round-trip per account.
#[derive(Debug, Clone)]
pub struct RecoveredAccount {
    pub account_id: String,
    pub state: GetStateResponse,
}