Skip to content

src: Doxygen-ify misc FCMP++ docstrings #448

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeffro256 wants to merge 1 commit into
base: fcmp++-stage
Choose a base branch
from
Open

src: Doxygen-ify misc FCMP++ docstrings #448

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions src/fcmp_pp/fcmp_pp_rust/fcmp++.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,13 +282,13 @@ int fcmp_pp_prove_input_new(const struct PathUnsafe *path,
void destroy_fcmp_pp_prove_input(struct FcmpPpProveMembershipInputUnsafe *fcmp_pp_prove_input);

/**
* brief: fcmp_pp_prove_sal - Make a FCMP++ spend auth & linkability proof
* param: signable_tx_hash - message to sign
* param: x - ed25519 scalar s.t. O~ = x G + y T
* param: y - ed25519 scalar s.t. O~ = x G + y T
* param: rerandomized_output - used for input tuple, r_i, and r_r_i
* outparam: sal_proof_out - a buffer of size FCMP_PP_SAL_PROOF_SIZE_V1 where resultant SAL proof is stored
* return: 0 on success, a negative value on failure
* @brief Make a FCMP++ spend auth & linkability proof
* @param signable_tx_hash message to sign
* @param x ed25519 scalar s.t. O~ = x G + y T
* @param y ed25519 scalar s.t. O~ = x G + y T
* @param rerandomized_output used for input tuple, r_i, and r_r_i
* @param[out] sal_proof_out a buffer of size FCMP_PP_SAL_PROOF_SIZE_V1 where resultant SAL proof is stored
* @return 0 on success, a negative value on failure
*
* note: This call can technically be stripped down even more because `rerandomized_output` contains
* more information than we need: we can discard r_o and r_c. However, in practice, these
Expand All @@ -303,12 +303,12 @@ int fcmp_pp_prove_sal(const uint8_t signable_tx_hash[32],
uint8_t key_image_out[32]);

/**
* brief: fcmp_pp_prove_membership - Make a FCMP++ membership proof for N inputs
* param: inputs - a slice of FCMP provable inputs returned from fcmp_pp_prove_input_new()
* param: n_tree_layers -
* param: proof_len -
* outparam: fcmp_proof_out - a buffer where the FCMP proof will be written to
* return: an error on failure, nothing otherwise
* @brief Make a FCMP++ membership proof for N inputs
* @param inputs a slice of FCMP provable inputs returned from fcmp_pp_prove_input_new()
* @param n_tree_layers -
* @param proof_len -
* @param[out] fcmp_proof_out a buffer where the FCMP proof will be written to
* @return an error on failure, nothing otherwise
*/
int fcmp_pp_prove_membership(const struct FcmpPpProveMembershipInputSliceUnsafe fcmp_pp_prove_inputs,
uintptr_t n_tree_layers,
Expand All @@ -331,25 +331,25 @@ int fcmp_pp_verify_input_new(const uint8_t *signable_tx_hash,
void destroy_fcmp_pp_verify_input(struct FcmpPpVerifyInputUnsafe *fcmp_pp_verify_input);

/**
* brief: fcmp_pp_verify_sal - Verify a FCMP++ spend auth & linkability proof
* param: signable_tx_hash - message to verify
* param: input - (O~, I~, C~, R) tuple
* param: L - L = x Hp(O), AKA key image
* param: sal_proof - SAL proof to verify
* return: true on verification success, false otherwise
* @brief Verify a FCMP++ spend auth & linkability proof
* @param signable_tx_hash message to verify
* @param input (O~, I~, C~, R) tuple
* @param L L = x Hp(O), AKA key image
* @param sal_proof SAL proof to verify
* @return true on verification success, false otherwise
*/
bool fcmp_pp_verify_sal(const uint8_t signable_tx_hash[32],
const struct FcmpInputCompressed *input,
const uint8_t L[32],
const uint8_t sal_proof[FCMP_PP_SAL_PROOF_SIZE_V1]);
/**
* brief: fcmp_pp_verify_membership - Verify a FCMP++ membership proof
* param: inputs - a slice of fcmp_input_ref pointers
* param: tree_root -
* param: n_tree_layers -
* param: fcmp_proof - FCMP proof bytes to verify
* param: fcmp_proof_len - length of fcmp_proof buffer
* return: true on verification success, false otherwise
* @brief Verify a FCMP++ membership proof
* @param inputs a slice of fcmp_input_ref pointers
* @param tree_root -
* @param n_tree_layers -
* @param fcmp_proof FCMP proof bytes to verify
* @param fcmp_proof_len length of fcmp_proof buffer
* @return true on verification success, false otherwise
*/
bool fcmp_pp_verify_membership(struct InputSlice inputs,
const struct TreeRootUnsafe *tree_root,
Expand Down
2 changes: 1 addition & 1 deletion src/wallet/hot_cold.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright (c) 2025, The Monero Project
// Copyright (c) 2025-2026, The Monero Project
//
// All rights reserved.
//
Expand Down
67 changes: 32 additions & 35 deletions src/wallet/scanning_tools.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,10 @@
#include "crypto/crypto.h"
#include "cryptonote_basic/blobdatatype.h"
#include "cryptonote_basic/cryptonote_basic.h"
#include "cryptonote_basic/subaddress_index.h"
#include "cryptonote_basic/tx_extra.h"

//third party headers

//standard headers
#include <unordered_map>
#include <optional>
#include <vector>

Expand Down Expand Up @@ -99,15 +96,15 @@ using MoneroEnoteVariant = std::variant<PreCarrotEnote,
carrot::CarrotEnoteV1>;

/**
* brief: do a view-incoming scan as receiver on an enote given the tx prefix and amount commitment opening
* param: tx_prefix -
* param: amount - a
* param: amount_blinding_factor - k_a
* param: local_output_index - i
* param: k_view_incoming_dev - k_v
* param: main_address_spend_pubkeys - [K_s, ...]
* param: subaddress_map -
* return: std::nullopt if scan failed, otherwise enote scan info on success
* @brief Do a view-incoming scan as receiver on an enote given the tx prefix and amount commitment opening
* @param tx_prefix -
* @param amount a
* @param amount_blinding_factor k_a
* @param local_output_index i
* @param k_view_incoming_dev k_v
* @param main_address_spend_pubkeys [K_s, ...]
* @param subaddress_map -
* @return std::nullopt if scan failed, otherwise enote scan info on success
*/
std::optional<enote_view_incoming_scan_info_t> view_incoming_scan_enote_from_prefix(
const cryptonote::transaction_prefix &tx_prefix,
Expand All @@ -119,17 +116,17 @@ std::optional<enote_view_incoming_scan_info_t> view_incoming_scan_enote_from_pre
const carrot::subaddress_map &subaddress_map);

/**
* brief: do a view-incoming scan as receiver on all enotes in a full tx
* param: tx -
* param: main_tx_ephemeral_pubkeys - parsed main ephemeral pubkeys in `tx`
* param: additional_tx_ephemeral_pubkeys - parsed additional ephemeral pubkeys in `tx`
* param: tx_extra_nonce - parsed tx extra nonce field in `tx`
* param: main_derivations - sender-receiver ECDHs against main ephemeral pubkeys
* param: additional_derivations - sender-receiver ECDHs against additional ephemeral pubkeys
* param: k_view_incoming_dev - device for k_v
* param: main_address_spend_pubkeys - [K_s, ...]
* param: subaddress_map -
* outparam: enote_scan_infos_out - mutable span to enote scan infos of size N, where N is number of `tx`'s outputs
* @brief Do a view-incoming scan as receiver on all enotes in a full tx
* @param tx -
* @param main_tx_ephemeral_pubkeys parsed main ephemeral pubkeys in `tx`
* @param additional_tx_ephemeral_pubkeys parsed additional ephemeral pubkeys in `tx`
* @param tx_extra_nonce parsed tx extra nonce field in `tx`
* @param main_derivations sender-receiver ECDHs against main ephemeral pubkeys
* @param additional_derivations sender-receiver ECDHs against additional ephemeral pubkeys
* @param k_view_incoming_dev device for k_v
* @param main_address_spend_pubkeys [K_s, ...]
* @param subaddress_map -
* @param[out] enote_scan_infos_out - mutable span to enote scan infos of size N, where N is number of `tx`'s outputs
*/
void view_incoming_scan_transaction(
const cryptonote::transaction &tx,
Expand All @@ -155,13 +152,13 @@ std::vector<std::optional<enote_view_incoming_scan_info_t>> view_incoming_scan_t
const carrot::subaddress_map &subaddress_map);

/**
* brief: do a view-incoming scan as sender on all enotes in a full tx
* param: tx -
* param: tx_extra_nonce - parsed tx extra nonce field in `tx`
* param: custom_main_derivations - sender-receiver ECDHs against main ephemeral pubkeys
* param: custom_additional_derivations - sender-receiver ECDHs against additional ephemeral pubkeys
* param: address - (K^j_s, K^j_v) of recipient to scan for
* return: list of enote scan infos of size N, where N is number of `tx`'s outputs
* @brief Do a view-incoming scan as sender on all enotes in a full tx
* @param tx -
* @param tx_extra_nonce parsed tx extra nonce field in `tx`
* @param custom_main_derivations sender-receiver ECDHs against main ephemeral pubkeys
* @param custom_additional_derivations sender-receiver ECDHs against additional ephemeral pubkeys
* @param address (K^j_s, K^j_v) of recipient to scan for
* @return: list of enote scan infos of size N, where N is number of `tx`'s outputs
*/
std::vector<std::optional<enote_view_incoming_scan_info_t>> view_incoming_scan_transaction_as_sender(
const cryptonote::transaction &tx,
Expand All @@ -170,15 +167,15 @@ std::vector<std::optional<enote_view_incoming_scan_info_t>> view_incoming_scan_t
const cryptonote::account_public_address &address);

/**
* brief: return true iff `pid` is "long" payment ID (greater than 8 bytes)
* @brief Return true iff `pid` is "long" payment ID (greater than 8 bytes)
*/
bool is_long_payment_id(const crypto::hash &pid);

/**
* brief: try deriving a scanned enote's key image with our key image device
* param: enote_scan_info -
* param: key_image_dev - device for k_s (legacy-derived) or k_gi (Carrot-derived)
* return: std::nullopt on derive failure, otherwise the key image for the one-time address of scanned enote
* @brief Try deriving a scanned enote's key image with our key image device
* @param enote_scan_info -
* @param key_image_dev device for k_s (legacy-derived) or k_gi (Carrot-derived)
* @return std::nullopt on derive failure, otherwise the key image for the one-time address of scanned enote
*/
std::optional<crypto::key_image> try_derive_enote_key_image(
const enote_view_incoming_scan_info_t &enote_scan_info,
Expand Down
Loading
Loading