17549972632

Committed 08 Sep 2025 11:57AM UTC coverage: 60.917% (-0.2%) from 61.111%

Build # 17549972632

Build Type

push

github

Committed by

web-flow

Commit Message

feat: wallet multisignature feature (#7481)

Description
---
This PR introduces support for multisignature (multisig) functionality
across the CLI and gRPC interfaces.

Cli methods provided
- SignMessage - Needed in Tari_Universe to sign messages 
- SignScriptMessage- Needed in tari_universe to sign script message
- PrepareDepositMultisigTransaction - Test purpose only. Create
transaction for converting normal utxo into multisign one. Without
signing it (needed in tari_universe for offline signing)
- PrepareWithdrawMultisigTransaction - Test purpose only. Create
transaction for converting multisig utxo into normal one. Without
signing it (needed in tari_universe for offline signing)
- SignOneSidedDepositMultisigTransaction - Sign the Prepared deposit
transaction (for offline signing in tari_universe).
- SignOneSidedWithdrawMultisigTransaction - Sign the Prepared withdraw
transaction (for offline signing in tari_universe).
- CreateMultisigUtxo - It is the same as
PrepareDepositMultisigTransaction /
SignOneSidedDepositMultisigTransaction but it can be called only from
cli.(won't work with offline signing)
- GetMultisigUtxoData - Return Data from utxo that are needed for
multisig (challenge / public_offset_key).
- SendMultisigUtxo - It is the same as
PrepareWithdrawMultisigTransaction /
SignOneSidedWithdrawMultisigTransaction but it can be called only from
cli.(won't work with offline signing)


GRPC methods
- PrepareDepositMultisigTransaction 
- PrepareWithdrawMultisigTransaction - transaction for converting
multisig utxo into normal one. Without signing it (needed in
tari_universe for offline signing)

Motivation and Context
---

How Has This Been Tested?
---
Written unit test and manually both from CLI and from tari universe
offline signing.

What process can a PR reviewer use to test or verify this change?
---
The change can be tested from the wallet using Docker.

**1. Create a multisignature UTXO (replace with your own data):**

```
docker compose ... (continued)

Run Details

847 of 1880 new or added lines in 17 files covered. (45.05%)

8 existing lines in 5 files now uncovered.

73757 of 121077 relevant lines covered (60.92%)

296113.71 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

69.71

/base_layer/transaction_components/src/key_manager/wrapper.rs

//  Copyright 2023, The Tari Project
//
//  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
//  following conditions are met:
//
//  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
//  disclaimer.
//
//  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
//  following disclaimer in the documentation and/or other materials provided with the distribution.
//
//  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
//  products derived from this software without specific prior written permission.
//
//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
//  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
//  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
//  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
//  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
//  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
//  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

use std::{
    fmt::{Debug, Formatter},
    sync::Arc,
};

use blake2::Blake2b;
use digest::consts::U64;
use tari_common_types::{
    seeds::cipher_seed::CipherSeed,
    tari_address::TariAddress,
    types::{
        ComAndPubSignature,
        CommsDHKE,
        CompressedCommitment,
        CompressedPublicKey,
        CompressedSignature,
        PrivateKey,
        RangeProof,
        WalletMessageSchnorrSignature,
    },
    wallet_types::WalletType,
};
use tari_crypto::{hashing::DomainSeparatedHash, ristretto::RistrettoComSig};
use tari_script::{CompressedCheckSigSchnorrSignature, TariScript};
use tokio::sync::RwLock;

use crate::{
    crypto_factories::CryptoFactories,
    key_manager::{
        error::KeyManagerServiceError,
        interface::{SecretTransactionKeyManagerInterface, TariKeyAndId, TransactionKeyManagerBackend, TxoStage},
        AddResult,
        TariKeyId,
        TransactionKeyManagerInner,
        TransactionKeyManagerInterface,
    },
    transaction_components::{
        EncryptedData,
        KernelFeatures,
        MemoField,
        RangeProofType,
        TransactionError,
        TransactionInputVersion,
        TransactionKernelVersion,
        TransactionOutputVersion,
    },
    MicroMinotari,
};

/// The key manager provides a hierarchical key derivation function (KDF) that derives uniformly random secret keys from
/// a single seed key for arbitrary branches, using an implementation of `KeyManagerBackend` to store the current index
/// for each branch.
///
/// This handle can be cloned cheaply and safely shared across multiple threads.
#[derive(Clone)]
pub struct TransactionKeyManagerWrapper<TBackend> {
    transaction_key_manager_inner: Arc<RwLock<TransactionKeyManagerInner<TBackend>>>,
}

impl<TBackend> TransactionKeyManagerWrapper<TBackend>
where TBackend: TransactionKeyManagerBackend + 'static
{
    /// Creates a new key manager.
    /// * `master_seed` is the primary seed that will be used to derive all unique branch keys with their indexes
    /// * `db` implements `KeyManagerBackend` and is used for persistent storage of branches and indices.
    pub async fn new(
        master_seed: CipherSeed,
        db: TBackend,
        crypto_factories: CryptoFactories,
        wallet_type: Arc<WalletType>,
    ) -> Result<Self, KeyManagerServiceError> {
        Ok(TransactionKeyManagerWrapper {
            transaction_key_manager_inner: Arc::new(RwLock::new(
                TransactionKeyManagerInner::new(master_seed, db, crypto_factories, wallet_type).await?,
            )),
        })
    }

    /// Get the wallet type
    pub async fn get_wallet_type(&self) -> Arc<WalletType> {
        self.transaction_key_manager_inner.read().await.get_wallet_type()
    }

    /// Get the birthday of the wallet seed
    pub async fn get_birthday(&self) -> u16 {
        self.transaction_key_manager_inner.read().await.master_seed().birthday()
    }
}

#[async_trait::async_trait]
impl<TBackend> TransactionKeyManagerInterface for TransactionKeyManagerWrapper<TBackend>
where TBackend: TransactionKeyManagerBackend + 'static
{
    async fn add_new_branch<T: Into<String> + Send>(&self, branch: T) -> Result<AddResult, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .write()
            .await
            .add_key_manager_branch(&branch.into())
            .await
    }

    async fn get_next_key<T: Into<String> + Send>(&self, branch: T) -> Result<TariKeyAndId, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_next_key(&branch.into())
            .await
    }

    async fn get_random_key(&self) -> Result<TariKeyAndId, KeyManagerServiceError> {
        self.transaction_key_manager_inner.read().await.get_random_key().await
    }

    async fn get_static_key<T: Into<String> + Send>(&self, branch: T) -> Result<TariKeyId, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_static_key(&branch.into())
            .await
    }

    async fn get_public_key_at_key_id(
        &self,
        key_id: &TariKeyId,
    ) -> Result<CompressedPublicKey, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_public_key_at_key_id(key_id)
            .await
    }

    async fn import_key(&self, private_key: PrivateKey) -> Result<TariKeyId, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .import_key(private_key)
            .await
    }

    async fn get_commitment(
        &self,
        commitment_mask_key_id: &TariKeyId,
        value: &PrivateKey,
    ) -> Result<CompressedCommitment, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_commitment(commitment_mask_key_id, value)
            .await
    }

    async fn verify_mask(
        &self,
        commitment: &CompressedCommitment,
        commitment_mask_key_id: &TariKeyId,
        value: u64,
    ) -> Result<bool, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .verify_mask(commitment, commitment_mask_key_id, value)
            .await
    }

    async fn get_view_key(&self) -> Result<TariKeyAndId, KeyManagerServiceError> {
        self.transaction_key_manager_inner.read().await.get_view_key().await
    }

    async fn get_private_view_key(&self) -> Result<PrivateKey, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_private_view_key()
            .await
    }

    async fn get_spend_key(&self) -> Result<TariKeyAndId, KeyManagerServiceError> {
        self.transaction_key_manager_inner.read().await.get_spend_key().await
    }

    async fn sign_message_with_spend_key(
        &self,
        message: &[u8],
        sender_offset_pub_key: Option<&CompressedPublicKey>,
    ) -> Result<WalletMessageSchnorrSignature, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .sign_message(message, sender_offset_pub_key)
            .await
    }

    async fn get_comms_key(&self) -> Result<TariKeyAndId, KeyManagerServiceError> {
        self.transaction_key_manager_inner.read().await.get_comms_key().await
    }

    async fn get_next_commitment_mask_and_script_key(
        &self,
    ) -> Result<(TariKeyAndId, TariKeyAndId), KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_next_commitment_mask_and_script_key()
            .await
    }

    async fn find_script_key_id_from_commitment_mask_key_id(
        &self,
        commitment_mask_key_id: &TariKeyId,
        public_script_key: Option<&CompressedPublicKey>,
    ) -> Result<Option<TariKeyId>, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .find_script_key_id_from_commitment_mask_key_id(commitment_mask_key_id, public_script_key)
            .await
    }

    async fn get_diffie_hellman_shared_secret(
        &self,
        secret_key_id: &TariKeyId,
        public_key: &CompressedPublicKey,
    ) -> Result<CommsDHKE, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_diffie_hellman_shared_secret(secret_key_id, public_key)
            .await
    }

    async fn get_diffie_hellman_stealth_domain_hasher(
        &self,
        secret_key_id: &TariKeyId,
        public_key: &CompressedPublicKey,
    ) -> Result<DomainSeparatedHash<Blake2b<U64>>, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_diffie_hellman_stealth_domain_hasher(secret_key_id, public_key)
            .await
    }

    async fn construct_range_proof(
        &self,
        commitment_mask_key_id: &TariKeyId,
        value: u64,
        min_value: u64,
    ) -> Result<RangeProof, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .construct_range_proof(commitment_mask_key_id, value, min_value)
            .await
    }

    async fn get_script_signature(
        &self,
        script_key_id: &TariKeyId,
        commitment_mask_key_id: &TariKeyId,
        value: &PrivateKey,
        txi_version: &TransactionInputVersion,
        script_message: &[u8; 32],
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_script_signature(
                script_key_id,
                commitment_mask_key_id,
                value,
                txi_version,
                script_message,
            )
            .await
    }

    async fn get_partial_script_signature(
        &self,
        commitment_mask_id: &TariKeyId,
        value: &PrivateKey,
        txi_version: &TransactionInputVersion,
        ephemeral_pubkey: &CompressedPublicKey,
        script_public_key: &CompressedPublicKey,
        script_message: &[u8; 32],
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_partial_script_signature(
                commitment_mask_id,
                value,
                txi_version,
                ephemeral_pubkey,
                script_public_key,
                script_message,
            )
            .await
    }

    async fn get_partial_txo_kernel_signature(
        &self,
        commitment_mask_key_id: &TariKeyId,
        nonce_id: &TariKeyId,
        total_nonce: &CompressedPublicKey,
        total_excess: &CompressedPublicKey,
        kernel_version: &TransactionKernelVersion,
        kernel_message: &[u8; 32],
        kernel_features: &KernelFeatures,
        txo_type: TxoStage,
    ) -> Result<CompressedSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_partial_txo_kernel_signature(
                commitment_mask_key_id,
                nonce_id,
                total_nonce,
                total_excess,
                kernel_version,
                kernel_message,
                kernel_features,
                txo_type,
            )
            .await
    }

    async fn get_txo_kernel_signature_excess_with_offset(
        &self,
        commitment_mask_key_id: &TariKeyId,
        nonce_id: &TariKeyId,
    ) -> Result<CompressedPublicKey, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_txo_kernel_signature_excess_with_offset(commitment_mask_key_id, nonce_id)
            .await
    }

    async fn get_txo_private_kernel_offset(
        &self,
        commitment_mask_key_id: &TariKeyId,
        nonce_id: &TariKeyId,
    ) -> Result<PrivateKey, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_txo_private_kernel_offset(commitment_mask_key_id, nonce_id)
            .await
    }

    async fn encrypt_data_for_recovery(
        &self,
        commitment_mask_key_id: &TariKeyId,
        custom_recovery_key_id: Option<&TariKeyId>,
        value: u64,
        payment_id: MemoField,
    ) -> Result<EncryptedData, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .encrypt_data_for_recovery(commitment_mask_key_id, custom_recovery_key_id, value, payment_id)
            .await
    }

    async fn extract_payment_id_from_encrypted_data(
        &self,
        encrypted_data: &EncryptedData,
        commitment: &CompressedCommitment,
        custom_recovery_key_id: Option<&TariKeyId>,
    ) -> Result<MemoField, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .extract_payment_id_from_encrypted_data(encrypted_data, commitment, custom_recovery_key_id)
            .await
    }

    async fn try_output_key_recovery(
        &self,
        commitment: &CompressedCommitment,
        encrypted_data: &EncryptedData,
        custom_recovery_key: Option<PrivateKey>,
    ) -> Result<(TariKeyId, MicroMinotari, MemoField), TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .try_output_key_recovery(commitment, encrypted_data, custom_recovery_key)
            .await
    }

    async fn is_this_output_ours(
        &self,
        commitment: &CompressedCommitment,
        encrypted_data: &EncryptedData,
        custom_recovery_key_id: Option<&TariKeyId>,
    ) -> Result<bool, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .is_this_output_ours(commitment, encrypted_data, custom_recovery_key_id)
            .await
    }

    async fn get_script_offset(
        &self,
        script_key_ids: &[TariKeyId],
        sender_offset_key_ids: &[TariKeyId],
    ) -> Result<PrivateKey, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_script_offset(script_key_ids, sender_offset_key_ids)
            .await
    }

    async fn get_metadata_signature_ephemeral_commitment(
        &self,
        nonce_id: &TariKeyId,
        range_proof_type: RangeProofType,
    ) -> Result<CompressedCommitment, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_metadata_signature_ephemeral_commitment(nonce_id, range_proof_type)
            .await
    }

    async fn get_metadata_signature(
        &self,
        commitment_mask_key_id: &TariKeyId,
        value_as_private_key: &PrivateKey,
        sender_offset_key_id: &TariKeyId,
        txo_version: &TransactionOutputVersion,
        metadata_signature_message: &[u8; 32],
        range_proof_type: RangeProofType,
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_metadata_signature(
                commitment_mask_key_id,
                value_as_private_key,
                sender_offset_key_id,
                txo_version,
                metadata_signature_message,
                range_proof_type,
            )
            .await
    }

    async fn get_one_sided_metadata_signature(
        &self,
        commitment_mask_key_id: &TariKeyId,
        value: MicroMinotari,
        sender_offset_key_id: &TariKeyId,
        txo_version: &TransactionOutputVersion,
        metadata_signature_message_common: &[u8; 32],
        range_proof_type: RangeProofType,
        script: &TariScript,
        receiver_address: &TariAddress,
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_one_sided_metadata_signature(
                commitment_mask_key_id,
                value,
                sender_offset_key_id,
                txo_version,
                metadata_signature_message_common,
                range_proof_type,
                script,
                receiver_address,
            )
            .await
    }

    async fn sign_script_message(
        &self,
        private_key_id: &TariKeyId,
        challenge: &[u8],
    ) -> Result<CompressedCheckSigSchnorrSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .sign_script_message(private_key_id, challenge)
            .await
    }

    async fn sign_script_message_with_spend_key(
        &self,
        message: &[u8],
        sender_offset_pub_key: Option<&CompressedPublicKey>,
    ) -> Result<CompressedCheckSigSchnorrSignature, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .sign_script_message_with_spend_key(message, sender_offset_pub_key)
            .await
    }

    async fn sign_with_nonce_and_challenge(
        &self,
        private_key_id: &TariKeyId,
        nonce: &TariKeyId,
        challenge: &[u8; 64],
    ) -> Result<CompressedSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .sign_with_nonce_and_challenge(private_key_id, nonce, challenge)
            .await
    }

    async fn get_receiver_partial_metadata_signature(
        &self,
        commitment_mask_key_id: &TariKeyId,
        value: &PrivateKey,
        sender_offset_public_key: &CompressedPublicKey,
        ephemeral_pubkey: &CompressedPublicKey,
        txo_version: &TransactionOutputVersion,
        metadata_signature_message: &[u8; 32],
        range_proof_type: RangeProofType,
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_receiver_partial_metadata_signature(
                commitment_mask_key_id,
                value,
                sender_offset_public_key,
                ephemeral_pubkey,
                txo_version,
                metadata_signature_message,
                range_proof_type,
            )
            .await
    }

    // In the case where the sender is an aggregated signer, we need to parse in the other public key shares, this is
    // done in: aggregated_sender_offset_public_keys and aggregated_ephemeral_public_keys. If there is no aggregated
    // signers, this can be left as none
    async fn get_sender_partial_metadata_signature(
        &self,
        ephemeral_private_nonce_id: &TariKeyId,
        sender_offset_key_id: &TariKeyId,
        commitment: &CompressedCommitment,
        ephemeral_commitment: &CompressedCommitment,
        txo_version: &TransactionOutputVersion,
        metadata_signature_message: &[u8; 32],
    ) -> Result<ComAndPubSignature, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_sender_partial_metadata_signature(
                ephemeral_private_nonce_id,
                sender_offset_key_id,
                commitment,
                ephemeral_commitment,
                txo_version,
                metadata_signature_message,
            )
            .await
    }

    async fn generate_burn_proof(
        &self,
        commitment_mask_key_id: &TariKeyId,
        amount: &PrivateKey,
        claim_public_key: &CompressedPublicKey,
    ) -> Result<RistrettoComSig, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .generate_burn_proof(commitment_mask_key_id, amount, claim_public_key)
            .await
    }

    async fn stealth_address_script_spending_key(
        &self,
        commitment_mask_key_id: &TariKeyId,
        spend_key: &CompressedPublicKey,
    ) -> Result<CompressedPublicKey, TransactionError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .stealth_address_script_spending_key(commitment_mask_key_id, spend_key)
            .await
    }

    async fn add_offset_to_spend_key(
        &self,
        spend_key_id: &TariKeyId,
        sender_offset_pub_key: &CompressedPublicKey,
    ) -> Result<TariKeyId, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .write()
            .await
            .add_offset_to_spend_key(spend_key_id, sender_offset_pub_key)
            .await
    }

    async fn encrypted_key(
        &self,
        key_id: &TariKeyId,
        encryption_key_id: Option<&TariKeyId>,
    ) -> Result<Vec<u8>, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .encrypted_key(key_id, encryption_key_id)
            .await
    }

    async fn import_encrypted_key(
        &self,
        encrypted: Vec<u8>,
        encryption_key_id: Option<&TariKeyId>,
    ) -> Result<TariKeyId, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .import_encrypted_key(encrypted, encryption_key_id)
            .await
    }
}

#[async_trait::async_trait]
impl<TBackend> SecretTransactionKeyManagerInterface for TransactionKeyManagerWrapper<TBackend>
where TBackend: TransactionKeyManagerBackend + 'static
{
    async fn get_private_key(&self, key_id: &TariKeyId) -> Result<PrivateKey, KeyManagerServiceError> {
        self.transaction_key_manager_inner
            .read()
            .await
            .get_private_key(key_id)
            .await
    }
}

impl<KM> Debug for TransactionKeyManagerWrapper<KM> {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Key Manager").finish()
    }
}

tari-project / tari / 17549972632

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous