Struct Payment 

pub struct Payment<M: ManagedTypeApi> {
    pub token_identifier: TokenId<M>,
    pub token_nonce: u64,
    pub amount: NonZeroBigUint<M>,
}

Represents a payment in a specific token with a guaranteed non-zero amount.

A Payment encapsulates all the information needed to represent a token transfer:

• The token identifier (native EGLD or ESDT token)
• The token nonce (0 for fungible tokens, > 0 for NFTs/SFTs)
• The amount (guaranteed to be non-zero)

This type is commonly used in smart contracts for handling incoming payments, storing payment information, and ensuring payment validity through the type system.

Key Features

• Type Safety: The amount is guaranteed to be non-zero through NonZeroBigUint
• Universal Token Support: Works with both native EGLD and ESDT tokens
• NFT/SFT Support: Handles both fungible (nonce=0) and non-fungible tokens (nonce>0)
• Serialization: Supports encoding/decoding for blockchain storage and communication

Examples

// Create a fungible token payment
let usdc_payment = Payment::new(
    TokenId::from("USDC-123456"),
    0,
    NonZeroBigUint::try_from(1000u64)?,
);

// Create an NFT payment
let nft_payment = Payment::try_new(
    "NFT-456789",
    42,
    1u64
)?;

// Check if payment is fungible
assert!(usdc_payment.is_fungible());
assert!(!nft_payment.is_fungible());

See Also

• FungiblePayment for fungible-only payments
• NonZeroBigUint for the amount type constraints

Fields

token_identifier: TokenId<M>

The token identifier (native EGLD or ESDT token)

token_nonce: u64

The token nonce (0 for fungible tokens, > 0 for NFTs/SFTs)

amount: NonZeroBigUint<M>

The payment amount (guaranteed to be non-zero)

Implementations

impl<M: ManagedTypeApi> Payment<M>

pub fn new<T, A>(token_identifier: T, token_nonce: u64, amount: A) -> Self

where T: Into<TokenId<M>>, A: Into<NonZeroBigUint<M>>,

Creates a new Payment with the specified token identifier, nonce, and amount.

This constructor accepts any type that can be converted into a TokenId<M> and any type that can be converted into a NonZeroBigUint<M>, for ergonomic usage.

Arguments

• token_identifier - Any type convertible to TokenId<M> (e.g., &str, String, ManagedBuffer<M>, etc.)
• token_nonce - The token nonce (0 for fungible tokens, > 0 for NFTs/SFTs)
• amount - Any type convertible to NonZeroBigUint<M> (e.g., NonZeroU64)

Examples

let token_id = TokenId::from("USDC-123456");
let amount = NonZero::new(1000u32).unwrap();

// Create a fungible token payment
let payment = Payment::new(token_id, 0, amount);

// Create an NFT payment
let nft_payment = Payment::new("NFT-456789", 42, NonZeroBigUint::one());

pub fn try_new<T, A, E>( token_identifier: T, token_nonce: u64, amount: A, ) -> Result<Self, E>

where T: Into<TokenId<M>>, A: TryInto<NonZeroBigUint<M>, Error = E>,

Attempts to create a new Payment from flexible input types.

This is a more flexible version of Payment::new that accepts arguments implementing Into and TryInto traits, allowing for convenient conversion from various compatible types.

Arguments

• token_identifier - Any type that can be converted into a TokenId<M> (e.g., ManagedBuffer<M>, &str, String, etc.)
• token_nonce - The token nonce (0 for fungible tokens, > 0 for NFTs/SFTs)
• amount - Any type that can be converted into a NonZeroBigUint<M> (e.g., BigUint<M>, u128, ManagedBuffer<M>, etc.)

Returns

• Ok(Payment) - If all conversions succeed and the amount is non-zero
• Err(NonZeroError) - If the amount converts to zero

Examples

let token_id = TokenId::<M>::from("TOKEN-123456");
let amount = BigUint::from(1000u64);

// Create payment from BigUint (might be zero)
let payment = Payment::<M>::try_new(token_id, 0, amount)?;

// Create payment from u128
let payment = Payment::<M>::try_new("USDC-123456", 0, 500u128)?;

pub fn is_fungible(&self) -> bool

pub fn fungible_or_panic(self) -> FungiblePayment<M>

pub fn into_tuple(self) -> (TokenId<M>, u64, NonZeroBigUint<M>)

pub fn as_tuple(&self) -> (&TokenId<M>, u64, &NonZeroBigUint<M>)

pub fn into_egld_or_esdt_payment(self) -> EgldOrEsdtTokenPayment<M>

Zero-cost conversion to the legacy payment type, EgldOrEsdtTokenPayment.

pub fn map_ref_egld_or_esdt<Context, D, F, U>( &self, context: Context, for_egld: D, for_esdt: F, ) -> U

where D: FnOnce(Context, Egld<&BigUint<M>>) -> U, F: FnOnce(Context, EsdtTokenPaymentRefs<'_, M>) -> U,

Same as map_egld_or_esdt, but only takes a reference, and consequently, the closures also only get references.

pub fn map_egld_or_esdt<Context, D, F, U>( self, context: Context, for_egld: D, for_esdt: F, ) -> U

where D: FnOnce(Context, Egld<BigUint<M>>) -> U, F: FnOnce(Context, EsdtTokenPayment<M>) -> U,

pub fn as_refs(&self) -> PaymentRefs<'_, M>

Trait Implementations

impl<M> AsRef<Payment<M>> for &Payment<M>

where M: ManagedTypeApi,

fn as_ref(&self) -> &Payment<M>

Converts this type into a shared reference of the (usually inferred) input type.

impl<M: Clone + ManagedTypeApi> Clone for Payment<M>

fn clone(&self) -> Payment<M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: Debug + ManagedTypeApi> Debug for Payment<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M: ManagedTypeApi, T, A> From<(T, u64, A)> for Payment<M>

where T: Into<TokenId<M>>, A: Into<NonZeroBigUint<M>>,

fn from(value: (T, u64, A)) -> Self

Converts to this type from the input type.

impl<M: ManagedTypeApi> From<Payment<M>> for PaymentVec<M>

fn from(value: Payment<M>) -> Self

Converts to this type from the input type.

impl<M: ManagedTypeApi> From<Payment<M>> for PaymentMultiValue<M>

fn from(obj: Payment<M>) -> Self

Converts to this type from the input type.

impl<M: ManagedTypeApi> IntoMultiValue for Payment<M>

type MultiValue = PaymentMultiValue<M>

fn into_multi_value(self) -> Self::MultiValue

impl<M: ManagedTypeApi> ManagedVecItem for Payment<M>

const SKIPS_RESERIALIZATION: bool = false

If true, then the encoding of the item is identical to the payload, and no further conversion is necessary (the underlying buffer can be used as-is during serialization). False for all managed types, but true for basic types (like u32).

type PAYLOAD = ManagedVecItemPayloadBuffer<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>>

Type managing the underlying binary representation in a ManagedVec..

type Ref<'a> = Ref<'a, Payment<M>>

Reference representation of the ManagedVec item.

fn read_from_payload(payload: &Self::PAYLOAD) -> Self

Parses given bytes as a an owned object.

unsafe fn borrow_from_payload<'a>(payload: &Self::PAYLOAD) -> Self::Ref<'a>

Parses given bytes as a representation of the object, either owned, or a reference.

fn save_to_payload(self, payload: &mut Self::PAYLOAD)

Converts the object into bytes.

fn payload_size() -> usize

impl<M: ManagedTypeApi> NestedDecode for Payment<M>

fn dep_decode_or_handle_err<I, H>( input: &mut I, h: H, ) -> Result<Self, H::HandledErr>

where I: NestedDecodeInput, H: DecodeErrorHandler,

Version of dep_decode that can handle errors as soon as they occur. For instance in can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn dep_decode<I>(input: &mut I) -> Result<Self, DecodeError>

where I: NestedDecodeInput,

Attempt to deserialise the value from input, using the format of an object nested inside another structure. In case of success returns the deserialized value and the number of bytes consumed during the operation.

impl<M: ManagedTypeApi> NestedEncode for Payment<M>

fn dep_encode_or_handle_err<O, H>( &self, __dest__: &mut O, __h__: H, ) -> Result<(), H::HandledErr>

where O: NestedEncodeOutput, H: EncodeErrorHandler,

Version of dep_encode that can handle errors as soon as they occur. For instance in can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn dep_encode<O>(&self, dest: &mut O) -> Result<(), EncodeError>

where O: NestedEncodeOutput,

NestedEncode to output, using the format of an object nested inside another structure. Does not provide compact version.

impl<M: PartialEq + ManagedTypeApi> PartialEq for Payment<M>

fn eq(&self, other: &Payment<M>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M: ManagedTypeApi> TopDecode for Payment<M>

fn top_decode_or_handle_err<I, H>( top_input: I, h: H, ) -> Result<Self, H::HandledErr>

where I: TopDecodeInput, H: DecodeErrorHandler,

Version of top_decode that can handle errors as soon as they occur. For instance it can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn top_decode<I>(input: I) -> Result<Self, DecodeError>

where I: TopDecodeInput,

Attempt to deserialize the value from input.

impl<M: ManagedTypeApi> TopEncode for Payment<M>

fn top_encode_or_handle_err<O, H>( &self, output: O, __h__: H, ) -> Result<(), H::HandledErr>

where O: TopEncodeOutput, H: EncodeErrorHandler,

Version of top_encode that can handle errors as soon as they occur. For instance in can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn top_encode<O>(&self, output: O) -> Result<(), EncodeError>

where O: TopEncodeOutput,

Attempt to serialize the value to output.

impl<Env> TxPayment<Env> for &Payment<Env::Api>

where Env: TxEnv,

fn is_no_payment(&self, _env: &Env) -> bool

Returns true if payment indicates transfer of either non-zero EGLD or ESDT amounts.

fn perform_transfer_execute_fallible( self, env: &Env, to: &ManagedAddress<Env::Api>, gas_limit: u64, fc: FunctionCall<Env::Api>, ) -> Result<(), TransferExecuteFailed>

Transfer-execute calls have different APIs for different payments types. This method selects between them.

fn perform_transfer_execute_legacy( self, env: &Env, to: &ManagedAddress<Env::Api>, gas_limit: u64, fc: FunctionCall<Env::Api>, )

Allows transfer-execute without payment.

fn with_normalized<From, To, F, R>( self, env: &Env, from: &From, to: To, fc: FunctionCall<Env::Api>, f: F, ) -> R

where From: TxFrom<Env>, To: TxToSpecified<Env>, F: FnOnce(&ManagedAddress<Env::Api>, &BigUint<Env::Api>, FunctionCall<Env::Api>) -> R,

Converts an ESDT call to a built-in function call, if necessary.

fn into_scenario_payments(self, env: &Env) -> ScenarioPayments<Env::Api>

Payment data to be used by the testing framework. Will be refactored.

fn perform_transfer_fallible( self, env: &Env, to: &ManagedAddress<Env::Api>, ) -> Result<(), TransferExecuteFailed>

Shortcut for doing direct transfers.

impl<Env> TxPayment<Env> for Payment<Env::Api>

where Env: TxEnv,

fn is_no_payment(&self, env: &Env) -> bool

Returns true if payment indicates transfer of either non-zero EGLD or ESDT amounts.

fn perform_transfer_execute_fallible( self, env: &Env, to: &ManagedAddress<Env::Api>, gas_limit: u64, fc: FunctionCall<Env::Api>, ) -> Result<(), TransferExecuteFailed>

Transfer-execute calls have different APIs for different payments types. This method selects between them.

fn perform_transfer_execute_legacy( self, env: &Env, to: &ManagedAddress<Env::Api>, gas_limit: u64, fc: FunctionCall<Env::Api>, )

Allows transfer-execute without payment.

fn with_normalized<From, To, F, R>( self, env: &Env, from: &From, to: To, fc: FunctionCall<Env::Api>, f: F, ) -> R

where From: TxFrom<Env>, To: TxToSpecified<Env>, F: FnOnce(&ManagedAddress<Env::Api>, &BigUint<Env::Api>, FunctionCall<Env::Api>) -> R,

Converts an ESDT call to a built-in function call, if necessary.

fn into_scenario_payments(self, env: &Env) -> ScenarioPayments<Env::Api>

Payment data to be used by the testing framework. Will be refactored.

fn perform_transfer_fallible( self, env: &Env, to: &ManagedAddress<Env::Api>, ) -> Result<(), TransferExecuteFailed>

Shortcut for doing direct transfers.

impl<Env> TxPaymentCompose<Env, Payment<<Env as TxEnv>::Api>> for PaymentVec<Env::Api>

where Env: TxEnv,

type Output = ManagedVec<<Env as TxEnv>::Api, Payment<<Env as TxEnv>::Api>>

The resulting payment type after composition.

fn compose(self, rhs: Payment<Env::Api>) -> Self::Output

Combines this payment with another payment, returning a new payment object that represents both transfers.

impl<Env> TxPaymentCompose<Env, Payment<<Env as TxEnv>::Api>> for Payment<Env::Api>

where Env: TxEnv,

type Output = ManagedVec<<Env as TxEnv>::Api, Payment<<Env as TxEnv>::Api>>

The resulting payment type after composition.

fn compose(self, rhs: Payment<Env::Api>) -> Self::Output

Combines this payment with another payment, returning a new payment object that represents both transfers.

impl<M: ManagedTypeApi> TypeAbi for Payment<M>

type Unmanaged = Payment<M>

fn type_name() -> TypeName

The type name, as it shows up in the ABI.

fn type_name_rust() -> TypeName

The type name as it shows up in Rust code. Used for proxies.

fn type_names() -> TypeNames

fn type_name_specific() -> Option<TypeName>

Specific name to be optionally added to the ABI.

fn provide_type_descriptions<TDC: TypeDescriptionContainer>( accumulator: &mut TDC, )

A type can provide more than its own name. For instance, a struct can also provide the descriptions of the type of its fields. TypeAbi doesn’t care for the exact accumulator type, which is abstracted by the TypeDescriptionContainer trait.

impl<M: Eq + ManagedTypeApi> Eq for Payment<M>

impl<M: ManagedTypeApi> StructuralPartialEq for Payment<M>

impl<M: ManagedTypeApi> TypeAbiFrom<&Payment<M>> for Payment<M>

impl<M: ManagedTypeApi> TypeAbiFrom<Payment<M>> for Payment<M>