sui_types/

coin_reservation.rs

// Copyright (c) Mysten Labs, Inc.
// SPDX-License-Identifier: Apache-2.0

//! This module defines the protocol for specifying an address balance reservation
//! via an ObjectRef, in order to provide backward compatibility for clients that do
//! not understand address balances.
//!
//! The layout of the reservation ObjectRef is as follows:
//!
//!    (ObjectID, SequenceNumber, ObjectDigest)
//!
//! The ObjectID points to an accumulator object (i.e. a dynamic field of the accumulator root object).
//! This identifies both the owner and type (e.g. SUI, USDC, etc) of the balance being spent.
//!
//! It is masked by XORing with the current chain identifier (i.e. genesis checkpoint digest).
//! This prevents cross-chain replay, as an attacker would have to mine an address and currency
//! type such that `dynamic_field_key(address, type) = V` such that
//! `V ^ FOREIGN_CHAIN_IDENTIFIER = TARGET_ACCUMULATOR_OBJECT_ID ^ TARGET_CHAIN_IDENTIFIER`
//! and then trick the target into signing a transaction as V on the foreign chain.
//!
//! The masking also allows read APIs to positively identify attempts to read a "fake" object ID, as
//! follows:
//!   1. First, read the requested object ID.
//!   2. If it does not exist, unmask the ID using the local chain identifier and read it again.
//!   3. If it exists on the second attempt, the ID must have originated by masking an accumulator object ID.
//!
//! The SequenceNumber is a monotonically increasing version number, typically the version of the
//! accumulator root object. It is not used by the protocol, but is intended to help the
//! caching behavior of old clients.
//!
//! ObjectDigest contains the remainder of the payload:
//!
//! 1. The amount of the reservation [8 bytes]
//! 2. The epoch(s) in which the tx is valid [4 bytes] (good enough for 12 million years of 24 hour epochs).
//! 3. A magic number to identify this ObjectRef as a coin reservation [20 bytes].

use std::sync::Arc;

use move_core_types::language_storage::TypeTag;
use thiserror::Error;

use crate::{
    accumulator_root::{AccumulatorKey, AccumulatorValue},
    base_types::{ObjectID, ObjectRef, SequenceNumber, SuiAddress},
    committee::EpochId,
    digests::{ChainIdentifier, ObjectDigest},
    error::{UserInputError, UserInputResult},
    storage::RuntimeObjectResolver,
    transaction::FundsWithdrawalArg,
};

macro_rules! invalid_res_error {
    ($($args:tt)*) => {
        UserInputError::InvalidWithdrawReservation {
            error: format!($($args)*),
        }
    };
}

/// Trait for resolving funds withdrawal from a coin reservation
pub trait CoinReservationResolverTrait {
    // Used to check validity of the transaction. If the coin_reservation does not
    // point to an existing accumulator object, the transaction will be rejected.
    fn resolve_funds_withdrawal(
        &self,
        // Note: must be the sender. We do not support sponsorship.
        sender: SuiAddress,
        coin_reservation: ParsedObjectRefWithdrawal,
        // The version of the accumulator root object to use for MVCC lookup.
        // If None, use the latest version.
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<FundsWithdrawalArg>;
}

pub const COIN_RESERVATION_MAGIC: [u8; 20] = [
    0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac, 0xac,
    0xac, 0xac, 0xac, 0xac,
];

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct ParsedDigest {
    epoch_id: u32,
    reservation_amount: u64,
}

impl ParsedDigest {
    pub fn epoch_id(&self) -> EpochId {
        self.epoch_id as EpochId
    }

    pub fn reservation_amount(&self) -> u64 {
        self.reservation_amount
    }

    pub fn is_coin_reservation_digest(digest: &ObjectDigest) -> bool {
        let inner = digest.inner();
        // check if the last 20 bytes of digest match the magic number
        let last_20_bytes: &[u8; 20] = inner[12..32].try_into().unwrap();
        *last_20_bytes == COIN_RESERVATION_MAGIC
    }
}

#[derive(Debug, Error)]
#[error("Invalid digest")]
pub struct ParsedDigestError;

impl TryFrom<ObjectDigest> for ParsedDigest {
    type Error = ParsedDigestError;

    fn try_from(digest: ObjectDigest) -> Result<Self, Self::Error> {
        if ParsedDigest::is_coin_reservation_digest(&digest) {
            let inner = digest.inner();
            let reservation_amount_bytes: &[u8; 8] = inner[0..8].try_into().unwrap();
            let epoch_bytes: &[u8; 4] = inner[8..12].try_into().unwrap();

            let epoch_id = u32::from_le_bytes(*epoch_bytes);
            let reservation_amount = u64::from_le_bytes(*reservation_amount_bytes);

            Ok(Self {
                epoch_id,
                reservation_amount,
            })
        } else {
            Err(ParsedDigestError)
        }
    }
}

impl From<ParsedDigest> for ObjectDigest {
    fn from(parsed: ParsedDigest) -> Self {
        let mut inner = [0; 32];
        inner[0..8].copy_from_slice(&parsed.reservation_amount.to_le_bytes());
        inner[8..12].copy_from_slice(&parsed.epoch_id.to_le_bytes());
        inner[12..32].copy_from_slice(&COIN_RESERVATION_MAGIC);
        ObjectDigest::new(inner)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ParsedObjectRefWithdrawal {
    pub unmasked_object_id: ObjectID,
    pub parsed_digest: ParsedDigest,
}

impl ParsedObjectRefWithdrawal {
    pub fn new(unmasked_object_id: ObjectID, epoch_id: EpochId, reservation_amount: u64) -> Self {
        Self {
            unmasked_object_id,
            parsed_digest: ParsedDigest {
                epoch_id: epoch_id.try_into().unwrap(),
                reservation_amount,
            },
        }
    }

    pub fn reservation_amount(&self) -> u64 {
        self.parsed_digest.reservation_amount()
    }

    pub fn epoch_id(&self) -> EpochId {
        self.parsed_digest.epoch_id()
    }

    pub fn encode(&self, version: SequenceNumber, chain_identifier: ChainIdentifier) -> ObjectRef {
        let digest = self.parsed_digest.into();
        let masked_id = mask_or_unmask_id(self.unmasked_object_id, chain_identifier);
        (masked_id, version, digest)
    }

    pub fn parse(object_ref: &ObjectRef, chain_identifier: ChainIdentifier) -> Option<Self> {
        let (object_id, _version, digest) = object_ref;
        let parsed_digest = ParsedDigest::try_from(*digest).ok()?;

        let unmasked_object_id = mask_or_unmask_id(*object_id, chain_identifier);

        Some(ParsedObjectRefWithdrawal {
            unmasked_object_id,
            parsed_digest,
        })
    }
}

pub fn mask_or_unmask_id(object_id: ObjectID, chain_identifier: ChainIdentifier) -> ObjectID {
    let mask_bytes: &[u8; 32] = chain_identifier.as_bytes();

    let object_id_bytes: [u8; 32] = object_id.into_bytes();
    let mut masked_object_id_bytes = [0; 32];
    for i in 0..32 {
        masked_object_id_bytes[i] = object_id_bytes[i] ^ mask_bytes[i];
    }
    ObjectID::new(masked_object_id_bytes)
}

/// Creates a fake ObjectRef representing an address balance, suitable for returning from
/// JSON-RPC APIs to backward-compatible clients. The object_id is masked with the chain
/// identifier to prevent cross-chain replay.
pub fn encode_object_ref(
    unmasked_object_id: ObjectID,
    version: SequenceNumber,
    epoch: EpochId,
    balance: u64,
    chain_identifier: ChainIdentifier,
) -> ObjectRef {
    ParsedObjectRefWithdrawal::new(unmasked_object_id, epoch, balance)
        .encode(version, chain_identifier)
}

fn get_owner_and_type_for_object_impl(
    runtime_object_resolver: &dyn RuntimeObjectResolver,
    object_id: ObjectID,
    accumulator_version: Option<SequenceNumber>,
) -> UserInputResult<Option<(SuiAddress, TypeTag)>> {
    let Some(object) = AccumulatorValue::load_object_by_id(
        runtime_object_resolver,
        accumulator_version,
        object_id,
    )
    .map_err(|e| invalid_res_error!("could not load coin reservation object id {}", e))?
    else {
        return Ok(None);
    };

    let move_object = object.data.try_as_move().unwrap();

    let type_tag: TypeTag = move_object
        .type_()
        .balance_accumulator_field_type_maybe()
        .ok_or_else(|| {
            invalid_res_error!(
                "coin reservation object id {} is not a balance accumulator field",
                object_id
            )
        })?;

    let (key, _): (AccumulatorKey, AccumulatorValue) = move_object
        .try_into()
        .map_err(|e| invalid_res_error!("could not load coin reservation object id {}", e))?;

    Ok(Some((key.owner, type_tag)))
}

fn resolve_funds_withdrawal_impl(
    runtime_object_resolver: &dyn RuntimeObjectResolver,
    sender: SuiAddress,
    coin_reservation: ParsedObjectRefWithdrawal,
    accumulator_version: Option<SequenceNumber>,
) -> UserInputResult<FundsWithdrawalArg> {
    let (owner, type_tag) = get_owner_and_type_for_object_impl(
        runtime_object_resolver,
        coin_reservation.unmasked_object_id,
        accumulator_version,
    )?
    .ok_or_else(|| {
        invalid_res_error!(
            "coin reservation object id {} not found",
            coin_reservation.unmasked_object_id
        )
    })?;

    if sender != owner {
        return Err(invalid_res_error!(
            "coin reservation object id {} is owned by {}, not sender {}",
            coin_reservation.unmasked_object_id,
            owner,
            sender
        ));
    }

    Ok(FundsWithdrawalArg::balance_from_sender(
        coin_reservation.reservation_amount(),
        type_tag,
    ))
}

/// Resolves coin reservations by looking up the accumulator object to determine
/// the owner and type of the balance being withdrawn.
pub struct CoinReservationResolver {
    runtime_object_resolver: Arc<dyn RuntimeObjectResolver + Send + Sync>,
}

impl CoinReservationResolver {
    pub fn new(runtime_object_resolver: Arc<dyn RuntimeObjectResolver + Send + Sync>) -> Self {
        Self {
            runtime_object_resolver,
        }
    }

    /// Looks up the type tag and owner for a given accumulator object ID.
    /// Returns `Ok(Some((owner, type_tag)))` if the object exists and is a valid balance
    /// accumulator field, `Ok(None)` if the object does not exist (a transient condition
    /// on this node), and `Err(_)` for any other failure (which is permanent for this
    /// `object_id` and therefore safe to cache).
    pub fn get_owner_and_type_for_object(
        &self,
        object_id: ObjectID,
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<Option<(SuiAddress, TypeTag)>> {
        get_owner_and_type_for_object_impl(
            self.runtime_object_resolver.as_ref(),
            object_id,
            accumulator_version,
        )
    }

    pub fn resolve_funds_withdrawal(
        &self,
        sender: SuiAddress,
        coin_reservation: ParsedObjectRefWithdrawal,
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<FundsWithdrawalArg> {
        resolve_funds_withdrawal_impl(
            self.runtime_object_resolver.as_ref(),
            sender,
            coin_reservation,
            accumulator_version,
        )
    }
}

/// Borrow a runtime object resolver for coin-reservation lookups.
pub struct BorrowedCoinReservationResolver<'a> {
    runtime_object_resolver: &'a dyn RuntimeObjectResolver,
}

impl<'a> BorrowedCoinReservationResolver<'a> {
    /// Create a coin-reservation resolver over borrowed storage.
    pub fn new(runtime_object_resolver: &'a dyn RuntimeObjectResolver) -> Self {
        Self {
            runtime_object_resolver,
        }
    }
}

impl CoinReservationResolverTrait for BorrowedCoinReservationResolver<'_> {
    fn resolve_funds_withdrawal(
        &self,
        sender: SuiAddress,
        coin_reservation: ParsedObjectRefWithdrawal,
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<FundsWithdrawalArg> {
        resolve_funds_withdrawal_impl(
            self.runtime_object_resolver,
            sender,
            coin_reservation,
            accumulator_version,
        )
    }
}

impl CoinReservationResolverTrait for CoinReservationResolver {
    fn resolve_funds_withdrawal(
        &self,
        sender: SuiAddress,
        coin_reservation: ParsedObjectRefWithdrawal,
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<FundsWithdrawalArg> {
        CoinReservationResolver::resolve_funds_withdrawal(
            self,
            sender,
            coin_reservation,
            accumulator_version,
        )
    }
}

impl CoinReservationResolverTrait for &'_ CoinReservationResolver {
    fn resolve_funds_withdrawal(
        &self,
        sender: SuiAddress,
        coin_reservation: ParsedObjectRefWithdrawal,
        accumulator_version: Option<SequenceNumber>,
    ) -> UserInputResult<FundsWithdrawalArg> {
        CoinReservationResolver::resolve_funds_withdrawal(
            self,
            sender,
            coin_reservation,
            accumulator_version,
        )
    }
}
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_normal_digest() {
        let digest = ObjectDigest::new([0; 32]);
        assert!(ParsedDigest::try_from(digest).is_err());
    }

    #[test]
    fn test_is_coin_reservation_digest() {
        let digest = ObjectDigest::random();
        assert!(!ParsedDigest::is_coin_reservation_digest(&digest));

        let digest = ParsedDigest {
            epoch_id: 42,
            reservation_amount: 1232348999,
        }
        .into();
        assert!(ParsedDigest::is_coin_reservation_digest(&digest));
    }

    #[test]
    fn test_encode_and_parse_digest() {
        let parsed_digest = ParsedDigest {
            epoch_id: 42,
            reservation_amount: 1232348999,
        };

        let digest = ObjectDigest::from(parsed_digest);
        assert_eq!(parsed_digest, ParsedDigest::try_from(digest).unwrap());
    }

    #[test]
    fn test_parse_object_ref() {
        let object_ref = (
            ObjectID::new([0; 32]),
            SequenceNumber::new(),
            ObjectDigest::new([0; 32]),
        );

        assert!(
            ParsedObjectRefWithdrawal::parse(&object_ref, ChainIdentifier::default()).is_none()
        );
    }

    #[test]
    fn test_borrowed_resolver_uses_runtime_object_resolver() {
        let store = crate::in_memory_storage::InMemoryStorage::default();
        let resolver = BorrowedCoinReservationResolver::new(&store);
        let object_id = ObjectID::random();
        let result = resolver.resolve_funds_withdrawal(
            SuiAddress::random_for_testing_only(),
            ParsedObjectRefWithdrawal::new(object_id, 0, 1),
            None,
        );

        assert!(matches!(
            result,
            Err(UserInputError::InvalidWithdrawReservation { error })
                if error == format!("coin reservation object id {object_id} not found")
        ));
    }

    #[test]
    fn test_parse_object_ref_with_valid_digest() {
        let chain_id = ChainIdentifier::random();

        let id = ObjectID::random();
        let parsed_obj_ref = ParsedObjectRefWithdrawal {
            unmasked_object_id: id,
            parsed_digest: ParsedDigest {
                epoch_id: 42,
                reservation_amount: 1232348999,
            },
        };
        let encoded_obj_ref = parsed_obj_ref.encode(SequenceNumber::new(), chain_id);

        assert_ne!(encoded_obj_ref.0, id, "object id should be masked");

        let parsed_obj_ref = ParsedObjectRefWithdrawal::parse(&encoded_obj_ref, chain_id).unwrap();
        assert_eq!(parsed_obj_ref.unmasked_object_id, id);
        assert_eq!(parsed_obj_ref.parsed_digest.epoch_id, 42);
        assert_eq!(parsed_obj_ref.parsed_digest.reservation_amount, 1232348999);
    }
}