monero_rpc/

lib.rs

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![doc = include_str!("../README.md")]
#![deny(missing_docs)]
#![cfg_attr(not(feature = "std"), no_std)]

use core::{
  future::Future,
  fmt::Debug,
  ops::{Bound, RangeBounds},
};
use std_shims::{
  alloc::format,
  vec,
  vec::Vec,
  io,
  string::{String, ToString},
};

use zeroize::Zeroize;

use curve25519_dalek::edwards::{CompressedEdwardsY, EdwardsPoint};

use serde::{Serialize, Deserialize, de::DeserializeOwned};
use serde_json::{Value, json};

use monero_serai::{
  io::*,
  transaction::{Input, Timelock, Pruned, Transaction},
  block::Block,
  DEFAULT_LOCK_WINDOW,
};
use monero_address::Address;

// Number of blocks the fee estimate will be valid for
// https://github.com/monero-project/monero/blob/94e67bf96bbc010241f29ada6abc89f49a81759c
//   /src/wallet/wallet2.cpp#L121
const GRACE_BLOCKS_FOR_FEE_ESTIMATE: u64 = 10;

// Monero errors if more than 100 is requested unless using a non-restricted RPC
// https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454
//   /src/rpc/core_rpc_server.cpp#L75
const TXS_PER_REQUEST: usize = 100;

/// An error from the RPC.
#[derive(Clone, PartialEq, Eq, Debug)]
#[cfg_attr(feature = "std", derive(thiserror::Error))]
pub enum RpcError {
  /// An internal error.
  #[cfg_attr(feature = "std", error("internal error ({0})"))]
  InternalError(String),
  /// A connection error with the node.
  #[cfg_attr(feature = "std", error("connection error ({0})"))]
  ConnectionError(String),
  /// The node is invalid per the expected protocol.
  #[cfg_attr(feature = "std", error("invalid node ({0})"))]
  InvalidNode(String),
  /// Requested transactions weren't found.
  #[cfg_attr(feature = "std", error("transactions not found"))]
  TransactionsNotFound(Vec<[u8; 32]>),
  /// The transaction was pruned.
  ///
  /// Pruned transactions are not supported at this time.
  #[cfg_attr(feature = "std", error("pruned transaction"))]
  PrunedTransaction,
  /// A transaction (sent or received) was invalid.
  #[cfg_attr(feature = "std", error("invalid transaction ({0:?})"))]
  InvalidTransaction([u8; 32]),
  /// The returned fee was unusable.
  #[cfg_attr(feature = "std", error("unexpected fee response"))]
  InvalidFee,
  /// The priority intended for use wasn't usable.
  #[cfg_attr(feature = "std", error("invalid priority"))]
  InvalidPriority,
}

/// A block which is able to be scanned.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct ScannableBlock {
  /// The block which is being scanned.
  pub block: Block,
  /// The non-miner transactions within this block.
  pub transactions: Vec<Transaction<Pruned>>,
  /// The output index for the first RingCT output within this block.
  ///
  /// None if there are no RingCT outputs within this block, Some otherwise.
  pub output_index_for_first_ringct_output: Option<u64>,
}

/// A struct containing a fee rate.
///
/// The fee rate is defined as a per-weight cost, along with a mask for rounding purposes.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Zeroize)]
pub struct FeeRate {
  /// The fee per-weight of the transaction.
  per_weight: u64,
  /// The mask to round with.
  mask: u64,
}

impl FeeRate {
  /// Construct a new fee rate.
  pub fn new(per_weight: u64, mask: u64) -> Result<FeeRate, RpcError> {
    if (per_weight == 0) || (mask == 0) {
      Err(RpcError::InvalidFee)?;
    }
    Ok(FeeRate { per_weight, mask })
  }

  /// Write the FeeRate.
  ///
  /// This is not a Monero protocol defined struct, and this is accordingly not a Monero protocol
  /// defined serialization.
  pub fn write(&self, w: &mut impl io::Write) -> io::Result<()> {
    w.write_all(&self.per_weight.to_le_bytes())?;
    w.write_all(&self.mask.to_le_bytes())
  }

  /// Serialize the FeeRate to a `Vec<u8>`.
  ///
  /// This is not a Monero protocol defined struct, and this is accordingly not a Monero protocol
  /// defined serialization.
  pub fn serialize(&self) -> Vec<u8> {
    let mut res = Vec::with_capacity(16);
    self.write(&mut res).unwrap();
    res
  }

  /// Read a FeeRate.
  ///
  /// This is not a Monero protocol defined struct, and this is accordingly not a Monero protocol
  /// defined serialization.
  pub fn read(r: &mut impl io::Read) -> io::Result<FeeRate> {
    let per_weight = read_u64(r)?;
    let mask = read_u64(r)?;
    FeeRate::new(per_weight, mask).map_err(io::Error::other)
  }

  /// Calculate the fee to use from the weight.
  ///
  /// This function may panic upon overflow.
  pub fn calculate_fee_from_weight(&self, weight: usize) -> u64 {
    let fee = self.per_weight * u64::try_from(weight).unwrap();
    let fee = fee.div_ceil(self.mask) * self.mask;
    debug_assert_eq!(weight, self.calculate_weight_from_fee(fee), "Miscalculated weight from fee");
    fee
  }

  /// Calculate the weight from the fee.
  pub fn calculate_weight_from_fee(&self, fee: u64) -> usize {
    usize::try_from(fee / self.per_weight).unwrap()
  }
}

/// The priority for the fee.
///
/// Higher-priority transactions will be included in blocks earlier.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[allow(non_camel_case_types)]
pub enum FeePriority {
  /// The `Unimportant` priority, as defined by Monero.
  Unimportant,
  /// The `Normal` priority, as defined by Monero.
  Normal,
  /// The `Elevated` priority, as defined by Monero.
  Elevated,
  /// The `Priority` priority, as defined by Monero.
  Priority,
  /// A custom priority.
  Custom {
    /// The numeric representation of the priority, as used within the RPC.
    priority: u32,
  },
}

/// https://github.com/monero-project/monero/blob/ac02af92867590ca80b2779a7bbeafa99ff94dcb/
///   src/simplewallet/simplewallet.cpp#L161
impl FeePriority {
  pub(crate) fn fee_priority(&self) -> u32 {
    match self {
      FeePriority::Unimportant => 1,
      FeePriority::Normal => 2,
      FeePriority::Elevated => 3,
      FeePriority::Priority => 4,
      FeePriority::Custom { priority, .. } => *priority,
    }
  }
}

#[derive(Debug, Deserialize)]
struct JsonRpcResponse<T> {
  result: T,
}

#[derive(Debug, Deserialize)]
struct TransactionResponse {
  tx_hash: String,
  as_hex: String,
  pruned_as_hex: String,
}
#[derive(Debug, Deserialize)]
struct TransactionsResponse {
  #[serde(default)]
  missed_tx: Vec<String>,
  txs: Vec<TransactionResponse>,
}

/// The response to an query for the information of a RingCT output.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct OutputInformation {
  /// The block number of the block this output was added to the chain in.
  ///
  /// This is equivalent to he height of the blockchain at the time the block was added.
  pub height: usize,
  /// If the output is unlocked, per the node's local view.
  pub unlocked: bool,
  /// The output's key.
  ///
  /// This is a CompressedEdwardsY, not an EdwardsPoint, as it may be invalid. CompressedEdwardsY
  /// only asserts validity on decompression and allows representing compressed types.
  pub key: CompressedEdwardsY,
  /// The output's commitment.
  pub commitment: EdwardsPoint,
  /// The transaction which created this output.
  pub transaction: [u8; 32],
}

fn rpc_hex(value: &str) -> Result<Vec<u8>, RpcError> {
  hex::decode(value).map_err(|_| RpcError::InvalidNode("expected hex wasn't hex".to_string()))
}

fn hash_hex(hash: &str) -> Result<[u8; 32], RpcError> {
  rpc_hex(hash)?.try_into().map_err(|_| RpcError::InvalidNode("hash wasn't 32-bytes".to_string()))
}

fn rpc_point(point: &str) -> Result<EdwardsPoint, RpcError> {
  decompress_point(
    rpc_hex(point)?
      .try_into()
      .map_err(|_| RpcError::InvalidNode(format!("invalid point: {point}")))?,
  )
  .ok_or_else(|| RpcError::InvalidNode(format!("invalid point: {point}")))
}

/// An RPC connection to a Monero daemon.
///
/// This is abstract such that users can use an HTTP library (which being their choice), a
/// Tor/i2p-based transport, or even a memory buffer an external service somehow routes.
///
/// While no implementors are directly provided, [monero-simple-request-rpc](
///   https://github.com/serai-dex/serai/tree/develop/networks/monero/rpc/simple-request
/// ) is recommended.
pub trait Rpc: Sync + Clone {
  /// Perform a POST request to the specified route with the specified body.
  ///
  /// The implementor is left to handle anything such as authentication.
  fn post(
    &self,
    route: &str,
    body: Vec<u8>,
  ) -> impl Send + Future<Output = Result<Vec<u8>, RpcError>>;

  /// Perform a RPC call to the specified route with the provided parameters.
  ///
  /// This is NOT a JSON-RPC call. They use a route of "json_rpc" and are available via
  /// `json_rpc_call`.
  fn rpc_call<Params: Send + Serialize + Debug, Response: DeserializeOwned + Debug>(
    &self,
    route: &str,
    params: Option<Params>,
  ) -> impl Send + Future<Output = Result<Response, RpcError>> {
    async move {
      let res = self
        .post(
          route,
          if let Some(params) = params {
            serde_json::to_string(&params).unwrap().into_bytes()
          } else {
            vec![]
          },
        )
        .await?;
      let res_str = std_shims::str::from_utf8(&res)
        .map_err(|_| RpcError::InvalidNode("response wasn't utf-8".to_string()))?;
      serde_json::from_str(res_str)
        .map_err(|_| RpcError::InvalidNode(format!("response wasn't the expected json: {res_str}")))
    }
  }

  /// Perform a JSON-RPC call with the specified method with the provided parameters.
  fn json_rpc_call<Response: DeserializeOwned + Debug>(
    &self,
    method: &str,
    params: Option<Value>,
  ) -> impl Send + Future<Output = Result<Response, RpcError>> {
    async move {
      let mut req = json!({ "method": method });
      if let Some(params) = params {
        req.as_object_mut().unwrap().insert("params".into(), params);
      }
      Ok(self.rpc_call::<_, JsonRpcResponse<Response>>("json_rpc", Some(req)).await?.result)
    }
  }

  /// Perform a binary call to the specified route with the provided parameters.
  fn bin_call(
    &self,
    route: &str,
    params: Vec<u8>,
  ) -> impl Send + Future<Output = Result<Vec<u8>, RpcError>> {
    async move { self.post(route, params).await }
  }

  /// Get the active blockchain protocol version.
  ///
  /// This is specifically the major version within the most recent block header.
  fn get_hardfork_version(&self) -> impl Send + Future<Output = Result<u8, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct HeaderResponse {
        major_version: u8,
      }

      #[derive(Debug, Deserialize)]
      struct LastHeaderResponse {
        block_header: HeaderResponse,
      }

      Ok(
        self
          .json_rpc_call::<LastHeaderResponse>("get_last_block_header", None)
          .await?
          .block_header
          .major_version,
      )
    }
  }

  /// Get the height of the Monero blockchain.
  ///
  /// The height is defined as the amount of blocks on the blockchain. For a blockchain with only
  /// its genesis block, the height will be 1.
  fn get_height(&self) -> impl Send + Future<Output = Result<usize, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct HeightResponse {
        height: usize,
      }
      let res = self.rpc_call::<Option<()>, HeightResponse>("get_height", None).await?.height;
      if res == 0 {
        Err(RpcError::InvalidNode("node responded with 0 for the height".to_string()))?;
      }
      Ok(res)
    }
  }

  /// Get the specified transactions.
  ///
  /// The received transactions will be hashed in order to verify the correct transactions were
  /// returned.
  fn get_transactions(
    &self,
    hashes: &[[u8; 32]],
  ) -> impl Send + Future<Output = Result<Vec<Transaction>, RpcError>> {
    async move {
      if hashes.is_empty() {
        return Ok(vec![]);
      }

      let mut hashes_hex = hashes.iter().map(hex::encode).collect::<Vec<_>>();
      let mut all_txs = Vec::with_capacity(hashes.len());
      while !hashes_hex.is_empty() {
        let this_count = TXS_PER_REQUEST.min(hashes_hex.len());

        let txs: TransactionsResponse = self
          .rpc_call(
            "get_transactions",
            Some(json!({
              "txs_hashes": hashes_hex.drain(.. this_count).collect::<Vec<_>>(),
            })),
          )
          .await?;

        if !txs.missed_tx.is_empty() {
          Err(RpcError::TransactionsNotFound(
            txs.missed_tx.iter().map(|hash| hash_hex(hash)).collect::<Result<_, _>>()?,
          ))?;
        }

        all_txs.extend(txs.txs);
      }

      all_txs
        .iter()
        .enumerate()
        .map(|(i, res)| {
          // https://github.com/monero-project/monero/issues/8311
          let buf = rpc_hex(if !res.as_hex.is_empty() { &res.as_hex } else { &res.pruned_as_hex })?;
          let mut buf = buf.as_slice();
          let tx = Transaction::read(&mut buf).map_err(|_| match hash_hex(&res.tx_hash) {
            Ok(hash) => RpcError::InvalidTransaction(hash),
            Err(err) => err,
          })?;
          if !buf.is_empty() {
            Err(RpcError::InvalidNode("transaction had extra bytes after it".to_string()))?;
          }

          // We check this to ensure we didn't read a pruned transaction when we meant to read an
          // actual transaction. That shouldn't be possible, as they have different serializations,
          // yet it helps to ensure that if we applied the above exception (using the pruned data),
          // it was for the right reason
          if res.as_hex.is_empty() {
            match tx.prefix().inputs.first() {
              Some(Input::Gen { .. }) => (),
              _ => Err(RpcError::PrunedTransaction)?,
            }
          }

          // This does run a few keccak256 hashes, which is pointless if the node is trusted
          // In exchange, this provides resilience against invalid/malicious nodes
          if tx.hash() != hashes[i] {
            Err(RpcError::InvalidNode(
              "replied with transaction wasn't the requested transaction".to_string(),
            ))?;
          }

          Ok(tx)
        })
        .collect()
    }
  }

  /// Get the specified transactions in their pruned format.
  fn get_pruned_transactions(
    &self,
    hashes: &[[u8; 32]],
  ) -> impl Send + Future<Output = Result<Vec<Transaction<Pruned>>, RpcError>> {
    async move {
      if hashes.is_empty() {
        return Ok(vec![]);
      }

      let mut hashes_hex = hashes.iter().map(hex::encode).collect::<Vec<_>>();
      let mut all_txs = Vec::with_capacity(hashes.len());
      while !hashes_hex.is_empty() {
        let this_count = TXS_PER_REQUEST.min(hashes_hex.len());

        let txs: TransactionsResponse = self
          .rpc_call(
            "get_transactions",
            Some(json!({
              "txs_hashes": hashes_hex.drain(.. this_count).collect::<Vec<_>>(),
              "prune": true,
            })),
          )
          .await?;

        if !txs.missed_tx.is_empty() {
          Err(RpcError::TransactionsNotFound(
            txs.missed_tx.iter().map(|hash| hash_hex(hash)).collect::<Result<_, _>>()?,
          ))?;
        }

        all_txs.extend(txs.txs);
      }

      all_txs
        .iter()
        .map(|res| {
          let buf = rpc_hex(&res.pruned_as_hex)?;
          let mut buf = buf.as_slice();
          let tx =
            Transaction::<Pruned>::read(&mut buf).map_err(|_| match hash_hex(&res.tx_hash) {
              Ok(hash) => RpcError::InvalidTransaction(hash),
              Err(err) => err,
            })?;
          if !buf.is_empty() {
            Err(RpcError::InvalidNode("pruned transaction had extra bytes after it".to_string()))?;
          }
          Ok(tx)
        })
        .collect()
    }
  }

  /// Get the specified transaction.
  ///
  /// The received transaction will be hashed in order to verify the correct transaction was
  /// returned.
  fn get_transaction(
    &self,
    tx: [u8; 32],
  ) -> impl Send + Future<Output = Result<Transaction, RpcError>> {
    async move { self.get_transactions(&[tx]).await.map(|mut txs| txs.swap_remove(0)) }
  }

  /// Get the specified transaction in its pruned format.
  fn get_pruned_transaction(
    &self,
    tx: [u8; 32],
  ) -> impl Send + Future<Output = Result<Transaction<Pruned>, RpcError>> {
    async move { self.get_pruned_transactions(&[tx]).await.map(|mut txs| txs.swap_remove(0)) }
  }

  /// Get the hash of a block from the node.
  ///
  /// `number` is the block's zero-indexed position on the blockchain (`0` for the genesis block,
  /// `height - 1` for the latest block).
  fn get_block_hash(
    &self,
    number: usize,
  ) -> impl Send + Future<Output = Result<[u8; 32], RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct BlockHeaderResponse {
        hash: String,
      }
      #[derive(Debug, Deserialize)]
      struct BlockHeaderByHeightResponse {
        block_header: BlockHeaderResponse,
      }

      let header: BlockHeaderByHeightResponse =
        self.json_rpc_call("get_block_header_by_height", Some(json!({ "height": number }))).await?;
      hash_hex(&header.block_header.hash)
    }
  }

  /// Get a block from the node by its hash.
  ///
  /// The received block will be hashed in order to verify the correct block was returned.
  fn get_block(&self, hash: [u8; 32]) -> impl Send + Future<Output = Result<Block, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct BlockResponse {
        blob: String,
      }

      let res: BlockResponse =
        self.json_rpc_call("get_block", Some(json!({ "hash": hex::encode(hash) }))).await?;

      let block = Block::read::<&[u8]>(&mut rpc_hex(&res.blob)?.as_ref())
        .map_err(|_| RpcError::InvalidNode("invalid block".to_string()))?;
      if block.hash() != hash {
        Err(RpcError::InvalidNode("different block than requested (hash)".to_string()))?;
      }
      Ok(block)
    }
  }

  /// Get a block from the node by its number.
  ///
  /// `number` is the block's zero-indexed position on the blockchain (`0` for the genesis block,
  /// `height - 1` for the latest block).
  fn get_block_by_number(
    &self,
    number: usize,
  ) -> impl Send + Future<Output = Result<Block, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct BlockResponse {
        blob: String,
      }

      let res: BlockResponse =
        self.json_rpc_call("get_block", Some(json!({ "height": number }))).await?;

      let block = Block::read::<&[u8]>(&mut rpc_hex(&res.blob)?.as_ref())
        .map_err(|_| RpcError::InvalidNode("invalid block".to_string()))?;

      // Make sure this is actually the block for this number
      match block.miner_transaction.prefix().inputs.first() {
        Some(Input::Gen(actual)) => {
          if *actual == number {
            Ok(block)
          } else {
            Err(RpcError::InvalidNode("different block than requested (number)".to_string()))
          }
        }
        _ => Err(RpcError::InvalidNode(
          "block's miner_transaction didn't have an input of kind Input::Gen".to_string(),
        )),
      }
    }
  }

  /// Get a block's scannable form.
  fn get_scannable_block(
    &self,
    block: Block,
  ) -> impl Send + Future<Output = Result<ScannableBlock, RpcError>> {
    async move {
      let transactions = self.get_pruned_transactions(&block.transactions).await?;

      /*
        Requesting the output index for each output we sucessfully scan would cause a loss of
        privacy. We could instead request the output indexes for all outputs we scan, yet this
        would notably increase the amount of RPC calls we make.

        We solve this by requesting the output index for the first RingCT output in the block, which
        should be within the miner transaction. Then, as we scan transactions, we update the output
        index ourselves.

        Please note we only will scan RingCT outputs so we only need to track the RingCT output
        index. This decision was made due to spending CN outputs potentially having burdensome
        requirements (the need to make a v1 TX due to insufficient decoys).

        We bound ourselves to only scanning RingCT outputs by only scanning v2 transactions. This is
        safe and correct since:

        1) v1 transactions cannot create RingCT outputs.

           https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454
             /src/cryptonote_basic/cryptonote_format_utils.cpp#L866-L869

        2) v2 miner transactions implicitly create RingCT outputs.

           https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454
             /src/blockchain_db/blockchain_db.cpp#L232-L241

        3) v2 transactions must create RingCT outputs.

           https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c45
             /src/cryptonote_core/blockchain.cpp#L3055-L3065

           That does bound on the hard fork version being >= 3, yet all v2 TXs have a hard fork
           version > 3.

           https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454
             /src/cryptonote_core/blockchain.cpp#L3417
      */

      // Get the index for the first output
      let mut output_index_for_first_ringct_output = None;
      let miner_tx_hash = block.miner_transaction.hash();
      let miner_tx = Transaction::<Pruned>::from(block.miner_transaction.clone());
      for (hash, tx) in core::iter::once((&miner_tx_hash, &miner_tx))
        .chain(block.transactions.iter().zip(&transactions))
      {
        // If this isn't a RingCT output, or there are no outputs, move to the next TX
        if (!matches!(tx, Transaction::V2 { .. })) || tx.prefix().outputs.is_empty() {
          continue;
        }

        let index = *self.get_o_indexes(*hash).await?.first().ok_or_else(|| {
          RpcError::InvalidNode(
            "requested output indexes for a TX with outputs and got none".to_string(),
          )
        })?;
        output_index_for_first_ringct_output = Some(index);
        break;
      }

      Ok(ScannableBlock { block, transactions, output_index_for_first_ringct_output })
    }
  }

  /// Get a block's scannable form by its hash.
  // TODO: get_blocks.bin
  fn get_scannable_block_by_hash(
    &self,
    hash: [u8; 32],
  ) -> impl Send + Future<Output = Result<ScannableBlock, RpcError>> {
    async move { self.get_scannable_block(self.get_block(hash).await?).await }
  }

  /// Get a block's scannable form by its number.
  // TODO: get_blocks_by_height.bin
  fn get_scannable_block_by_number(
    &self,
    number: usize,
  ) -> impl Send + Future<Output = Result<ScannableBlock, RpcError>> {
    async move { self.get_scannable_block(self.get_block_by_number(number).await?).await }
  }

  /// Get the currently estimated fee rate from the node.
  ///
  /// This may be manipulated to unsafe levels and MUST be sanity checked.
  ///
  /// This MUST NOT be expected to be deterministic in any way.
  fn get_fee_rate(
    &self,
    priority: FeePriority,
  ) -> impl Send + Future<Output = Result<FeeRate, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct FeeResponse {
        status: String,
        fees: Option<Vec<u64>>,
        fee: u64,
        quantization_mask: u64,
      }

      let res: FeeResponse = self
        .json_rpc_call(
          "get_fee_estimate",
          Some(json!({ "grace_blocks": GRACE_BLOCKS_FOR_FEE_ESTIMATE })),
        )
        .await?;

      if res.status != "OK" {
        Err(RpcError::InvalidFee)?;
      }

      if let Some(fees) = res.fees {
        // https://github.com/monero-project/monero/blob/94e67bf96bbc010241f29ada6abc89f49a81759c/
        // src/wallet/wallet2.cpp#L7615-L7620
        let priority_idx = usize::try_from(if priority.fee_priority() >= 4 {
          3
        } else {
          priority.fee_priority().saturating_sub(1)
        })
        .map_err(|_| RpcError::InvalidPriority)?;

        if priority_idx >= fees.len() {
          Err(RpcError::InvalidPriority)
        } else {
          FeeRate::new(fees[priority_idx], res.quantization_mask)
        }
      } else {
        // https://github.com/monero-project/monero/blob/94e67bf96bbc010241f29ada6abc89f49a81759c/
        //   src/wallet/wallet2.cpp#L7569-L7584
        // https://github.com/monero-project/monero/blob/94e67bf96bbc010241f29ada6abc89f49a81759c/
        //   src/wallet/wallet2.cpp#L7660-L7661
        let priority_idx = usize::try_from(if priority.fee_priority() == 0 {
          1
        } else {
          priority.fee_priority() - 1
        })
        .map_err(|_| RpcError::InvalidPriority)?;
        let multipliers = [1, 5, 25, 1000];
        if priority_idx >= multipliers.len() {
          // though not an RPC error, it seems sensible to treat as such
          Err(RpcError::InvalidPriority)?;
        }
        let fee_multiplier = multipliers[priority_idx];

        FeeRate::new(res.fee * fee_multiplier, res.quantization_mask)
      }
    }
  }

  /// Publish a transaction.
  fn publish_transaction(
    &self,
    tx: &Transaction,
  ) -> impl Send + Future<Output = Result<(), RpcError>> {
    async move {
      #[allow(dead_code)]
      #[derive(Debug, Deserialize)]
      struct SendRawResponse {
        status: String,
        double_spend: bool,
        fee_too_low: bool,
        invalid_input: bool,
        invalid_output: bool,
        low_mixin: bool,
        not_relayed: bool,
        overspend: bool,
        too_big: bool,
        too_few_outputs: bool,
        reason: String,
      }

      let res: SendRawResponse = self
        .rpc_call(
          "send_raw_transaction",
          Some(json!({ "tx_as_hex": hex::encode(tx.serialize()), "do_sanity_checks": false })),
        )
        .await?;

      if res.status != "OK" {
        Err(RpcError::InvalidTransaction(tx.hash()))?;
      }

      Ok(())
    }
  }

  /// Generate blocks, with the specified address receiving the block reward.
  ///
  /// Returns the hashes of the generated blocks and the last block's number.
  fn generate_blocks<const ADDR_BYTES: u128>(
    &self,
    address: &Address<ADDR_BYTES>,
    block_count: usize,
  ) -> impl Send + Future<Output = Result<(Vec<[u8; 32]>, usize), RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct BlocksResponse {
        blocks: Vec<String>,
        height: usize,
      }

      let res = self
        .json_rpc_call::<BlocksResponse>(
          "generateblocks",
          Some(json!({
            "wallet_address": address.to_string(),
            "amount_of_blocks": block_count
          })),
        )
        .await?;

      let mut blocks = Vec::with_capacity(res.blocks.len());
      for block in res.blocks {
        blocks.push(hash_hex(&block)?);
      }
      Ok((blocks, res.height))
    }
  }

  /// Get the output indexes of the specified transaction.
  fn get_o_indexes(
    &self,
    hash: [u8; 32],
  ) -> impl Send + Future<Output = Result<Vec<u64>, RpcError>> {
    async move {
      // Given the immaturity of Rust epee libraries, this is a homegrown one which is only
      // validated to work against this specific function

      // Header for EPEE, an 8-byte magic and a version
      const EPEE_HEADER: &[u8] = b"\x01\x11\x01\x01\x01\x01\x02\x01\x01";

      // Read an EPEE VarInt, distinct from the VarInts used throughout the rest of the protocol
      fn read_epee_vi<R: io::Read>(reader: &mut R) -> io::Result<u64> {
        let vi_start = read_byte(reader)?;
        let len = match vi_start & 0b11 {
          0 => 1,
          1 => 2,
          2 => 4,
          3 => 8,
          _ => unreachable!(),
        };
        let mut vi = u64::from(vi_start >> 2);
        for i in 1 .. len {
          vi |= u64::from(read_byte(reader)?) << (((i - 1) * 8) + 6);
        }
        Ok(vi)
      }

      let mut request = EPEE_HEADER.to_vec();
      // Number of fields (shifted over 2 bits as the 2 LSBs are reserved for metadata)
      request.push(1 << 2);
      // Length of field name
      request.push(4);
      // Field name
      request.extend(b"txid");
      // Type of field
      request.push(10);
      // Length of string, since this byte array is technically a string
      request.push(32 << 2);
      // The "string"
      request.extend(hash);

      let indexes_buf = self.bin_call("get_o_indexes.bin", request).await?;
      let mut indexes: &[u8] = indexes_buf.as_ref();

      (|| {
        let mut res = None;
        let mut has_status = false;

        if read_bytes::<_, { EPEE_HEADER.len() }>(&mut indexes)? != EPEE_HEADER {
          Err(io::Error::other("invalid header"))?;
        }

        let read_object = |reader: &mut &[u8]| -> io::Result<Vec<u64>> {
          // Read the amount of fields
          let fields = read_byte(reader)? >> 2;

          for _ in 0 .. fields {
            // Read the length of the field's name
            let name_len = read_byte(reader)?;
            // Read the name of the field
            let name = read_raw_vec(read_byte, name_len.into(), reader)?;

            let type_with_array_flag = read_byte(reader)?;
            // The type of this field, without the potentially set array flag
            let kind = type_with_array_flag & (!0x80);
            let has_array_flag = type_with_array_flag != kind;

            // Read this many instances of the field
            let iters = if has_array_flag { read_epee_vi(reader)? } else { 1 };

            // Check the field type
            {
              #[allow(clippy::match_same_arms)]
              let (expected_type, expected_array_flag) = match name.as_slice() {
                b"o_indexes" => (5, true),
                b"status" => (10, false),
                b"untrusted" => (11, false),
                b"credits" => (5, false),
                b"top_hash" => (10, false),
                // On-purposely prints name as a byte vector to prevent printing arbitrary strings
                // This is a self-describing format so we don't have to error here, yet we don't
                // claim this to be a complete deserialization function
                // To ensure it works for this specific use case, it's best to ensure it's limited
                // to this specific use case (ensuring we have less variables to deal with)
                _ => {
                  Err(io::Error::other(format!("unrecognized field in get_o_indexes: {name:?}")))?
                }
              };
              if (expected_type != kind) || (expected_array_flag != has_array_flag) {
                let fmt_array_bool = |array_bool| if array_bool { "array" } else { "not array" };
                Err(io::Error::other(format!(
                  "field {name:?} was {kind} ({}), expected {expected_type} ({})",
                  fmt_array_bool(has_array_flag),
                  fmt_array_bool(expected_array_flag)
                )))?;
              }
            }

            let read_field_as_bytes = match kind {
              /*
              // i64
              1 => |reader: &mut &[u8]| read_raw_vec(read_byte, 8, reader),
              // i32
              2 => |reader: &mut &[u8]| read_raw_vec(read_byte, 4, reader),
              // i16
              3 => |reader: &mut &[u8]| read_raw_vec(read_byte, 2, reader),
              // i8
              4 => |reader: &mut &[u8]| read_raw_vec(read_byte, 1, reader),
              */
              // u64
              5 => |reader: &mut &[u8]| read_raw_vec(read_byte, 8, reader),
              /*
              // u32
              6 => |reader: &mut &[u8]| read_raw_vec(read_byte, 4, reader),
              // u16
              7 => |reader: &mut &[u8]| read_raw_vec(read_byte, 2, reader),
              // u8
              8 => |reader: &mut &[u8]| read_raw_vec(read_byte, 1, reader),
              // double
              9 => |reader: &mut &[u8]| read_raw_vec(read_byte, 8, reader),
              */
              // string, or any collection of bytes
              10 => |reader: &mut &[u8]| {
                let len = read_epee_vi(reader)?;
                read_raw_vec(
                  read_byte,
                  len.try_into().map_err(|_| io::Error::other("u64 length exceeded usize"))?,
                  reader,
                )
              },
              // bool
              11 => |reader: &mut &[u8]| read_raw_vec(read_byte, 1, reader),
              /*
              // object, errors here as it shouldn't be used on this call
              12 => {
                |_: &mut &[u8]| Err(io::Error::other("node used object in reply to get_o_indexes"))
              }
              // array, so far unused
              13 => |_: &mut &[u8]| Err(io::Error::other("node used the unused array type")),
              */
              _ => |_: &mut &[u8]| Err(io::Error::other("node used an invalid type")),
            };

            let mut bytes_res = vec![];
            for _ in 0 .. iters {
              bytes_res.push(read_field_as_bytes(reader)?);
            }

            let mut actual_res = Vec::with_capacity(bytes_res.len());
            match name.as_slice() {
              b"o_indexes" => {
                for o_index in bytes_res {
                  actual_res.push(read_u64(&mut o_index.as_slice())?);
                }
                res = Some(actual_res);
              }
              b"status" => {
                if bytes_res
                  .first()
                  .ok_or_else(|| io::Error::other("status was a 0-length array"))?
                  .as_slice() !=
                  b"OK"
                {
                  Err(io::Error::other("response wasn't OK"))?;
                }
                has_status = true;
              }
              b"untrusted" | b"credits" | b"top_hash" => continue,
              _ => Err(io::Error::other("unrecognized field in get_o_indexes"))?,
            }
          }

          if !has_status {
            Err(io::Error::other("response didn't contain a status"))?;
          }

          // If the Vec was empty, it would've been omitted, hence the unwrap_or
          Ok(res.unwrap_or(vec![]))
        };

        read_object(&mut indexes)
      })()
      .map_err(|e| RpcError::InvalidNode(format!("invalid binary response: {e:?}")))
    }
  }
}

/// A trait for any object which can be used to select RingCT decoys.
///
/// An implementation is provided for any satisfier of `Rpc`. It is not recommended to use an `Rpc`
/// object to satisfy this. This should be satisfied by a local store of the output distribution,
/// both for performance and to prevent potential attacks a remote node can perform.
pub trait DecoyRpc: Sync {
  /// Get the height the output distribution ends at.
  ///
  /// This is equivalent to the height of the blockchain it's for. This is intended to be cheaper
  /// than fetching the entire output distribution.
  fn get_output_distribution_end_height(
    &self,
  ) -> impl Send + Future<Output = Result<usize, RpcError>>;

  /// Get the RingCT (zero-amount) output distribution.
  ///
  /// `range` is in terms of block numbers. The result may be smaller than the requested range if
  /// the range starts before RingCT outputs were created on-chain.
  fn get_output_distribution(
    &self,
    range: impl Send + RangeBounds<usize>,
  ) -> impl Send + Future<Output = Result<Vec<u64>, RpcError>>;

  /// Get the specified outputs from the RingCT (zero-amount) pool.
  fn get_outs(
    &self,
    indexes: &[u64],
  ) -> impl Send + Future<Output = Result<Vec<OutputInformation>, RpcError>>;

  /// Get the specified outputs from the RingCT (zero-amount) pool, but only return them if their
  /// timelock has been satisfied.
  ///
  /// The timelock being satisfied is distinct from being free of the 10-block lock applied to all
  /// Monero transactions.
  ///
  /// The node is trusted for if the output is unlocked unless `fingerprintable_deterministic` is
  /// set to true. If `fingerprintable_deterministic` is set to true, the node's local view isn't
  /// used, yet the transaction's timelock is checked to be unlocked at the specified `height`.
  /// This offers a deterministic decoy selection, yet is fingerprintable as time-based timelocks
  /// aren't evaluated (and considered locked, preventing their selection).
  fn get_unlocked_outputs(
    &self,
    indexes: &[u64],
    height: usize,
    fingerprintable_deterministic: bool,
  ) -> impl Send + Future<Output = Result<Vec<Option<[EdwardsPoint; 2]>>, RpcError>>;
}

impl<R: Rpc> DecoyRpc for R {
  fn get_output_distribution_end_height(
    &self,
  ) -> impl Send + Future<Output = Result<usize, RpcError>> {
    async move { <Self as Rpc>::get_height(self).await }
  }

  fn get_output_distribution(
    &self,
    range: impl Send + RangeBounds<usize>,
  ) -> impl Send + Future<Output = Result<Vec<u64>, RpcError>> {
    async move {
      #[derive(Default, Debug, Deserialize)]
      struct Distribution {
        distribution: Vec<u64>,
        // A blockchain with just its genesis block has a height of 1
        start_height: usize,
      }

      #[derive(Debug, Deserialize)]
      struct Distributions {
        distributions: [Distribution; 1],
        status: String,
      }

      let from = match range.start_bound() {
        Bound::Included(from) => *from,
        Bound::Excluded(from) => from.checked_add(1).ok_or_else(|| {
          RpcError::InternalError("range's from wasn't representable".to_string())
        })?,
        Bound::Unbounded => 0,
      };
      let to = match range.end_bound() {
        Bound::Included(to) => *to,
        Bound::Excluded(to) => to
          .checked_sub(1)
          .ok_or_else(|| RpcError::InternalError("range's to wasn't representable".to_string()))?,
        Bound::Unbounded => self.get_height().await? - 1,
      };
      if from > to {
        Err(RpcError::InternalError(format!(
          "malformed range: inclusive start {from}, inclusive end {to}"
        )))?;
      }

      let zero_zero_case = (from == 0) && (to == 0);
      let distributions: Distributions = self
        .json_rpc_call(
          "get_output_distribution",
          Some(json!({
            "binary": false,
            "amounts": [0],
            "cumulative": true,
            // These are actually block numbers, not heights
            "from_height": from,
            "to_height": if zero_zero_case { 1 } else { to },
          })),
        )
        .await?;

      if distributions.status != "OK" {
        Err(RpcError::ConnectionError(
          "node couldn't service this request for the output distribution".to_string(),
        ))?;
      }

      let mut distributions = distributions.distributions;
      let Distribution { start_height, mut distribution } = core::mem::take(&mut distributions[0]);
      // start_height is also actually a block number, and it should be at least `from`
      // It may be after depending on when these outputs first appeared on the blockchain
      // Unfortunately, we can't validate without a binary search to find the RingCT activation
      // block and an iterative search from there, so we solely sanity check it
      if start_height < from {
        Err(RpcError::InvalidNode(format!(
          "requested distribution from {from} and got from {start_height}"
        )))?;
      }
      // It shouldn't be after `to` though
      if start_height > to {
        Err(RpcError::InvalidNode(format!(
          "requested distribution to {to} and got from {start_height}"
        )))?;
      }

      let expected_len = if zero_zero_case { 2 } else { (to - start_height) + 1 };
      // Yet this is actually a height
      if expected_len != distribution.len() {
        Err(RpcError::InvalidNode(format!(
          "distribution length ({}) wasn't of the requested length ({})",
          distribution.len(),
          expected_len
        )))?;
      }
      // Requesting to = 0 returns the distribution for the entire chain
      // We work around this by requesting 0, 1 (yielding two blocks), then popping the second
      // block
      if zero_zero_case {
        distribution.pop();
      }
      Ok(distribution)
    }
  }

  fn get_outs(
    &self,
    indexes: &[u64],
  ) -> impl Send + Future<Output = Result<Vec<OutputInformation>, RpcError>> {
    async move {
      #[derive(Debug, Deserialize)]
      struct OutputResponse {
        height: usize,
        unlocked: bool,
        key: String,
        mask: String,
        txid: String,
      }

      #[derive(Debug, Deserialize)]
      struct OutsResponse {
        status: String,
        outs: Vec<OutputResponse>,
      }

      // https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454
      //   /src/rpc/core_rpc_server.cpp#L67
      const MAX_OUTS: usize = 5000;

      let mut res = Vec::with_capacity(indexes.len());
      for indexes in indexes.chunks(MAX_OUTS) {
        let rpc_res: OutsResponse = self
          .rpc_call(
            "get_outs",
            Some(json!({
              "get_txid": true,
              "outputs": indexes.iter().map(|o| json!({
                "amount": 0,
                "index": o
              })).collect::<Vec<_>>()
            })),
          )
          .await?;

        if rpc_res.status != "OK" {
          Err(RpcError::InvalidNode("bad response to get_outs".to_string()))?;
        }

        res.extend(
          rpc_res
            .outs
            .into_iter()
            .map(|output| {
              Ok(OutputInformation {
                height: output.height,
                unlocked: output.unlocked,
                key: CompressedEdwardsY(
                  rpc_hex(&output.key)?
                    .try_into()
                    .map_err(|_| RpcError::InvalidNode("output key wasn't 32 bytes".to_string()))?,
                ),
                commitment: rpc_point(&output.mask)?,
                transaction: hash_hex(&output.txid)?,
              })
            })
            .collect::<Result<Vec<_>, RpcError>>()?,
        );
      }

      Ok(res)
    }
  }

  fn get_unlocked_outputs(
    &self,
    indexes: &[u64],
    height: usize,
    fingerprintable_deterministic: bool,
  ) -> impl Send + Future<Output = Result<Vec<Option<[EdwardsPoint; 2]>>, RpcError>> {
    async move {
      let outs = self.get_outs(indexes).await?;

      // Only need to fetch txs to do deterministic check on timelock
      let txs = if fingerprintable_deterministic {
        self.get_transactions(&outs.iter().map(|out| out.transaction).collect::<Vec<_>>()).await?
      } else {
        vec![]
      };

      // TODO: https://github.com/serai-dex/serai/issues/104
      outs
        .iter()
        .enumerate()
        .map(|(i, out)| {
          // Allow keys to be invalid, though if they are, return None to trigger selection of a
          // new decoy
          // Only valid keys can be used in CLSAG proofs, hence the need for re-selection, yet
          // invalid keys may honestly exist on the blockchain
          let Some(key) = out.key.decompress() else {
            return Ok(None);
          };
          Ok(Some([key, out.commitment]).filter(|_| {
            if fingerprintable_deterministic {
              // https://github.com/monero-project/monero/blob
              //   /cc73fe71162d564ffda8e549b79a350bca53c454/src/cryptonote_core
              //   /blockchain.cpp#L90
              const ACCEPTED_TIMELOCK_DELTA: usize = 1;

              // https://github.com/monero-project/monero/blob
              //   /cc73fe71162d564ffda8e549b79a350bca53c454/src/cryptonote_core
              //   /blockchain.cpp#L3836
              ((out.height + DEFAULT_LOCK_WINDOW) <= height) &&
                (Timelock::Block(height - 1 + ACCEPTED_TIMELOCK_DELTA) >=
                  txs[i].prefix().additional_timelock)
            } else {
              out.unlocked
            }
          }))
        })
        .collect()
    }
  }
}