sui_types/

execution_status.rs

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

use crate::ObjectID;
use crate::base_types::SuiAddress;
use crate::error::{BoxError, ExecutionError, ExecutionErrorMetadata, ExecutionErrorTrait};
use move_binary_format::file_format::{CodeOffset, TypeParameterIndex};
use move_core_types::language_storage::ModuleId;
use serde::{Deserialize, Serialize};
use std::error::Error;
use std::fmt::{self, Display, Formatter};
use sui_macros::EnumVariantOrder;
use thiserror::Error;

#[cfg(test)]
#[path = "unit_tests/execution_status_tests.rs"]
mod execution_status_tests;

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize)]
pub enum ExecutionStatus {
    Success,
    /// Gas used in the failed case, and the error.
    Failure(ExecutionFailure),
}

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize)]
pub struct ExecutionFailure {
    pub error: ExecutionErrorKind,
    pub command: Option<CommandIndex>,
}

impl ExecutionFailure {
    pub fn new(error: ExecutionErrorKind, command: Option<CommandIndex>) -> Self {
        ExecutionFailure { error, command }
    }
}

impl From<ExecutionError> for ExecutionFailure {
    fn from(value: ExecutionError) -> Self {
        Self {
            error: value.kind().clone(),
            command: value.command(),
        }
    }
}

impl Error for ExecutionFailure {}

impl Display for ExecutionFailure {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "Execution Failure: {}", self.error)
    }
}

impl ExecutionErrorTrait for ExecutionFailure {
    fn new(
        failure: ExecutionFailure,
        _source: Option<BoxError>,
        _metadata: ExecutionErrorMetadata,
    ) -> Self {
        failure
    }

    fn with_command_index(self, command: CommandIndex) -> Self {
        Self {
            command: Some(command),
            ..self
        }
    }
    fn kind(&self) -> &ExecutionErrorKind {
        &self.error
    }
    fn command(&self) -> Option<CommandIndex> {
        self.command
    }
}

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize)]
pub struct CongestedObjects(pub Vec<ObjectID>);

impl fmt::Display for CongestedObjects {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
        for obj in &self.0 {
            write!(f, "{}, ", obj)?;
        }
        Ok(())
    }
}

pub type ExecutionFailureStatus = ExecutionErrorKind;

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Error, EnumVariantOrder)]
pub enum ExecutionErrorKind {
    //
    // General transaction errors
    //
    #[error("Insufficient Gas.")]
    InsufficientGas,
    #[error("Invalid Gas Object. Possibly not address-owned or possibly not a SUI coin.")]
    InvalidGasObject,
    #[error("INVARIANT VIOLATION.")]
    InvariantViolation,
    #[error("Attempted to used feature that is not supported yet")]
    FeatureNotYetSupported,
    #[error(
        "Move object with size {object_size} is larger \
        than the maximum object size {max_object_size}"
    )]
    MoveObjectTooBig {
        object_size: u64,
        max_object_size: u64,
    },
    #[error(
        "Move package with size {object_size} is larger than the \
        maximum object size {max_object_size}"
    )]
    MovePackageTooBig {
        object_size: u64,
        max_object_size: u64,
    },
    #[error("Circular Object Ownership, including object {object}.")]
    CircularObjectOwnership { object: ObjectID },

    //
    // Coin errors
    //
    #[error("Insufficient coin balance for operation.")]
    InsufficientCoinBalance,
    #[error("The coin balance overflows u64")]
    CoinBalanceOverflow,

    //
    // Publish/Upgrade errors
    //
    #[error(
        "Publish Error, Non-zero Address. \
        The modules in the package must have their self-addresses set to zero."
    )]
    PublishErrorNonZeroAddress,

    #[error(
        "Sui Move Bytecode Verification Error. \
        Please run the Sui Move Verifier for more information."
    )]
    SuiMoveVerificationError,

    //
    // Errors from the Move VM
    //
    // Indicates an error from a non-abort instruction
    #[error(
        "Move Primitive Runtime Error. Location: {0}. \
        Arithmetic error, stack overflow, max value depth, etc."
    )]
    MovePrimitiveRuntimeError(MoveLocationOpt),
    #[error("Move Runtime Abort. Location: {0}, Abort Code: {1}")]
    MoveAbort(MoveLocation, u64),
    #[error(
        "Move Bytecode Verification Error. \
        Please run the Bytecode Verifier for more information."
    )]
    VMVerificationOrDeserializationError,
    #[error("MOVE VM INVARIANT VIOLATION.")]
    VMInvariantViolation,

    //
    // Programmable Transaction Errors
    //
    #[error("Function Not Found.")]
    FunctionNotFound,
    #[error(
        "Arity mismatch for Move function. \
        The number of arguments does not match the number of parameters"
    )]
    ArityMismatch,
    #[error(
        "Type arity mismatch for Move function. \
        Mismatch between the number of actual versus expected type arguments."
    )]
    TypeArityMismatch,
    #[error("Non Entry Function Invoked. Move Call must start with an entry function")]
    NonEntryFunctionInvoked,
    #[error("Invalid command argument at {arg_idx}. {kind}")]
    CommandArgumentError {
        arg_idx: u16,
        kind: CommandArgumentError,
    },
    #[error("Error for type argument at index {argument_idx}: {kind}")]
    TypeArgumentError {
        argument_idx: TypeParameterIndex,
        kind: TypeArgumentError,
    },
    #[error(
        "Unused result without the drop ability. \
        Command result {result_idx}, return value {secondary_idx}"
    )]
    UnusedValueWithoutDrop { result_idx: u16, secondary_idx: u16 },
    #[error(
        "Invalid public Move function signature. \
        Unsupported return type for return value {idx}"
    )]
    InvalidPublicFunctionReturnType { idx: u16 },
    #[error("Invalid Transfer Object, object does not have public transfer.")]
    InvalidTransferObject,

    //
    // Post-execution errors
    //
    // Indicates the effects from the transaction are too large
    #[error(
        "Effects of size {current_size} bytes too large. \
    Limit is {max_size} bytes"
    )]
    EffectsTooLarge { current_size: u64, max_size: u64 },

    #[error(
        "Publish/Upgrade Error, Missing dependency. \
         A dependency of a published or upgraded package has not been assigned an on-chain \
         address."
    )]
    PublishUpgradeMissingDependency,

    #[error(
        "Publish/Upgrade Error, Dependency downgrade. \
         Indirect (transitive) dependency of published or upgraded package has been assigned an \
         on-chain version that is less than the version required by one of the package's \
         transitive dependencies."
    )]
    PublishUpgradeDependencyDowngrade,

    #[error("Invalid package upgrade. {upgrade_error}")]
    PackageUpgradeError { upgrade_error: PackageUpgradeError },

    // Indicates the transaction tried to write objects too large to storage
    #[error(
        "Written objects of {current_size} bytes too large. \
    Limit is {max_size} bytes"
    )]
    WrittenObjectsTooLarge { current_size: u64, max_size: u64 },

    #[error("Certificate is on the deny list")]
    CertificateDenied,

    #[error(
        "Sui Move Bytecode Verification Timeout. \
        Please run the Sui Move Verifier for more information."
    )]
    SuiMoveVerificationTimedout,

    #[error("The shared object operation is not allowed.")]
    SharedObjectOperationNotAllowed,

    #[error(
        "Certificate cannot be executed due to a dependency on a deleted shared object or an object that was transferred out of consensus"
    )]
    InputObjectDeleted,

    #[error("Certificate is cancelled due to congestion on shared objects: {congested_objects}")]
    ExecutionCancelledDueToSharedObjectCongestion { congested_objects: CongestedObjects },

    #[error("Address {address:?} is denied for coin {coin_type}")]
    AddressDeniedForCoin {
        address: SuiAddress,
        coin_type: String,
    },

    #[error("Coin type is globally paused for use: {coin_type}")]
    CoinTypeGlobalPause { coin_type: String },

    #[error("Certificate is cancelled because randomness could not be generated this epoch")]
    ExecutionCancelledDueToRandomnessUnavailable,

    #[error(
        "Move vector element (passed to MakeMoveVec) with size {value_size} is larger \
        than the maximum size {max_scaled_size}. Note that this maximum is scaled based on the \
        type of the vector element."
    )]
    MoveVectorElemTooBig {
        value_size: u64,
        max_scaled_size: u64,
    },

    #[error(
        "Move value (possibly an upgrade ticket or a dev-inspect value) with size {value_size} \
        is larger than the maximum size  {max_scaled_size}. Note that this maximum is scaled based \
        on the type of the value."
    )]
    MoveRawValueTooBig {
        value_size: u64,
        max_scaled_size: u64,
    },

    #[error("A valid linkage was unable to be determined for the transaction")]
    InvalidLinkage,

    #[error("Insufficient funds for funds accumulator withdrawal")]
    InsufficientFundsForWithdraw,

    #[error("Non-exclusive write input object {id} has been modified")]
    NonExclusiveWriteInputObjectModified { id: ObjectID },

    // A system object the transaction must read has not yet caught up, on this node, to the version
    // the transaction requires. Node-local and transient: execution unwinds with it, the authority
    // discards the effects and retries, so it never reaches committed effects. Present only so the
    // unwind can be recognized by kind (see `TemporaryStore::check_system_object_available`).
    #[error("System object not available locally; transaction must be retried")]
    SystemObjectNotAvailableLocally,
    // NOTE: if you want to add a new enum,
    // please add it at the end for Rust SDK backward compatibility.
}

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Hash)]
pub struct MoveLocation {
    pub module: ModuleId,
    pub function: u16,
    pub instruction: CodeOffset,
    pub function_name: Option<String>,
}

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Hash)]
pub struct MoveLocationOpt(pub Option<MoveLocation>);

#[derive(Eq, PartialEq, Copy, Clone, Debug, Serialize, Deserialize, Hash, Error)]
pub enum CommandArgumentError {
    #[error("The type of the value does not match the expected type")]
    TypeMismatch,
    #[error("The argument cannot be deserialized into a value of the specified type")]
    InvalidBCSBytes,
    #[error("The argument cannot be instantiated from raw bytes")]
    InvalidUsageOfPureArg,
    #[error(
        "Invalid argument to private entry function. \
        These functions cannot take arguments from other Move functions"
    )]
    InvalidArgumentToPrivateEntryFunction,
    #[error("Out of bounds access to input or result vector {idx}")]
    IndexOutOfBounds { idx: u16 },
    #[error(
        "Out of bounds secondary access to result vector \
        {result_idx} at secondary index {secondary_idx}"
    )]
    SecondaryIndexOutOfBounds { result_idx: u16, secondary_idx: u16 },
    #[error(
        "Invalid usage of result {result_idx}, \
        expected a single result but found either no return values or multiple."
    )]
    InvalidResultArity { result_idx: u16 },
    #[error(
        "Invalid taking of the Gas coin. \
        It can only be used by-value with TransferObjects"
    )]
    InvalidGasCoinUsage,
    #[error(
        "Invalid usage of value. \
        Mutably borrowed values require unique usage. \
        Immutably borrowed values cannot be taken or borrowed mutably. \
        Taken values cannot be used again."
    )]
    InvalidValueUsage,
    #[error("Immutable objects cannot be passed by-value.")]
    InvalidObjectByValue,
    #[error("Immutable objects cannot be passed by mutable reference, &mut.")]
    InvalidObjectByMutRef,
    #[error(
        "Shared object operations such a wrapping, freezing, or converting to owned are not \
        allowed."
    )]
    SharedObjectOperationNotAllowed,
    #[error(
        "Invalid argument arity. Expected a single argument but found a result that expanded to \
        multiple arguments."
    )]
    InvalidArgumentArity,
    #[error(
        "Object passed to TransferObject does not have public transfer, i.e. the `store` \
        ability"
    )]
    InvalidTransferObject,
    #[error(
        "First argument to MakeMoveVec is not an object. If no type is specified for MakeMoveVec, all arguments must be the same object type."
    )]
    InvalidMakeMoveVecNonObjectArgument,
    #[error("Specified argument location does not have a value and cannot be used")]
    ArgumentWithoutValue,
    #[error(
        "Cannot move a borrowed value. The value's type does resulted in this argument usage \
        being inferred as a move. This is likely due to the type not having the `copy` ability; \
        although in rare cases, it could also be this is the last usage of a value without the \
        `drop` ability."
    )]
    CannotMoveBorrowedValue,
    #[error(
        "Cannot write to an argument location that is still borrowed, and where that borrow \
        is an extension of that reference. This is likely due to this argument being used in a \
        Move call that returns a reference, and that reference is used in a later command."
    )]
    CannotWriteToExtendedReference,
    #[error(
        "The argument specified cannot be used as a reference argument in the Move call. Either \
        the argument is a mutable reference and it conflicts with another argument to the call, \
        or the argument is mutable and another reference extends it and will be used in a later \
        command."
    )]
    InvalidReferenceArgument,
}

#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Hash, Error)]
pub enum PackageUpgradeError {
    #[error("Unable to fetch package at {package_id}")]
    UnableToFetchPackage { package_id: ObjectID },
    #[error("Object {object_id} is not a package")]
    NotAPackage { object_id: ObjectID },
    #[error("New package is incompatible with previous version")]
    IncompatibleUpgrade,
    #[error("Digest in upgrade ticket and computed digest disagree")]
    DigestDoesNotMatch { digest: Vec<u8> },
    #[error("Upgrade policy {policy} is not a valid upgrade policy")]
    UnknownUpgradePolicy { policy: u8 },
    #[error("Package ID {package_id} does not match package ID in upgrade ticket {ticket_id}")]
    PackageIDDoesNotMatch {
        package_id: ObjectID,
        ticket_id: ObjectID,
    },
}

#[derive(Eq, PartialEq, Clone, Copy, Debug, Serialize, Deserialize, Hash, Error)]
pub enum TypeArgumentError {
    #[error("A type was not found in the module specified.")]
    TypeNotFound,
    #[error("A type provided did not match the specified constraints.")]
    ConstraintNotSatisfied,
}

impl ExecutionErrorKind {
    pub fn command_argument_error(kind: CommandArgumentError, arg_idx: u16) -> Self {
        Self::CommandArgumentError { arg_idx, kind }
    }
}

impl Display for MoveLocationOpt {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match &self.0 {
            None => write!(f, "UNKNOWN"),
            Some(l) => write!(f, "{l}"),
        }
    }
}

impl Display for MoveLocation {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let Self {
            module,
            function,
            instruction,
            function_name,
        } = self;
        if let Some(fname) = function_name {
            write!(
                f,
                "{module}::{fname} (function index {function}) at offset {instruction}"
            )
        } else {
            write!(
                f,
                "{module} in function definition {function} at offset {instruction}"
            )
        }
    }
}

impl ExecutionStatus {
    pub fn new_failure(failure: ExecutionFailure) -> ExecutionStatus {
        ExecutionStatus::Failure(failure)
    }

    pub fn is_ok(&self) -> bool {
        matches!(self, ExecutionStatus::Success)
    }

    pub fn is_err(&self) -> bool {
        matches!(self, ExecutionStatus::Failure(_))
    }

    pub fn unwrap(&self) {
        match self {
            ExecutionStatus::Success => {}
            ExecutionStatus::Failure(_) => {
                panic!("Unable to unwrap() on {:?}", self);
            }
        }
    }

    pub fn unwrap_err(self) -> (ExecutionErrorKind, Option<CommandIndex>) {
        match self {
            ExecutionStatus::Success => {
                panic!("Unable to unwrap() on {:?}", self);
            }
            ExecutionStatus::Failure(ExecutionFailure { error, command }) => (error, command),
        }
    }

    pub fn get_congested_objects(&self) -> Option<&CongestedObjects> {
        if let ExecutionStatus::Failure(ExecutionFailure {
            error:
                ExecutionErrorKind::ExecutionCancelledDueToSharedObjectCongestion { congested_objects },
            ..
        }) = self
        {
            Some(congested_objects)
        } else {
            None
        }
    }

    pub fn is_cancelled(&self) -> bool {
        matches!(
            self,
            ExecutionStatus::Failure(ExecutionFailure {
                error: ExecutionErrorKind::ExecutionCancelledDueToSharedObjectCongestion { .. },
                ..
            })
        )
    }
}

pub type CommandIndex = usize;