mirror of
https://github.com/wownero/wownero.git
synced 2026-11-22 08:34:03 +01:00
+3









j-berman
jeffro256
Luke Parker
Lee *!* Clagett
SyntheticBird45
jeetrex17
UkoeHB
MrCyjaneK
tobtoht
selsta
Thomas
navidR
Boog900
a9145f9d38
Co-authored-by: jeffro256 <jeffro256@tutanota.com> Co-authored-by: Luke Parker <lukeparker5132@gmail.com> Co-authored-by: Lee *!* Clagett <code@leeclagett.com> Co-authored-by: SyntheticBird45 <someoneelse.is_on.github.rio7x@simplelogin.com> Co-authored-by: jeetrex17 <jeetrex@tutamail.com> Co-authored-by: UkoeHB <ukoehb@users.noreply.github.com> Co-authored-by: MrCyjaneK Co-authored-by: tobtoht Co-authored-by: selsta Co-authored-by: Thomas <thomas.giudici@proton.me> Co-authored-by: navidR Co-authored-by: Boog900 <boog900@tutanota.com>
228 lines
12 KiB
C++
228 lines
12 KiB
C++
// Copyright (c) 2025-2026, The Monero Project
|
|
//
|
|
// All rights reserved.
|
|
//
|
|
// 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.
|
|
|
|
/// @file Utilities for performing input selection on a set of input candidates
|
|
|
|
#pragma once
|
|
|
|
//local headers
|
|
#include "tx_proposal_utils.h"
|
|
|
|
//third party headers
|
|
|
|
//standard headers
|
|
#include <set>
|
|
|
|
//forward declarations
|
|
|
|
namespace carrot
|
|
{
|
|
/**
|
|
* @brief Candidate for input selection
|
|
*/
|
|
struct InputCandidate
|
|
{
|
|
CarrotSelectedInput core;
|
|
|
|
bool is_pre_carrot;
|
|
bool is_external;
|
|
uint64_t block_index;
|
|
};
|
|
|
|
namespace InputSelectionFlags
|
|
{
|
|
// Quantum forward secrecy (ON = unsafe)
|
|
static constexpr std::uint32_t ALLOW_EXTERNAL_INPUTS_IN_NORMAL_TRANSFERS = 1 << 0;
|
|
static constexpr std::uint32_t ALLOW_PRE_CARROT_INPUTS_IN_NORMAL_TRANSFERS = 1 << 1;
|
|
static constexpr std::uint32_t ALLOW_MIXED_INTERNAL_EXTERNAL = 1 << 2;
|
|
static constexpr std::uint32_t ALLOW_MIXED_CARROT_PRE_CARROT = 1 << 3;
|
|
|
|
// Amount handling
|
|
static constexpr std::uint32_t IS_KNOWN_FEE_SUBTRACTABLE = 1 << 4;
|
|
static constexpr std::uint32_t ALLOW_DUST = 1 << 5;
|
|
}
|
|
|
|
/**
|
|
* @brief A functor type which implements N-input selection on a subset of candidates
|
|
* @param input_candidates -
|
|
* @param selectable_input_indices subset of indices in `input_candidates` allowed to select from
|
|
* @param n_inputs exact number of selected inputs should return
|
|
* @param required_money sum of amounts of selected inputs should be greater than or equal to this value
|
|
* @param[out] selected_inputs_indices_out `n_inputs` subset of `selectable_input_indices`, of selected input indices
|
|
*
|
|
* To signify selection failure, `selected_inputs_indices_out` should be empty after end of call.
|
|
*/
|
|
using input_selection_policy_t = std::function<void(
|
|
epee::span<const InputCandidate> input_candidates,
|
|
const std::set<std::size_t> &selectable_input_indices,
|
|
std::size_t n_inputs,
|
|
const boost::multiprecision::uint128_t &required_money,
|
|
std::set<std::size_t> &selected_inputs_indices_out
|
|
)>;
|
|
|
|
/**
|
|
* @brief Get optimal number of inputs to maximum money minus fees
|
|
* @param user_amount_begin xmr_amount LegacyForwardIterator to beginning of user-defined amounts container
|
|
* @param user_amount_end xmr_amount LegacyForwardIterator to end of user-defined amounts container
|
|
* @param max_num_input_count maximum number of inputs
|
|
* @param fee_by_input_count fee indexed by number of inputs
|
|
* @return (N, X) where the X is the sum of the greatest N <= max_num_input_count amounts,
|
|
* maximizing X - F(N). F(N) is the fee for this transaction, given input count N
|
|
*
|
|
* This should correctly handle "almost-dust": inputs which are less than the fee, but greater than
|
|
* or equal to the difference of the fee compared to excluding that input, even if less than the
|
|
* difference of the fee compared to excluding that input plus more inputs. If this function returns
|
|
* N == 0, then there aren't enough usable funds, i.e. no N exists such that X - F(N) > 0.
|
|
*/
|
|
template <class AmountFwdIt>
|
|
std::pair<std::size_t, boost::multiprecision::uint128_t> get_input_count_for_max_usable_money(
|
|
AmountFwdIt user_amount_begin,
|
|
const AmountFwdIt &user_amount_end,
|
|
const std::size_t max_num_input_count,
|
|
const std::map<std::size_t, xmr_amount> &fee_by_input_count);
|
|
/**
|
|
* @brief Compare two input candidates who share a OTA; we can only choose one!
|
|
* @param lhs -
|
|
* @param rhs -
|
|
* @return 1 if lhs is better, -1 if rhs is better, 0 if neutral
|
|
* @throw component_out_of_order - iff rhs.core.key_image != lhs.core.key_image
|
|
*
|
|
* The better candidate is determined by criteria in descending order of importance as follows:
|
|
* 1. Amount (higher is better, duh)
|
|
* 2. Age (older is better for protection against double spend attacks)
|
|
* 3. Is pre-Carrot enote? (`false` is better for quantum forward-secrecy)
|
|
* 4. Is external enote? (`false` is better for quantum forward-secrecy)
|
|
*/
|
|
int compare_input_candidate_same_ota(const InputCandidate &lhs, const InputCandidate &rhs);
|
|
/**
|
|
* @brief Form subsets of input candidates to try selection in preferred order
|
|
* @param input_candidates - slice to user-provided input candidates
|
|
* @param flags - see InputSelectionFlags namespace
|
|
* @param is_normal_transfer - true iff num normal non-dummy payments in tx to perform selection for is >= 1
|
|
* @return ordered list of subsets (represented by 0-based indices) of input_candidates to try selection on
|
|
*
|
|
* This function also performs a burning bug check; no indices returned in any subset will reference
|
|
* an input candidate when another input candidate shares the same key image but is "better" as
|
|
* determined by compare_input_candidate_same_ki.
|
|
*
|
|
* Purpose: Mainly due to quantum forward secrecy properties of spending different types of Monero
|
|
* enotes, it isn't always preferable to be able to select all usable input candidates together in
|
|
* the same transaction. For example, spending internal Carrot enotes is always quantum forward
|
|
* secret, even when one's public Monero address is known. By contrast, spending a pre-Carrot enote
|
|
* is never quantum forward secret, even with no public address knowledge. As such, a spender should
|
|
* prefer not to spend these enotes in the same transaction, since the pre-Carrot enote will "taint"
|
|
* the quantum forward spending secrecy of the internal Carrot enote. Based on certain heuristics
|
|
* and user-provided flags, this function creates a list of subsets of input_candidates, in
|
|
* preferred order, to perform input selection on.
|
|
*
|
|
* Flags:
|
|
* * ALLOW_EXTERNAL_INPUTS_IN_NORMAL_TRANSFERS - external inputs in normal txs are allowed iff=1
|
|
* * ALLOW_PRE_CARROT_INPUTS_IN_NORMAL_TRANSFERS - pre-carrot inputs in normal txs are allowed iff=1
|
|
* * ALLOW_MIXED_INTERNAL_EXTERNAL - mixing internal/external inputs in any txs is allowed iff=1
|
|
* * ALLOW_MIXED_CARROT_PRE_CARROT - mixing pre-carrot/carrot inputs in any txs is allowed iff=1
|
|
*
|
|
* General rules (not in any specific order):
|
|
* * It should be preferred NOT to use external inputs in normal transfers
|
|
* * It should be preferred NOT to use pre-carrot inputs in normal transfers
|
|
* * It should be preferred NOT to mix internal/external inputs
|
|
* * It should be preferred NOT to mix pre-carrot/carrot inputs
|
|
* * It should be preferred YES to use external & pre-carrots inputs in self-send transactions
|
|
*
|
|
* In scenarios where a user-provided flag allows a non-preferred subset of input candidates, this
|
|
* function will FIRST add the subset of input candidates as if the user didn't provide that
|
|
* flag, and THEN add the non-preferred subset. For example, let's say that you pass input
|
|
* candidates span {A, B}, flags=ALLOW_EXTERNAL_INPUTS_IN_NORMAL_TRANSFERS, and
|
|
* is_normal_transfer=true. In this example, A is internal and B is external. The return
|
|
* value of this function will be {{0}, {1}, {0, 1}}. This means: "try input selection on 0 (A)
|
|
* first, then 1 (B), and then both {0, 1} (A & B)". In this example, although external inputs are
|
|
* *allowed* in normal transfers by the flag provided by the user, they are not *preferred*, so
|
|
* {A} comes before {B} in the subset list. Mixing is the least preferred, so {A, B} is the last
|
|
* subset.
|
|
*
|
|
* If unsure which flags to use, flags=0 is the "safest" option for input selection. Note that this
|
|
* completely disallows normal transfers for legacy key hierarchies, since inputs will never be
|
|
* internal due to the lack of the view-balance secret s_vb in legacy key hierarchies.
|
|
*/
|
|
std::vector<std::set<std::size_t>> form_preferred_input_candidate_subsets(
|
|
const epee::span<const InputCandidate> input_candidates,
|
|
const std::uint32_t flags,
|
|
const bool is_normal_transfer);
|
|
/**
|
|
* @brief Return list of tx input counts in order that we should prefer to select
|
|
* @param max_n_inputs maximum number of inputs to use in selection, set 0 to to use consensus limit
|
|
* @return list of tx input counts, in order of preference for this tx
|
|
*
|
|
* Transaction input counts are trivially observable on-chain, so picking a wrong input count when
|
|
* given the chance between multiple choices can have privacy consequences. The purpose of this
|
|
* function is to determine the order in which we should try to select a certain number of inputs.
|
|
* Calls to this function are not necessarily idempotent: the order may be random.
|
|
*/
|
|
std::vector<std::size_t> get_input_counts_in_preferred_order(std::size_t max_n_inputs);
|
|
/**
|
|
* @brief A customizable input selector for single (i.e. not batched) transfers
|
|
* @param input_candidates -
|
|
* @param policies slice of ISPs to attempt selection on, in order of user's preference
|
|
* @param flags see InputSelectionFlags namespace
|
|
* @param max_n_inputs - the maximum number of inputs to allow
|
|
* @param[out] selected_input_indices_out selected indices into `input_candidates` (optional)
|
|
* @return input selector functor
|
|
*
|
|
* The returned input selector considers provided input candidates, and creates subsets of the
|
|
* candidates as according to `form_preferred_input_candidate_subsets`. Then, in the order of input
|
|
* counts as according to `get_input_counts_in_preferred_order`, finds the first pair (subset, input
|
|
* count) that contains enough "usable" money: a sum of money great enough to pay the nominal output
|
|
* sum, plus any required fees as according to the input count. Once that is found, ISPs are
|
|
* dispatched in provided user order until one succeeds. If none succeed for that pair, then the
|
|
* whole of input selection fails, we do not move onto the next (subset, input count) pair.
|
|
*
|
|
* SAFETY: The lifetime of objects referenced by `input_candidates` and `selected_input_indices_out`
|
|
* (if not null) must be valid at least as long as as the last call to the returned functor.
|
|
*/
|
|
select_inputs_func_t make_single_transfer_input_selector(
|
|
const epee::span<const InputCandidate> input_candidates,
|
|
const epee::span<const input_selection_policy_t> policies,
|
|
const std::uint32_t flags,
|
|
const std::size_t max_n_inputs,
|
|
std::set<size_t> *selected_input_indices_out);
|
|
|
|
namespace ispolicy
|
|
{
|
|
/**
|
|
* @brief An input selection policy which generally attempts to select old outputs, but isn't necessarily optimal
|
|
*/
|
|
void select_greedy_aging(const epee::span<const InputCandidate>,
|
|
const std::set<std::size_t>&,
|
|
std::size_t,
|
|
const boost::multiprecision::uint128_t&,
|
|
std::set<std::size_t>&);
|
|
|
|
} //namespace ispolicy
|
|
} //namespace carrot
|
|
|
|
#include "input_selection.inl"
|