dpp/tokens/token_payment_info/

mod.rs

//! Token payment metadata and helpers.
//!
//! This module defines the versioned `TokenPaymentInfo` wrapper used to describe how a
//! client intends to pay with tokens for an operation (for example, creating,
//! transferring, purchasing, or updating the price of a document/NFT).
//! It captures which token to use, optional price bounds, and who covers gas fees.
//!
//! The enum is versioned to allow future evolution without breaking callers. The
//! current implementation is [`v0::TokenPaymentInfoV0`]. Accessors are provided via
//! [`v0::v0_accessors::TokenPaymentInfoAccessorsV0`], and convenience methods (such
//! as `token_id()` and `is_valid_for_required_cost()`) are available through
//! [`methods::v0::TokenPaymentInfoMethodsV0`].
//!
//! Typical usage:
//!
//! ```ignore
//! use dpp::tokens::gas_fees_paid_by::GasFeesPaidBy;
//! use dpp::data_contract::TokenContractPosition;
//! use dpp::tokens::token_payment_info::{TokenPaymentInfo, v0::TokenPaymentInfoV0};
//!
//! // Client indicates payment preferences for a transition
//! let info: TokenPaymentInfo = TokenPaymentInfoV0 {
//!     // `None` => use a token defined on the current contract
//!     payment_token_contract_id: None,
//!     // Which token (by position/index) on the contract to use
//!     token_contract_position: 0u16,
//!     // Optional bounds to guard against unexpected price changes
//!     minimum_token_cost: None,
//!     maximum_token_cost: Some(1_000u64.into()),
//!     // Who pays gas: user, contract owner, or prefer contract owner
//!     gas_fees_paid_by: GasFeesPaidBy::DocumentOwner,
//! }.into();
//! ```
//!
//! Deserialization from a platform `BTreeMap<String, Value>` requires a
//! `$formatVersion` key. For V0 the map may contain:
//! - `paymentTokenContractId` (`Identifier` as bytes)
//! - `tokenContractPosition` (`u16`)
//! - `minimumTokenCost` (`u64`)
//! - `maximumTokenCost` (`u64`)
//! - `gasFeesPaidBy` (one of: `"DocumentOwner"`, `"ContractOwner"`, `"PreferContractOwner"`)
//!
//! Unknown `$formatVersion` values yield an `UnknownVersionMismatch` error.
//!
use crate::balances::credits::TokenAmount;
use crate::data_contract::TokenContractPosition;
use crate::tokens::gas_fees_paid_by::GasFeesPaidBy;
use crate::tokens::token_payment_info::methods::v0::TokenPaymentInfoMethodsV0;
use crate::tokens::token_payment_info::v0::v0_accessors::TokenPaymentInfoAccessorsV0;
use crate::tokens::token_payment_info::v0::TokenPaymentInfoV0;
use crate::ProtocolError;
use bincode::{Decode, DecodeUntrusted, Encode};
use derive_more::{Display, From};
use platform_serialization_derive::{
    PlatformDeserializeTrusted, PlatformDeserializeUntrusted, PlatformSerialize,
};
use platform_value::btreemap_extensions::BTreeValueMapHelper;
#[cfg(feature = "value-conversion")]
use platform_value::Error;
use platform_value::{Identifier, Value};
#[cfg(feature = "serde-conversion")]
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

pub mod methods;
pub mod v0;

#[derive(
    Debug,
    Clone,
    Copy,
    Encode,
    Decode,
    PlatformDeserializeTrusted,
    PlatformDeserializeUntrusted,
    PlatformSerialize,
    PartialEq,
    Display,
    From,
    DecodeUntrusted,
)]
#[cfg_attr(
    feature = "serde-conversion",
    derive(Serialize, Deserialize),
    serde(tag = "$formatVersion")
)]
/// Versioned container describing how a client intends to pay with tokens.
///
/// The `TokenPaymentInfo` enum allows the protocol to evolve the underlying structure
/// across versions while keeping a stable API for callers. Use the accessor trait
/// [`v0::v0_accessors::TokenPaymentInfoAccessorsV0`] to read or update fields, and
/// [`methods::v0::TokenPaymentInfoMethodsV0`] for helpers like `token_id()` and
/// `is_valid_for_required_cost()`.
///
/// See [`v0::TokenPaymentInfoV0`] for the current set of fields and semantics.
pub enum TokenPaymentInfo {
    #[display("V0({})", "_0")]
    #[cfg_attr(feature = "serde-conversion", serde(rename = "0"))]
    V0(TokenPaymentInfoV0),
}

#[cfg(all(feature = "json-conversion", feature = "serde-conversion"))]
impl crate::serialization::JsonConvertible for TokenPaymentInfo {}

#[cfg(all(feature = "value-conversion", feature = "serde-conversion"))]
impl crate::serialization::ValueConvertible for TokenPaymentInfo {}

impl TokenPaymentInfoMethodsV0 for TokenPaymentInfo {}

impl TokenPaymentInfoAccessorsV0 for TokenPaymentInfo {
    // Getters
    fn payment_token_contract_id(&self) -> Option<Identifier> {
        match self {
            TokenPaymentInfo::V0(v0) => v0.payment_token_contract_id(),
        }
    }

    fn payment_token_contract_id_ref(&self) -> &Option<Identifier> {
        match self {
            TokenPaymentInfo::V0(v0) => v0.payment_token_contract_id_ref(),
        }
    }

    fn token_contract_position(&self) -> TokenContractPosition {
        match self {
            TokenPaymentInfo::V0(v0) => v0.token_contract_position(),
        }
    }

    fn minimum_token_cost(&self) -> Option<TokenAmount> {
        match self {
            TokenPaymentInfo::V0(v0) => v0.minimum_token_cost(),
        }
    }

    fn maximum_token_cost(&self) -> Option<TokenAmount> {
        match self {
            TokenPaymentInfo::V0(v0) => v0.maximum_token_cost(),
        }
    }

    fn gas_fees_paid_by(&self) -> GasFeesPaidBy {
        match self {
            TokenPaymentInfo::V0(v0) => v0.gas_fees_paid_by(),
        }
    }

    // Setters
    fn set_payment_token_contract_id(&mut self, id: Option<Identifier>) {
        match self {
            TokenPaymentInfo::V0(v0) => v0.set_payment_token_contract_id(id),
        }
    }

    fn set_token_contract_position(&mut self, position: TokenContractPosition) {
        match self {
            TokenPaymentInfo::V0(v0) => v0.set_token_contract_position(position),
        }
    }

    fn set_minimum_token_cost(&mut self, cost: Option<TokenAmount>) {
        match self {
            TokenPaymentInfo::V0(v0) => v0.set_minimum_token_cost(cost),
        }
    }

    fn set_maximum_token_cost(&mut self, cost: Option<TokenAmount>) {
        match self {
            TokenPaymentInfo::V0(v0) => v0.set_maximum_token_cost(cost),
        }
    }

    fn set_gas_fees_paid_by(&mut self, payer: GasFeesPaidBy) {
        match self {
            TokenPaymentInfo::V0(v0) => v0.set_gas_fees_paid_by(payer),
        }
    }
}

impl TryFrom<BTreeMap<String, Value>> for TokenPaymentInfo {
    type Error = ProtocolError;

    fn try_from(map: BTreeMap<String, Value>) -> Result<Self, Self::Error> {
        // Expect a `$formatVersion` discriminator and dispatch to the
        // corresponding versioned structure. This allows backward-compatible
        // support for older serialized payloads.
        let format_version = map.get_str("$formatVersion")?;
        match format_version {
            "0" => {
                let token_payment_info: TokenPaymentInfoV0 = map.try_into()?;

                Ok(token_payment_info.into())
            }
            version => Err(ProtocolError::UnknownVersionMismatch {
                method: "TokenPaymentInfo::from_value".to_string(),
                known_versions: vec![0],
                received: version
                    .parse()
                    .map_err(|_| ProtocolError::Generic("Conversion error".to_string()))?,
            }),
        }
    }
}

#[cfg(feature = "value-conversion")]
impl TryFrom<TokenPaymentInfo> for Value {
    type Error = Error;
    /// Serialize the versioned token payment info into a platform `Value`.
    ///
    /// This mirrors the map format accepted by `TryFrom<BTreeMap<String, Value>>`,
    /// including the `$formatVersion` discriminator.
    fn try_from(value: TokenPaymentInfo) -> Result<Self, Self::Error> {
        platform_value::to_value(value)
    }
}

#[cfg(all(
    test,
    feature = "json-conversion",
    feature = "value-conversion",
    feature = "serde-conversion"
))]
mod json_convertible_tests {
    use super::*;
    use platform_value::platform_value;
    use serde_json::json;

    fn fixture() -> TokenPaymentInfo {
        TokenPaymentInfo::V0(TokenPaymentInfoV0 {
            payment_token_contract_id: Some(Identifier::new([0x99; 32])),
            token_contract_position: 3,
            minimum_token_cost: Some(100),
            maximum_token_cost: Some(1_000),
            gas_fees_paid_by: GasFeesPaidBy::ContractOwner,
        })
    }

    #[test]
    fn json_round_trip_with_full_wire_shape() {
        use crate::serialization::JsonConvertible;
        let original = fixture();
        let json = original.to_json().expect("to_json");
        // Internally-tagged enum (`tag = "$formatVersion"`); inner V0 has
        // `rename_all = "camelCase"`. `Identifier` -> base58 in JSON.
        // `token_contract_position` is `TokenContractPosition` (= u16) and
        // `minimum_token_cost` / `maximum_token_cost` are `TokenAmount` (= u64);
        // JSON erases the size — see the value-path assertion for typed locks.
        // `gas_fees_paid_by` is the unit enum `GasFeesPaidBy` and serializes
        // as `"ContractOwner"` (no `rename_all`).
        assert_eq!(
            json,
            json!({
                "$formatVersion": "0",
                "paymentTokenContractId": "BLbDu5FZUdSfLrGejhuaWw5iMJBo3j3TVRyPv9rfJyMA",
                "tokenContractPosition": 3,
                "minimumTokenCost": 100,
                "maximumTokenCost": 1_000,
                "gasFeesPaidBy": "ContractOwner",
            })
        );
        let recovered = TokenPaymentInfo::from_json(json).expect("from_json");
        assert_eq!(original, recovered);
    }

    #[test]
    fn value_round_trip_with_full_wire_shape() {
        use crate::serialization::ValueConvertible;
        let original = fixture();
        let value = original.to_object().expect("to_object");
        // `Identifier` flows as `Value::Identifier` when interpolated.
        // `3u16` locks `Value::U16`; `100u64` / `1_000u64` lock `Value::U64`.
        let payment_token_contract_id = Identifier::new([0x99; 32]);
        assert_eq!(
            value,
            platform_value!({
                "$formatVersion": "0",
                "paymentTokenContractId": payment_token_contract_id,
                "tokenContractPosition": 3u16,
                "minimumTokenCost": 100u64,
                "maximumTokenCost": 1_000u64,
                "gasFeesPaidBy": "ContractOwner",
            })
        );
        let recovered = TokenPaymentInfo::from_object(value).expect("from_object");
        assert_eq!(original, recovered);
    }
}