xrpl_common_stdlib/objects/generated/mptoken_issuance.rs
1// GENERATED -- do not hand-edit. Run scripts/generate-ledger-objects.sh to regenerate.
2
3use crate::host::Result;
4use crate::objects::traits::CurrentLedgerObjectCommonFields;
5use crate::objects::traits::LedgerObjectCommonFields;
6use crate::objects::{current_ledger_object, ledger_object};
7use crate::sfield;
8use crate::types::account_id::AccountID;
9use crate::types::blob::StandardBlob;
10use crate::types::uint::Hash256;
11
12/// Trait providing access to fields specific to MPTokenIssuance objects in any ledger.
13pub trait MPTokenIssuanceFields: LedgerObjectCommonFields {
14 /// The address of the account that controls both the issuance amounts and characteristics of a
15 /// particular fungible token.
16 fn issuer(&self) -> Result<AccountID> {
17 ledger_object::get_field(self.get_slot_num(), sfield::Issuer)
18 }
19
20 /// The `Sequence` (or `Ticket`) number of the transaction that created this issuance. This
21 /// helps to uniquely identify the issuance and distinguish it from any other later MPT
22 /// issuances created by this account.
23 fn sequence(&self) -> Result<u32> {
24 ledger_object::get_field(self.get_slot_num(), sfield::Sequence)
25 }
26
27 /// This value specifies the fee, in tenths of a basis point, charged by the issuer for
28 /// secondary sales of the token, if such sales are allowed at all. Valid values for this field
29 /// are between 0 and 50,000 inclusive. A value of 1 is equivalent to 1/10 of a basis point or
30 /// 0.001%, allowing transfer rates between 0% and 50%. A `TransferFee` of 50,000 corresponds to
31 /// 50%. The default value for this field is 0. Any decimals in the transfer fee are rounded
32 /// down. The fee can be rounded down to zero if the payment is small. Issuers should make sure
33 /// that their MPT's `AssetScale` is large enough. <br><br>This field is mutable by default, but
34 /// can be made immutable.
35 fn transfer_fee(&self) -> Result<Option<u16>> {
36 ledger_object::get_field_optional(self.get_slot_num(), sfield::TransferFee)
37 }
38
39 /// A hint indicating which page of the owner directory links to this entry, in case the
40 /// directory consists of multiple pages.
41 fn owner_node(&self) -> Result<u64> {
42 ledger_object::get_field(self.get_slot_num(), sfield::OwnerNode)
43 }
44
45 /// Where to put the decimal place when displaying amounts of this MPT. More formally, the asset
46 /// scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale)
47 /// of a corresponding fractional unit. For example, if a US Dollar Stablecoin has an asset
48 /// scale of _2_, then 1 unit of that MPT would equal 0.01 US Dollars. This indicates to how
49 /// many decimal places the MPT can be subdivided. The default is `0`, meaning that the MPT
50 /// cannot be divided into smaller than 1 unit.
51 fn asset_scale(&self) -> Result<Option<u8>> {
52 ledger_object::get_field_optional(self.get_slot_num(), sfield::AssetScale)
53 }
54
55 /// The maximum number of MPTs that can exist at one time. If omitted, the maximum is currently
56 /// limited to 2^63-1.
57 fn maximum_amount(&self) -> Result<Option<u64>> {
58 ledger_object::get_field_optional(self.get_slot_num(), sfield::MaximumAmount)
59 }
60
61 /// The total amount of MPTs of this issuance currently in circulation. This value increases
62 /// when the issuer sends MPTs to a non-issuer, and decreases whenever the issuer receives MPTs.
63 fn outstanding_amount(&self) -> Result<u64> {
64 ledger_object::get_field(self.get_slot_num(), sfield::OutstandingAmount)
65 }
66
67 /// The amount of tokens currently locked up (for example, in escrow). This amount is already
68 /// included in the `OutstandingAmount`.
69 fn locked_amount(&self) -> Result<Option<u64>> {
70 ledger_object::get_field_optional(self.get_slot_num(), sfield::LockedAmount)
71 }
72
73 /// Arbitrary metadata about this issuance, in hex format. The limit for this field is 1024
74 /// bytes. <br><br>This field is mutable by default, but can be made immutable.
75 fn mptoken_metadata(&self) -> Result<Option<StandardBlob>> {
76 ledger_object::get_field_optional(self.get_slot_num(), sfield::MPTokenMetadata)
77 }
78
79 /// The identifying hash of the transaction that most recently modified this entry.
80 fn previous_txn_id(&self) -> Result<Hash256> {
81 ledger_object::get_field(self.get_slot_num(), sfield::PreviousTxnID)
82 }
83
84 /// The index of the ledger that contains the transaction that most recently modified this
85 /// object.
86 fn previous_txn_lgr_seq(&self) -> Result<u32> {
87 ledger_object::get_field(self.get_slot_num(), sfield::PreviousTxnLgrSeq)
88 }
89
90 /// The ledger entry ID of a permissioned domain that grants access to the MPT. This field is
91 /// _always_ mutable.
92 fn domain_id(&self) -> Result<Option<Hash256>> {
93 ledger_object::get_field_optional(self.get_slot_num(), sfield::DomainID)
94 }
95
96 /// Indicates which fields and flags are immutable for this MPT issuance. Any field or flag not
97 /// represented here remains mutable. See MPTokenIssuance Immutable Flags.
98 fn immutable_flags(&self) -> Result<Option<u32>> {
99 ledger_object::get_field_optional(self.get_slot_num(), sfield::ImmutableFlags)
100 }
101
102 /// The ReferenceHolding field (Optional).
103 fn reference_holding(&self) -> Result<Option<Hash256>> {
104 ledger_object::get_field_optional(self.get_slot_num(), sfield::ReferenceHolding)
105 }
106
107 /// A 33-byte compressed ElGamal public key for the issuer.
108 fn issuer_encryption_key(&self) -> Result<Option<StandardBlob>> {
109 ledger_object::get_field_optional(self.get_slot_num(), sfield::IssuerEncryptionKey)
110 }
111
112 /// A 33-byte compressed ElGamal public key for an optional on-chain auditor.
113 fn auditor_encryption_key(&self) -> Result<Option<StandardBlob>> {
114 ledger_object::get_field_optional(self.get_slot_num(), sfield::AuditorEncryptionKey)
115 }
116
117 /// The total amount of this token that is currently held in confidential balances.
118 fn confidential_outstanding_amount(&self) -> Result<Option<u64>> {
119 ledger_object::get_field_optional(
120 self.get_slot_num(),
121 sfield::ConfidentialOutstandingAmount,
122 )
123 }
124}
125
126/// Trait providing access to fields specific to the current MPTokenIssuance object.
127pub trait CurrentMPTokenIssuanceFields: CurrentLedgerObjectCommonFields {
128 /// The address of the account that controls both the issuance amounts and characteristics of a
129 /// particular fungible token.
130 fn issuer(&self) -> Result<AccountID> {
131 current_ledger_object::get_field(sfield::Issuer)
132 }
133
134 /// The `Sequence` (or `Ticket`) number of the transaction that created this issuance. This
135 /// helps to uniquely identify the issuance and distinguish it from any other later MPT
136 /// issuances created by this account.
137 fn sequence(&self) -> Result<u32> {
138 current_ledger_object::get_field(sfield::Sequence)
139 }
140
141 /// This value specifies the fee, in tenths of a basis point, charged by the issuer for
142 /// secondary sales of the token, if such sales are allowed at all. Valid values for this field
143 /// are between 0 and 50,000 inclusive. A value of 1 is equivalent to 1/10 of a basis point or
144 /// 0.001%, allowing transfer rates between 0% and 50%. A `TransferFee` of 50,000 corresponds to
145 /// 50%. The default value for this field is 0. Any decimals in the transfer fee are rounded
146 /// down. The fee can be rounded down to zero if the payment is small. Issuers should make sure
147 /// that their MPT's `AssetScale` is large enough. <br><br>This field is mutable by default, but
148 /// can be made immutable.
149 fn transfer_fee(&self) -> Result<Option<u16>> {
150 current_ledger_object::get_field_optional(sfield::TransferFee)
151 }
152
153 /// A hint indicating which page of the owner directory links to this entry, in case the
154 /// directory consists of multiple pages.
155 fn owner_node(&self) -> Result<u64> {
156 current_ledger_object::get_field(sfield::OwnerNode)
157 }
158
159 /// Where to put the decimal place when displaying amounts of this MPT. More formally, the asset
160 /// scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale)
161 /// of a corresponding fractional unit. For example, if a US Dollar Stablecoin has an asset
162 /// scale of _2_, then 1 unit of that MPT would equal 0.01 US Dollars. This indicates to how
163 /// many decimal places the MPT can be subdivided. The default is `0`, meaning that the MPT
164 /// cannot be divided into smaller than 1 unit.
165 fn asset_scale(&self) -> Result<Option<u8>> {
166 current_ledger_object::get_field_optional(sfield::AssetScale)
167 }
168
169 /// The maximum number of MPTs that can exist at one time. If omitted, the maximum is currently
170 /// limited to 2^63-1.
171 fn maximum_amount(&self) -> Result<Option<u64>> {
172 current_ledger_object::get_field_optional(sfield::MaximumAmount)
173 }
174
175 /// The total amount of MPTs of this issuance currently in circulation. This value increases
176 /// when the issuer sends MPTs to a non-issuer, and decreases whenever the issuer receives MPTs.
177 fn outstanding_amount(&self) -> Result<u64> {
178 current_ledger_object::get_field(sfield::OutstandingAmount)
179 }
180
181 /// The amount of tokens currently locked up (for example, in escrow). This amount is already
182 /// included in the `OutstandingAmount`.
183 fn locked_amount(&self) -> Result<Option<u64>> {
184 current_ledger_object::get_field_optional(sfield::LockedAmount)
185 }
186
187 /// Arbitrary metadata about this issuance, in hex format. The limit for this field is 1024
188 /// bytes. <br><br>This field is mutable by default, but can be made immutable.
189 fn mptoken_metadata(&self) -> Result<Option<StandardBlob>> {
190 current_ledger_object::get_field_optional(sfield::MPTokenMetadata)
191 }
192
193 /// The identifying hash of the transaction that most recently modified this entry.
194 fn previous_txn_id(&self) -> Result<Hash256> {
195 current_ledger_object::get_field(sfield::PreviousTxnID)
196 }
197
198 /// The index of the ledger that contains the transaction that most recently modified this
199 /// object.
200 fn previous_txn_lgr_seq(&self) -> Result<u32> {
201 current_ledger_object::get_field(sfield::PreviousTxnLgrSeq)
202 }
203
204 /// The ledger entry ID of a permissioned domain that grants access to the MPT. This field is
205 /// _always_ mutable.
206 fn domain_id(&self) -> Result<Option<Hash256>> {
207 current_ledger_object::get_field_optional(sfield::DomainID)
208 }
209
210 /// Indicates which fields and flags are immutable for this MPT issuance. Any field or flag not
211 /// represented here remains mutable. See MPTokenIssuance Immutable Flags.
212 fn immutable_flags(&self) -> Result<Option<u32>> {
213 current_ledger_object::get_field_optional(sfield::ImmutableFlags)
214 }
215
216 /// The ReferenceHolding field (Optional).
217 fn reference_holding(&self) -> Result<Option<Hash256>> {
218 current_ledger_object::get_field_optional(sfield::ReferenceHolding)
219 }
220
221 /// A 33-byte compressed ElGamal public key for the issuer.
222 fn issuer_encryption_key(&self) -> Result<Option<StandardBlob>> {
223 current_ledger_object::get_field_optional(sfield::IssuerEncryptionKey)
224 }
225
226 /// A 33-byte compressed ElGamal public key for an optional on-chain auditor.
227 fn auditor_encryption_key(&self) -> Result<Option<StandardBlob>> {
228 current_ledger_object::get_field_optional(sfield::AuditorEncryptionKey)
229 }
230
231 /// The total amount of this token that is currently held in confidential balances.
232 fn confidential_outstanding_amount(&self) -> Result<Option<u64>> {
233 current_ledger_object::get_field_optional(sfield::ConfidentialOutstandingAmount)
234 }
235}
236
237#[derive(Debug, Clone, Copy, Eq, PartialEq)]
238pub struct MPTokenIssuance {
239 pub(crate) slot_num: i32,
240}
241
242impl MPTokenIssuance {
243 /// Binds this handle to a host-managed slot holding a MPTokenIssuance ledger object.
244 pub fn new(slot_num: i32) -> Self {
245 Self { slot_num }
246 }
247}
248
249impl LedgerObjectCommonFields for MPTokenIssuance {
250 fn get_slot_num(&self) -> i32 {
251 self.slot_num
252 }
253}
254
255impl MPTokenIssuanceFields for MPTokenIssuance {}
256
257#[cfg(test)]
258mod tests {
259 use super::*;
260 use crate::host::host_bindings_trait::MockHostBindings;
261 use crate::host::setup_mock;
262 use crate::objects::test_utils::*;
263
264 #[test]
265 fn read_all_fields() {
266 let mut mock = MockHostBindings::new();
267 mock_all_fields_present(&mut mock);
268 let _guard = setup_mock(mock);
269
270 let obj = MPTokenIssuance::new(0);
271
272 assert!(obj.issuer().is_ok());
273 assert!(obj.sequence().is_ok());
274 assert!(obj.owner_node().is_ok());
275 assert!(obj.outstanding_amount().is_ok());
276 assert!(obj.previous_txn_id().is_ok());
277 assert!(obj.previous_txn_lgr_seq().is_ok());
278 assert!(obj.transfer_fee().is_ok());
279 assert!(obj.asset_scale().is_ok());
280 assert!(obj.maximum_amount().is_ok());
281 assert!(obj.locked_amount().is_ok());
282 assert!(obj.mptoken_metadata().is_ok());
283 assert!(obj.domain_id().is_ok());
284 assert!(obj.immutable_flags().is_ok());
285 assert!(obj.reference_holding().is_ok());
286 assert!(obj.issuer_encryption_key().is_ok());
287 assert!(obj.auditor_encryption_key().is_ok());
288 assert!(obj.confidential_outstanding_amount().is_ok());
289 }
290
291 #[test]
292 fn optional_fields_none() {
293 let mut mock = MockHostBindings::new();
294 mock_all_fields_not_found(&mut mock);
295 let _guard = setup_mock(mock);
296
297 let obj = MPTokenIssuance::new(0);
298
299 assert!(obj.transfer_fee().unwrap().is_none());
300 assert!(obj.asset_scale().unwrap().is_none());
301 assert!(obj.maximum_amount().unwrap().is_none());
302 assert!(obj.locked_amount().unwrap().is_none());
303 assert!(obj.domain_id().unwrap().is_none());
304 assert!(obj.immutable_flags().unwrap().is_none());
305 assert!(obj.reference_holding().unwrap().is_none());
306 assert!(obj.confidential_outstanding_amount().unwrap().is_none());
307 }
308}