xrpl_wasm_stdlib/core/current_tx/

traits.rs

//! # Transaction Field Access Traits
//!
//! This module defines traits for accessing fields from XRPL transactions in a type-safe manner.
//! It provides a structured interface for retrieving both common transaction fields (shared across
//! all transaction types) and transaction-specific fields (unique to particular transaction types).
//!
//! ## Overview
//!
//! XRPL transactions contain a variety of fields, some mandatory and others optional. This module
//! organizes field access into logical groups:
//!
//! - **Common Fields**: Fields present in all XRPL transactions (Account, Fee, Sequence, etc.)
//! - **Transaction-Specific Fields**: Fields unique to specific transaction types
//!
//! ## Design Philosophy
//!
//! The trait-based design provides several benefits:
//!
//! - **Type Safety**: Each field is accessed through methods with appropriate return types
//! - **Composability**: Transaction types can implement multiple traits as needed
//! - **Zero-Cost Abstraction**: Trait methods compile down to direct host function calls
//! - **Extensibility**: New transaction types can easily implement the relevant traits
//!
//! ## Field Categories
//!
//! ### Mandatory vs. Optional Fields
//!
//! - **Mandatory fields** return `Result<T>` and will error if missing
//! - **Optional fields** return `Result<Option<T>>` and return `None` if missing
//!
//! ### Field Types
//!
//! - **AccountID**: 20-byte account identifiers
//! - **Hash256**: 256-bit cryptographic hashes
//! - **Amount**: XRP amounts (with future support for tokens)
//! - **u32**: 32-bit unsigned integers for sequence numbers, flags, etc.
//! - **Blob**: Variable-length binary data
//! - **PublicKey**: 33-byte compressed public keys
//! - **TransactionType**: Enumerated transaction type identifiers

use crate::core::current_tx::{get_field, get_field_optional};
use crate::core::types::account_id::AccountID;
use crate::core::types::amount::Amount;
use crate::core::types::blob::Blob;
use crate::core::types::crypto_condition::{Condition, Fulfillment};
use crate::core::types::public_key::PublicKey;
use crate::core::types::transaction_type::TransactionType;
use crate::core::types::uint::Hash256;
use crate::host::error_codes::{
    match_result_code_optional, match_result_code_with_expected_bytes_optional,
};
use crate::host::{Result, get_tx_field};
use crate::sfield;

/// Trait providing access to common fields present in all XRPL transactions.
///
/// ## Implementation Requirements
///
/// Types implementing this trait should ensure they are used only in the context of a valid
/// XRPL transaction. The trait methods assume the current transaction context is properly
/// established by the XRPL Programmability environment.
pub trait TransactionCommonFields {
    /// Retrieves the account field from the current transaction.
    ///
    /// This field identifies (Required) The unique address of the account that initiated the
    /// transaction.
    ///
    /// # Returns
    ///
    /// Returns a `Result<AccountID>` where:
    /// * `Ok(AccountID)` - The 20-byte account identifier of the transaction sender
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    fn get_account(&self) -> Result<AccountID> {
        get_field(sfield::Account)
    }

    /// Retrieves the transaction type from the current transaction.
    ///
    /// This field specifies the type of transaction. Valid transaction types include:
    /// Payment, OfferCreate, TrustSet, and many others.
    ///
    /// # Returns
    ///
    /// Returns a `Result<TransactionType>` where:
    /// * `Ok(TransactionType)` - An enumerated value representing the transaction type
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    ///
    fn get_transaction_type(&self) -> Result<TransactionType> {
        get_field(sfield::TransactionType)
    }

    /// Retrieves the computation allowance from the current transaction.
    ///
    /// This field specifies the maximum computational resources that the transaction is
    /// allowed to consume during execution in the XRPL Programmability environment.
    /// It helps prevent runaway computations and ensures network stability.
    ///
    /// # Returns
    ///
    /// Returns a `Result<u32>` where:
    /// * `Ok(u32)` - The computation allowance value in platform-defined units
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    fn get_computation_allowance(&self) -> Result<u32> {
        get_field(sfield::ComputationAllowance)
    }

    /// Retrieves the fee amount from the current transaction.
    ///
    /// This field specifies the amount of XRP (in drops) that the sender is willing to pay
    /// as a transaction fee. The fee is consumed regardless of whether the transaction
    /// succeeds or fails, and higher fees can improve transaction priority during
    /// network congestion.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Amount>` where:
    /// * `Ok(Amount)` - The fee amount as an XRP amount in drops
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    ///
    /// # Note
    ///
    /// Returns XRP amounts only (for now). Future versions may support other token types
    /// when the underlying amount handling is enhanced.
    fn get_fee(&self) -> Result<Amount> {
        get_field(sfield::Fee)
    }

    /// Retrieves the sequence number from the current transaction.
    ///
    /// This field represents the sequence number of the account sending the transaction. A
    /// transaction is only valid if the Sequence number is exactly 1 greater than the previous
    /// transaction from the same account. The special case 0 means the transaction is using a
    /// Ticket instead (Added by the TicketBatch amendment).
    ///
    /// # Returns
    ///
    /// Returns a `Result<u32>` where:
    /// * `Ok(u32)` - The transaction sequence number
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    ///
    /// # Note
    ///
    /// If the transaction uses tickets instead of sequence numbers, this field may not
    /// be present. In such cases, use `get_ticket_sequence()` instead.
    fn get_sequence(&self) -> Result<u32> {
        get_field(sfield::Sequence)
    }

    /// Retrieves the account transaction ID from the current transaction.
    ///
    /// This optional field contains the hash value identifying another transaction. If provided,
    /// this transaction is only valid if the sending account's previously sent transaction matches
    /// the provided hash.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<Hash256>>` where:
    /// * `Ok(Some(Hash256))` - The hash of the required previous transaction
    /// * `Ok(None)` - If no previous transaction requirement is specified
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_account_txn_id(&self) -> Result<Option<Hash256>> {
        get_field_optional(sfield::AccountTxnID)
    }

    /// Retrieves the `flags` field from the current transaction.
    ///
    /// This optional field contains a bitfield of transaction-specific flags that modify
    /// the transaction's behavior.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<u32>>` where:
    /// * `Ok(Some(u32))` - The flags bitfield if present
    /// * `Ok(None)` - If no flags are specified (equivalent to flags = 0)
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_flags(&self) -> Result<Option<u32>> {
        get_field_optional(sfield::Flags)
    }

    /// Retrieves the last ledger sequence from the current transaction.
    ///
    /// This optional field specifies the highest ledger index this transaction can appear in.
    /// Specifying this field places a strict upper limit on how long the transaction can wait to
    /// be validated or rejected. See Reliable Transaction Submission for more details.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<u32>>` where:
    /// * `Ok(Some(u32))` - The maximum ledger index for transaction inclusion
    /// * `Ok(None)` - If no expiration is specified (transaction never expires)
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_last_ledger_sequence(&self) -> Result<Option<u32>> {
        get_field_optional(sfield::LastLedgerSequence)
    }

    /// Retrieves the network ID from the current transaction.
    ///
    /// This optional field identifies the network ID of the chain this transaction is intended for.
    /// MUST BE OMITTED for Mainnet and some test networks. REQUIRED on chains whose network ID is
    /// 1025 or higher.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<u32>>` where:
    /// * `Ok(Some(u32))` - The network identifier
    /// * `Ok(None)` - If no specific network is specified (uses default network)
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_network_id(&self) -> Result<Option<u32>> {
        get_field_optional(sfield::NetworkID)
    }

    /// Retrieves the source tag from the current transaction.
    ///
    /// This optional field is an arbitrary integer used to identify the reason for this payment, or
    /// a sender on whose behalf this transaction is made. Conventionally, a refund should specify
    /// the initial payment's SourceTag as the refund payment's DestinationTag.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<u32>>` where:
    /// * `Ok(Some(u32))` - The source tag identifier
    /// * `Ok(None)` - If no source tag is specified
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_source_tag(&self) -> Result<Option<u32>> {
        get_field_optional(sfield::SourceTag)
    }

    /// Retrieves the signing public key from the current transaction.
    ///
    /// This field contains the hex representation of the public key that corresponds to the
    /// private key used to sign this transaction. If an empty string, this field indicates that a
    /// multi-signature is present in the Signers field instead.
    ///
    /// # Returns
    ///
    /// Returns a `Result<PublicKey>` where:
    /// * `Ok(PublicKey)` - The 33-byte compressed public key used for signing
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    ///
    /// # Security Note
    ///
    /// The presence of this field doesn't guarantee the signature is valid. Instead, this field
    /// only provides the key claimed to be used for signing. The XRPL network performs signature
    /// validation before transaction execution.
    fn get_signing_pub_key(&self) -> Result<PublicKey> {
        get_field(sfield::SigningPubKey)
    }

    /// Retrieves the ticket sequence from the current transaction.
    ///
    /// This optional field provides the sequence number of the ticket to use in place of a
    /// Sequence number. If this is provided, Sequence must be 0. Cannot be used with AccountTxnID.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<u32>>` where:
    /// * `Ok(Some(u32))` - The ticket sequence number if the transaction uses tickets
    /// * `Ok(None)` - If the transaction uses traditional sequence numbering
    /// * `Err(Error)` - If an error occurred during field retrieval
    ///
    /// # Note
    ///
    /// Transactions use either `Sequence` or `TicketSequence`, but not both. Check this
    /// field when `get_sequence()` fails or when implementing ticket-aware logic.
    fn get_ticket_sequence(&self) -> Result<Option<u32>> {
        get_field_optional(sfield::TicketSequence)
    }

    /// Retrieves the transaction signature from the current transaction.
    ///
    /// This mandatory field contains the signature that verifies this transaction as originating
    /// from the account it says it is from.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Blob>` where:
    /// * `Ok(Blob)` - The transaction signature as variable-length binary data
    /// * `Err(Error)` - If the field cannot be retrieved
    ///
    /// # Security Note
    ///
    /// The signature is validated by the XRPL network before transaction execution.
    /// In the programmability context, you can access the signature for logging or
    /// analysis purposes, but signature validation has already been performed.
    fn get_txn_signature(&self) -> Result<Blob> {
        get_field(sfield::TxnSignature)
    }
}

/// Trait providing access to fields specific to EscrowFinish transactions.
///
/// This trait extends `TransactionCommonFields` with methods for retrieving fields that are
/// unique to EscrowFinish transactions. EscrowFinish transactions are used to complete
/// time-based or condition-based escrows that were previously created with EscrowCreate
/// transactions.
///
/// ## Implementation Requirements
///
/// Types implementing this trait should:
/// - Also implement `TransactionCommonFields` for access to common transaction fields
/// - Only be used in the context of processing EscrowFinish transactions
/// - Ensure proper error handling when accessing conditional fields
pub trait EscrowFinishFields: TransactionCommonFields {
    /// Retrieves the transaction ID (hash) from the current transaction.
    ///
    /// This field provides the unique hash identifier of the current EscrowFinish transaction.
    /// Transaction hashes are deterministically calculated from the transaction contents
    /// and serve as unique identifiers for referencing transactions across the XRPL network.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Hash256>` where:
    /// * `Ok(Hash256)` - The 256-bit transaction hash identifier
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    fn get_id(&self) -> Result<Hash256> {
        get_field(sfield::hash)
    }

    /// Retrieves the owner account from the current EscrowFinish transaction.
    ///
    /// This mandatory field identifies the XRPL account that originally created the escrow
    /// with an EscrowCreate transaction. The owner is the account that deposited the XRP
    /// into the escrow and specified the conditions for its release.
    ///
    /// # Returns
    ///
    /// Returns a `Result<AccountID>` where:
    /// * `Ok(AccountID)` - The 20-byte account identifier of the escrow owner
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    fn get_owner(&self) -> Result<AccountID> {
        get_field(sfield::Owner)
    }

    /// Retrieves the offer sequence from the current EscrowFinish transaction.
    ///
    /// This mandatory field specifies the sequence number of the original EscrowCreate
    /// transaction that created the escrow being finished. This creates a unique reference
    /// to the specific escrow object, as escrows are identified by the combination of
    /// the owner account and the sequence number of the creating transaction.
    ///
    /// # Returns
    ///
    /// Returns a `Result<u32>` where:
    /// * `Ok(u32)` - The sequence number of the EscrowCreate transaction
    /// * `Err(Error)` - If the field cannot be retrieved or has an unexpected size
    fn get_offer_sequence(&self) -> Result<u32> {
        get_field(sfield::OfferSequence)
    }

    /// Retrieves the cryptographic condition from the current EscrowFinish transaction.
    ///
    /// This optional field contains the cryptographic condition specified in the
    /// original EscrowCreate transaction. If present, a valid `Fulfillment` must be provided
    /// in the `Fulfillment` field for the escrow to be successfully finished. Conditions
    /// enable complex release criteria beyond simple time-based locks.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<Condition>>` where:
    /// * `Ok(Some(Condition))` - The 32-byte condition hash if the escrow is conditional
    /// * `Ok(None)` - If the escrow has no cryptographic condition (time-based only)
    /// * `Err(Error)` - If an error occurred during field retrieval
    fn get_condition(&self) -> Result<Option<Condition>> {
        let mut buffer = [0u8; 32];

        let result_code =
            unsafe { get_tx_field(sfield::Condition, buffer.as_mut_ptr(), buffer.len()) };

        match_result_code_with_expected_bytes_optional(result_code, 32, || Some(buffer.into()))
    }

    /// Retrieves the cryptographic fulfillment from the current EscrowFinish transaction.
    ///
    /// This optional field contains the cryptographic fulfillment that satisfies the condition
    /// specified in the original EscrowCreate transaction. The fulfillment must cryptographically
    /// prove that the condition's requirements have been met. This field is only required
    /// when the escrow has an associated condition.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Option<Fulfillment>>` where:
    /// * `Ok(Some(Fulfillment))` - The fulfillment data if provided
    /// * `Ok(None)` - If no fulfillment is provided (valid for unconditional escrows)
    /// * `Err(Error)` - If an error occurred during field retrieval
    ///
    /// # Fulfillment Validation
    ///
    /// The XRPL network automatically validates that:
    /// - The fulfillment satisfies the escrow's condition
    /// - The fulfillment is properly formatted according to RFC 3814
    /// - The cryptographic proof is mathematically valid
    ///
    /// # Size Limits
    ///
    /// Fulfillments are limited to 256 bytes in the current XRPL implementation.
    /// This limit ensures network performance while supporting the most practical
    /// cryptographic proof scenarios.
    fn get_fulfillment(&self) -> Result<Option<Fulfillment>> {
        // Fulfillment fields are limited in rippled to 256 bytes, so we don't use `get_blob_field`
        // but instead just use a smaller buffer directly.

        let mut buffer = [0u8; 256]; // <-- 256 is the current rippled cap.

        let result_code = unsafe { get_tx_field(sfield::Fulfillment, buffer.as_mut_ptr(), 256) };
        match_result_code_optional(result_code, || {
            Some(Fulfillment {
                data: buffer,
                len: result_code as usize,
            })
        })
    }

    // TODO: credential IDS
    // TODO: Signers
}