aptos-sdk 0.6.0

//! Transaction payloads.

use crate::types::{MoveModuleId, TypeTag};
use serde::{Deserialize, Serialize};

/// The payload of a transaction, specifying what action to take.
///
/// Note: Variant indices must match Aptos core for BCS compatibility:
/// - 0: Script
/// - 1: `ModuleBundle` (deprecated)
/// - 2: `EntryFunction`
/// - 3: Multisig
/// - 4: `Payload` (unified executable + extra-config format; used for
///   orderless transactions)
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum TransactionPayload {
    /// Execute a script with bytecode (variant 0).
    Script(Script),
    /// Deprecated module bundle payload (variant 1).
    /// This variant exists only for BCS compatibility.
    #[doc(hidden)]
    ModuleBundle(DeprecatedModuleBundle),
    /// Call an entry function on a module (variant 2).
    EntryFunction(EntryFunction),
    /// Multisig transaction payload (variant 3).
    Multisig(Multisig),
    /// Unified payload format carrying an executable plus extra configuration
    /// (variant 4).
    ///
    /// This is the format the chain uses for **orderless** transactions, where
    /// replay protection is provided by a nonce (in the extra config) instead of
    /// a sequence number. See [`TransactionPayloadInner`].
    Payload(TransactionPayloadInner),
}

impl TransactionPayload {
    /// Wraps an `EntryFunction` or `Script` payload as an orderless
    /// [`Payload`](TransactionPayload::Payload) with the given replay-protection
    /// `nonce`.
    ///
    /// The resulting payload must be sent in a [`RawTransaction`] whose
    /// `sequence_number` is [`u64::MAX`], which is how the chain distinguishes
    /// nonce-based (orderless) replay protection from sequence-number-based
    /// replay protection.
    ///
    /// [`RawTransaction`]: crate::transaction::RawTransaction
    ///
    /// # Errors
    ///
    /// Returns [`AptosError::Transaction`](crate::error::AptosError::Transaction)
    /// if the payload is not an `EntryFunction` or `Script` (multisig, module
    /// bundle, and already-wrapped `Payload` variants are not supported as
    /// orderless executables).
    pub fn into_orderless(self, nonce: u64) -> crate::error::AptosResult<Self> {
        let executable = match self {
            TransactionPayload::EntryFunction(ef) => TransactionExecutable::EntryFunction(ef),
            TransactionPayload::Script(s) => TransactionExecutable::Script(s),
            other => {
                return Err(crate::error::AptosError::Transaction(format!(
                    "orderless transactions support only entry-function or script payloads, got {}",
                    other.variant_name()
                )));
            }
        };
        Ok(TransactionPayload::Payload(TransactionPayloadInner::V1 {
            executable,
            extra_config: TransactionExtraConfig::V1 {
                multisig_address: None,
                replay_protection_nonce: Some(nonce),
            },
        }))
    }

    /// Returns a human-readable name for the payload variant (for diagnostics).
    fn variant_name(&self) -> &'static str {
        match self {
            TransactionPayload::Script(_) => "Script",
            TransactionPayload::ModuleBundle(_) => "ModuleBundle",
            TransactionPayload::EntryFunction(_) => "EntryFunction",
            TransactionPayload::Multisig(_) => "Multisig",
            TransactionPayload::Payload(_) => "Payload",
        }
    }
}

/// The inner, versioned body of a [`TransactionPayload::Payload`].
///
/// Variant index must be 0 (`V1`) to match Aptos core for BCS compatibility.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum TransactionPayloadInner {
    /// Version 1 (variant 0): an executable plus extra configuration.
    V1 {
        /// What to execute (entry function, script, or nothing).
        executable: TransactionExecutable,
        /// Extra configuration (multisig address, replay-protection nonce).
        extra_config: TransactionExtraConfig,
    },
}

/// The executable portion of a [`TransactionPayloadInner`].
///
/// Variant indices must match Aptos core for BCS compatibility:
/// - 0: `Script`
/// - 1: `EntryFunction`
/// - 2: `Empty`
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum TransactionExecutable {
    /// Execute a script with bytecode (variant 0).
    Script(Script),
    /// Call an entry function on a module (variant 1).
    EntryFunction(EntryFunction),
    /// No executable (variant 2), e.g. a multisig transaction whose executable
    /// is stored on chain.
    Empty,
}

/// Extra configuration attached to a [`TransactionPayloadInner`].
///
/// Variant index must be 0 (`V1`) to match Aptos core for BCS compatibility.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum TransactionExtraConfig {
    /// Version 1 (variant 0).
    V1 {
        /// The multisig account address, when this is a multisig transaction.
        multisig_address: Option<crate::types::AccountAddress>,
        /// The replay-protection nonce, present for orderless transactions.
        replay_protection_nonce: Option<u64>,
    },
}

/// Deprecated module bundle payload.
/// This type exists only for BCS enum variant compatibility.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeprecatedModuleBundle {
    #[doc(hidden)]
    _private: (),
}

/// Multisig transaction payload.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Multisig {
    /// The multisig account address.
    pub multisig_address: crate::types::AccountAddress,
    /// The inner transaction payload (optional).
    pub transaction_payload: Option<MultisigTransactionPayload>,
}

/// Inner payload for multisig transactions.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum MultisigTransactionPayload {
    /// Entry function call.
    EntryFunction(EntryFunction),
}

/// A script payload with inline bytecode.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Script {
    /// The Move bytecode to execute.
    #[serde(with = "serde_bytes")]
    pub code: Vec<u8>,
    /// Type arguments for the script.
    pub type_args: Vec<TypeTag>,
    /// Arguments to the script.
    pub args: Vec<ScriptArgument>,
}

impl Script {
    /// Creates a new script payload.
    pub fn new(code: Vec<u8>, type_args: Vec<TypeTag>, args: Vec<ScriptArgument>) -> Self {
        Self {
            code,
            type_args,
            args,
        }
    }
}

/// An argument to a script.
///
/// Variant order must match the chain's `ScriptTransactionArgumentVariants` for BCS compatibility with the
/// chain and TS SDK. See: <https://github.com/aptos-labs/aptos-core/blob/main/third_party/move/move-core/types/src/transaction_argument.rs>
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum ScriptArgument {
    /// A u8 value (variant 0).
    U8(u8),
    /// A u64 value (variant 1).
    U64(u64),
    /// A u128 value (variant 2).
    U128(u128),
    /// An address value (variant 3).
    Address(crate::types::AccountAddress),
    /// A vector of u8 / bytes (variant 4).
    U8Vector(#[serde(with = "serde_bytes")] Vec<u8>),
    /// A boolean value (variant 5).
    Bool(bool),
    /// A u16 value (variant 6).
    U16(u16),
    /// A u32 value (variant 7).
    U32(u32),
    /// A u256 value as 32 bytes (variant 8).
    U256([u8; 32]),
    /// Pre-serialized BCS bytes (variant 9). Use for types not directly representable as other variants.
    Serialized(#[serde(with = "serde_bytes")] Vec<u8>),
    /// An i8 value (variant 10).
    I8(i8),
    /// An i16 value (variant 11).
    I16(i16),
    /// An i32 value (variant 12).
    I32(i32),
    /// An i64 value (variant 13).
    I64(i64),
    /// An i128 value (variant 14).
    I128(i128),
    /// An i256 value as 32 bytes (variant 15).
    I256([u8; 32]),
}

/// An entry function call payload.
///
/// Entry functions are the most common type of transaction payload.
/// They call a function marked as `entry` in a Move module.
///
/// # Example
///
/// ```rust
/// use aptos_sdk::transaction::EntryFunction;
/// use aptos_sdk::types::{MoveModuleId, TypeTag, AccountAddress};
///
/// // Create a coin transfer payload
/// let module = MoveModuleId::from_str_strict("0x1::coin").unwrap();
/// let recipient = AccountAddress::from_hex("0x123").unwrap();
/// let entry_function = EntryFunction {
///     module,
///     function: "transfer".to_string(),
///     type_args: vec![TypeTag::aptos_coin()],
///     args: vec![
///         aptos_bcs::to_bytes(&recipient).unwrap(),
///         aptos_bcs::to_bytes(&1000u64).unwrap(),
///     ],
/// };
/// ```
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct EntryFunction {
    /// The module containing the function.
    pub module: MoveModuleId,
    /// The function name.
    pub function: String,
    /// Type arguments for generic functions.
    pub type_args: Vec<TypeTag>,
    /// BCS-encoded arguments.
    pub args: Vec<Vec<u8>>,
}

impl EntryFunction {
    /// Creates a new entry function payload.
    pub fn new(
        module: MoveModuleId,
        function: impl Into<String>,
        type_args: Vec<TypeTag>,
        args: Vec<Vec<u8>>,
    ) -> Self {
        Self {
            module,
            function: function.into(),
            type_args,
            args,
        }
    }

    /// Creates an entry function from a function identifier string.
    ///
    /// # Arguments
    ///
    /// * `function_id` - Full function ID (e.g., "`0x1::coin::transfer`")
    /// * `type_args` - Type arguments
    /// * `args` - BCS-encoded arguments
    ///
    /// # Errors
    ///
    /// Returns an error if the function ID string is invalid.
    pub fn from_function_id(
        function_id: &str,
        type_args: Vec<TypeTag>,
        args: Vec<Vec<u8>>,
    ) -> crate::error::AptosResult<Self> {
        let func_id = crate::types::EntryFunctionId::from_str_strict(function_id)?;
        Ok(Self {
            module: func_id.module,
            function: func_id.name.as_str().to_string(),
            type_args,
            args,
        })
    }

    /// Creates a simple APT transfer payload.
    ///
    /// # Arguments
    ///
    /// * `recipient` - The recipient's address
    /// * `amount` - Amount in octas (1 APT = 10^8 octas)
    ///
    /// # Errors
    ///
    /// Returns an error if the module ID is invalid or if BCS encoding of arguments fails.
    pub fn apt_transfer(
        recipient: crate::types::AccountAddress,
        amount: u64,
    ) -> crate::error::AptosResult<Self> {
        let module = MoveModuleId::from_str_strict("0x1::aptos_account")?;
        Ok(Self {
            module,
            function: "transfer".to_string(),
            type_args: vec![],
            args: vec![
                aptos_bcs::to_bytes(&recipient).map_err(crate::error::AptosError::bcs)?,
                aptos_bcs::to_bytes(&amount).map_err(crate::error::AptosError::bcs)?,
            ],
        })
    }

    /// Creates a coin transfer payload for any coin type.
    ///
    /// # Arguments
    ///
    /// * `coin_type` - The coin type tag
    /// * `recipient` - The recipient's address
    /// * `amount` - Amount in the coin's smallest unit
    ///
    /// # Errors
    ///
    /// Returns an error if the module ID is invalid or if BCS encoding of arguments fails.
    pub fn coin_transfer(
        coin_type: TypeTag,
        recipient: crate::types::AccountAddress,
        amount: u64,
    ) -> crate::error::AptosResult<Self> {
        let module = MoveModuleId::from_str_strict("0x1::coin")?;
        Ok(Self {
            module,
            function: "transfer".to_string(),
            type_args: vec![coin_type],
            args: vec![
                aptos_bcs::to_bytes(&recipient).map_err(crate::error::AptosError::bcs)?,
                aptos_bcs::to_bytes(&amount).map_err(crate::error::AptosError::bcs)?,
            ],
        })
    }
}

impl From<EntryFunction> for TransactionPayload {
    fn from(entry_function: EntryFunction) -> Self {
        TransactionPayload::EntryFunction(entry_function)
    }
}

impl From<Script> for TransactionPayload {
    fn from(script: Script) -> Self {
        TransactionPayload::Script(script)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::AccountAddress;

    #[test]
    fn test_apt_transfer() {
        let recipient = AccountAddress::from_hex("0x123").unwrap();
        let entry_fn = EntryFunction::apt_transfer(recipient, 1000).unwrap();

        assert_eq!(entry_fn.function, "transfer");
        assert!(entry_fn.type_args.is_empty());
        assert_eq!(entry_fn.args.len(), 2);
    }

    #[test]
    fn test_from_function_id() {
        let entry_fn = EntryFunction::from_function_id(
            "0x1::coin::transfer",
            vec![TypeTag::aptos_coin()],
            vec![],
        )
        .unwrap();

        assert_eq!(entry_fn.module.address, AccountAddress::ONE);
        assert_eq!(entry_fn.module.name.as_str(), "coin");
        assert_eq!(entry_fn.function, "transfer");
    }

    #[test]
    fn test_entry_function_new() {
        let module = MoveModuleId::from_str_strict("0x1::test_module").unwrap();
        let entry_fn = EntryFunction::new(
            module.clone(),
            "test_function",
            vec![TypeTag::U64],
            vec![vec![1, 2, 3]],
        );

        assert_eq!(entry_fn.module, module);
        assert_eq!(entry_fn.function, "test_function");
        assert_eq!(entry_fn.type_args.len(), 1);
        assert_eq!(entry_fn.args.len(), 1);
    }

    #[test]
    fn test_coin_transfer() {
        let recipient = AccountAddress::from_hex("0x456").unwrap();
        let coin_type = TypeTag::aptos_coin();
        let entry_fn = EntryFunction::coin_transfer(coin_type, recipient, 5000).unwrap();

        assert_eq!(entry_fn.module.address, AccountAddress::ONE);
        assert_eq!(entry_fn.module.name.as_str(), "coin");
        assert_eq!(entry_fn.function, "transfer");
        assert_eq!(entry_fn.type_args.len(), 1);
        assert_eq!(entry_fn.args.len(), 2);
    }

    #[test]
    fn test_into_orderless_wraps_entry_function() {
        let ef = EntryFunction::apt_transfer(AccountAddress::ONE, 1).unwrap();
        let payload = TransactionPayload::EntryFunction(ef.clone())
            .into_orderless(0xdead_beef)
            .unwrap();

        match payload {
            TransactionPayload::Payload(TransactionPayloadInner::V1 {
                executable: TransactionExecutable::EntryFunction(inner),
                extra_config:
                    TransactionExtraConfig::V1 {
                        multisig_address,
                        replay_protection_nonce,
                    },
            }) => {
                assert_eq!(inner, ef);
                assert_eq!(multisig_address, None);
                assert_eq!(replay_protection_nonce, Some(0xdead_beef));
            }
            other => panic!("expected orderless Payload, got {other:?}"),
        }
    }

    #[test]
    fn test_into_orderless_wraps_script() {
        let script = Script::new(vec![0x00], vec![], vec![]);
        let payload = TransactionPayload::Script(script.clone())
            .into_orderless(7)
            .unwrap();

        assert!(matches!(
            payload,
            TransactionPayload::Payload(TransactionPayloadInner::V1 {
                executable: TransactionExecutable::Script(_),
                ..
            })
        ));
    }

    #[test]
    fn test_into_orderless_rejects_multisig() {
        let multisig = Multisig {
            multisig_address: AccountAddress::ONE,
            transaction_payload: None,
        };
        let err = TransactionPayload::Multisig(multisig)
            .into_orderless(1)
            .unwrap_err();
        assert!(matches!(err, crate::error::AptosError::Transaction(_)));
    }

    #[test]
    fn test_script_new() {
        let code = vec![0x01, 0x02, 0x03];
        let type_args = vec![TypeTag::U64];
        let args = vec![ScriptArgument::U64(100)];
        let script = Script::new(code.clone(), type_args.clone(), args);

        assert_eq!(script.code, code);
        assert_eq!(script.type_args.len(), 1);
        assert_eq!(script.args.len(), 1);
    }

    #[test]
    fn test_script_argument_variants() {
        let u8_arg = ScriptArgument::U8(255);
        let u64_arg = ScriptArgument::U64(18_446_744_073_709_551_615);
        let u128_arg = ScriptArgument::U128(340_282_366_920_938_463_463_374_607_431_768_211_455);
        let addr_arg = ScriptArgument::Address(AccountAddress::ONE);
        let bytes_arg = ScriptArgument::U8Vector(vec![1, 2, 3]);
        let bool_arg = ScriptArgument::Bool(true);
        let u16_arg = ScriptArgument::U16(65535);
        let u32_arg = ScriptArgument::U32(4_294_967_295);
        let u256_arg = ScriptArgument::U256([0xff; 32]);
        let serialized_arg = ScriptArgument::Serialized(vec![1, 2, 3]);
        let i64_arg = ScriptArgument::I64(-1i64);

        // Test BCS serialization roundtrip (order matches enum declaration)
        let args = vec![
            u8_arg.clone(),
            u64_arg.clone(),
            u128_arg.clone(),
            addr_arg.clone(),
            bytes_arg.clone(),
            bool_arg.clone(),
            u16_arg.clone(),
            u32_arg.clone(),
            u256_arg.clone(),
            serialized_arg.clone(),
            i64_arg.clone(),
        ];

        for arg in args {
            let serialized = aptos_bcs::to_bytes(&arg).unwrap();
            let deserialized: ScriptArgument = aptos_bcs::from_bytes(&serialized).unwrap();
            assert_eq!(deserialized, arg);
        }
    }

    #[test]
    fn test_transaction_payload_from_entry_function() {
        let entry_fn = EntryFunction::apt_transfer(AccountAddress::ONE, 100).unwrap();
        let payload: TransactionPayload = entry_fn.into();

        match payload {
            TransactionPayload::EntryFunction(ef) => {
                assert_eq!(ef.function, "transfer");
            }
            _ => panic!("Expected EntryFunction variant"),
        }
    }

    #[test]
    fn test_transaction_payload_from_script() {
        let script = Script::new(vec![0x01], vec![], vec![]);
        let payload: TransactionPayload = script.into();

        match payload {
            TransactionPayload::Script(s) => {
                assert_eq!(s.code, vec![0x01]);
            }
            _ => panic!("Expected Script variant"),
        }
    }

    #[test]
    fn test_multisig_payload() {
        let entry_fn = EntryFunction::apt_transfer(AccountAddress::ONE, 100).unwrap();
        let multisig = Multisig {
            multisig_address: AccountAddress::from_hex("0x999").unwrap(),
            transaction_payload: Some(MultisigTransactionPayload::EntryFunction(entry_fn)),
        };

        let payload = TransactionPayload::Multisig(multisig.clone());
        match payload {
            TransactionPayload::Multisig(m) => {
                assert_eq!(m.multisig_address, multisig.multisig_address);
                assert!(m.transaction_payload.is_some());
            }
            _ => panic!("Expected Multisig variant"),
        }
    }

    #[test]
    fn test_entry_function_bcs_serialization() {
        let entry_fn = EntryFunction::apt_transfer(AccountAddress::ONE, 1000).unwrap();
        let serialized = aptos_bcs::to_bytes(&entry_fn).unwrap();
        let deserialized: EntryFunction = aptos_bcs::from_bytes(&serialized).unwrap();

        assert_eq!(entry_fn.module, deserialized.module);
        assert_eq!(entry_fn.function, deserialized.function);
        assert_eq!(entry_fn.type_args, deserialized.type_args);
        assert_eq!(entry_fn.args, deserialized.args);
    }

    #[test]
    fn test_transaction_payload_bcs_serialization() {
        let entry_fn = EntryFunction::apt_transfer(AccountAddress::ONE, 1000).unwrap();
        let payload = TransactionPayload::EntryFunction(entry_fn);

        let serialized = aptos_bcs::to_bytes(&payload).unwrap();
        let deserialized: TransactionPayload = aptos_bcs::from_bytes(&serialized).unwrap();

        assert_eq!(payload, deserialized);
    }

    #[test]
    fn test_from_function_id_invalid() {
        // Missing module separator
        let result = EntryFunction::from_function_id("0x1coin::transfer", vec![], vec![]);
        assert!(result.is_err());

        // Invalid address
        let result = EntryFunction::from_function_id("invalid::module::function", vec![], vec![]);
        assert!(result.is_err());
    }
}