sui_sdk_types/transaction/
mod.rs

1use crate::Digest;
2
3use super::Address;
4use super::CheckpointTimestamp;
5use super::ConsensusCommitDigest;
6use super::EpochId;
7use super::GenesisObject;
8use super::Identifier;
9use super::Jwk;
10use super::JwkId;
11use super::ObjectId;
12use super::ObjectReference;
13use super::ProtocolVersion;
14use super::TransactionDigest;
15use super::TypeTag;
16use super::UserSignature;
17use super::Version;
18
19#[cfg(feature = "serde")]
20#[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
21mod serialization;
22#[cfg(feature = "serde")]
23#[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
24pub(crate) use serialization::SignedTransactionWithIntentMessage;
25
26/// A transaction
27///
28/// # BCS
29///
30/// The BCS serialized form for this type is defined by the following ABNF:
31///
32/// ```text
33/// transaction = %x00 transaction-v1
34///
35/// transaction-v1 = transaction-kind address gas-payment transaction-expiration
36/// ```
37#[derive(Clone, Debug, PartialEq, Eq)]
38#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
39pub struct Transaction {
40    pub kind: TransactionKind,
41    pub sender: Address,
42    pub gas_payment: GasPayment,
43    pub expiration: TransactionExpiration,
44}
45
46#[derive(Clone, Debug, PartialEq, Eq)]
47#[cfg_attr(
48    feature = "serde",
49    derive(serde_derive::Serialize, serde_derive::Deserialize)
50)]
51#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
52pub struct SignedTransaction {
53    pub transaction: Transaction,
54    pub signatures: Vec<UserSignature>,
55}
56
57/// A TTL for a transaction
58///
59/// # BCS
60///
61/// The BCS serialized form for this type is defined by the following ABNF:
62///
63/// ```text
64/// transaction-expiration =  %x00      ; none
65///                        =/ %x01 u64  ; epoch
66/// ```
67#[derive(Clone, Copy, Default, Debug, PartialEq, Eq, Hash)]
68#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
69pub enum TransactionExpiration {
70    /// The transaction has no expiration
71    #[default]
72    None,
73
74    /// Validators wont sign a transaction unless the expiration Epoch
75    /// is greater than or equal to the current epoch
76    Epoch(EpochId),
77}
78
79/// Payment information for executing a transaction
80///
81/// # BCS
82///
83/// The BCS serialized form for this type is defined by the following ABNF:
84///
85/// ```text
86/// gas-payment = (vector object-ref) ; gas coin objects
87///               address             ; owner
88///               u64                 ; price
89///               u64                 ; budget
90/// ```
91#[derive(Clone, Debug, PartialEq, Eq)]
92#[cfg_attr(
93    feature = "serde",
94    derive(serde_derive::Serialize, serde_derive::Deserialize)
95)]
96#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
97pub struct GasPayment {
98    pub objects: Vec<ObjectReference>,
99
100    /// Owner of the gas objects, either the transaction sender or a sponsor
101    pub owner: Address,
102
103    /// Gas unit price to use when charging for computation
104    ///
105    /// Must be greater-than-or-equal-to the network's current RGP (reference gas price)
106    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
107    pub price: u64,
108
109    /// Total budget willing to spend for the execution of a transaction
110    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
111    pub budget: u64,
112}
113
114/// Randomness update
115///
116/// # BCS
117///
118/// The BCS serialized form for this type is defined by the following ABNF:
119///
120/// ```text
121/// randomness-state-update = u64 u64 bytes u64
122/// ```
123#[derive(Clone, Debug, PartialEq, Eq)]
124#[cfg_attr(
125    feature = "serde",
126    derive(serde_derive::Serialize, serde_derive::Deserialize)
127)]
128#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
129pub struct RandomnessStateUpdate {
130    /// Epoch of the randomness state update transaction
131    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
132    pub epoch: u64,
133
134    /// Randomness round of the update
135    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
136    pub randomness_round: u64,
137
138    /// Updated random bytes
139    #[cfg_attr(
140        feature = "serde",
141        serde(with = "crate::_serde::ReadableBase64Encoded")
142    )]
143    pub random_bytes: Vec<u8>,
144
145    /// The initial version of the randomness object that it was shared at.
146    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
147    pub randomness_obj_initial_shared_version: u64,
148}
149
150/// Transaction type
151///
152/// # BCS
153///
154/// The BCS serialized form for this type is defined by the following ABNF:
155///
156/// ```text
157/// transaction-kind    =  %x00 ptb
158///                     =/ %x01 change-epoch
159///                     =/ %x02 genesis-transaction
160///                     =/ %x03 consensus-commit-prologue
161///                     =/ %x04 authenticator-state-update
162///                     =/ %x05 (vector end-of-epoch-transaction-kind)
163///                     =/ %x06 randomness-state-update
164///                     =/ %x07 consensus-commit-prologue-v2
165///                     =/ %x08 consensus-commit-prologue-v3
166///                     =/ %x09 consensus-commit-prologue-v4
167/// ```
168#[derive(Clone, Debug, PartialEq, Eq)]
169#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
170pub enum TransactionKind {
171    /// A user transaction comprised of a list of native commands and move calls
172    ProgrammableTransaction(ProgrammableTransaction),
173
174    /// System transaction used to end an epoch.
175    ///
176    /// The ChangeEpoch variant is now deprecated (but the ChangeEpoch struct is still used by
177    /// EndOfEpochTransaction below).
178    ChangeEpoch(ChangeEpoch),
179
180    /// Transaction used to initialize the chain state.
181    ///
182    /// Only valid if in the genesis checkpoint (0) and if this is the very first transaction ever
183    /// executed on the chain.
184    Genesis(GenesisTransaction),
185
186    /// V1 consensus commit update
187    ConsensusCommitPrologue(ConsensusCommitPrologue),
188
189    /// Update set of valid JWKs used for zklogin
190    AuthenticatorStateUpdate(AuthenticatorStateUpdate),
191
192    /// Set of operations to run at the end of the epoch to close out the current epoch and start
193    /// the next one.
194    EndOfEpoch(Vec<EndOfEpochTransactionKind>),
195
196    /// Randomness update
197    RandomnessStateUpdate(RandomnessStateUpdate),
198
199    /// V2 consensus commit update
200    ConsensusCommitPrologueV2(ConsensusCommitPrologueV2),
201
202    /// V3 consensus commit update
203    ConsensusCommitPrologueV3(ConsensusCommitPrologueV3),
204
205    /// V4 consensus commit update
206    ConsensusCommitPrologueV4(ConsensusCommitPrologueV4),
207}
208
209/// Operation run at the end of an epoch
210///
211/// # BCS
212///
213/// The BCS serialized form for this type is defined by the following ABNF:
214///
215/// ```text
216/// end-of-epoch-transaction-kind   =  eoe-change-epoch
217///                                 =/ eoe-authenticator-state-create
218///                                 =/ eoe-authenticator-state-expire
219///                                 =/ eoe-randomness-state-create
220///                                 =/ eoe-deny-list-state-create
221///                                 =/ eoe-bridge-state-create
222///                                 =/ eoe-bridge-committee-init
223///                                 =/ eoe-store-execution-time-observations
224///
225/// eoe-change-epoch                = %x00 change-epoch
226/// eoe-authenticator-state-create  = %x01
227/// eoe-authenticator-state-expire  = %x02 authenticator-state-expire
228/// eoe-randomness-state-create     = %x03
229/// eoe-deny-list-state-create      = %x04
230/// eoe-bridge-state-create         = %x05 digest
231/// eoe-bridge-committee-init       = %x06 u64
232/// eoe-store-execution-time-observations = %x07 stored-execution-time-observations
233/// ```
234#[derive(Clone, Debug, PartialEq, Eq)]
235#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
236pub enum EndOfEpochTransactionKind {
237    /// End the epoch and start the next one
238    ChangeEpoch(ChangeEpoch),
239
240    /// Create and initialize the authenticator object used for zklogin
241    AuthenticatorStateCreate,
242
243    /// Expire JWKs used for zklogin
244    AuthenticatorStateExpire(AuthenticatorStateExpire),
245
246    /// Create and initialize the randomness object
247    RandomnessStateCreate,
248
249    /// Create and initialize the deny list object
250    DenyListStateCreate,
251
252    /// Create and initialize the bridge object
253    BridgeStateCreate { chain_id: super::CheckpointDigest },
254
255    /// Initialize the bridge committee
256    BridgeCommitteeInit { bridge_object_version: u64 },
257
258    /// Execution time observations from the committee to preserve cross epoch
259    StoreExecutionTimeObservations(ExecutionTimeObservations),
260}
261
262/// Set of Execution Time Observations from the committee.
263///
264/// # BCS
265///
266/// The BCS serialized form for this type is defined by the following ABNF:
267///
268/// ```text
269/// stored-execution-time-observations =  %x00 v1-stored-execution-time-observations
270///
271/// v1-stored-execution-time-observations = (vec
272///                                          execution-time-observation-key
273///                                          (vec execution-time-observation)
274///                                         )
275/// ```
276#[derive(Debug, Hash, PartialEq, Eq, Clone)]
277#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
278#[cfg_attr(
279    feature = "serde",
280    derive(serde_derive::Serialize, serde_derive::Deserialize)
281)]
282pub enum ExecutionTimeObservations {
283    V1(
284        Vec<(
285            ExecutionTimeObservationKey,
286            Vec<ValidatorExecutionTimeObservation>,
287        )>,
288    ),
289}
290
291/// An execution time observation from a particular validator
292///
293/// # BCS
294///
295/// The BCS serialized form for this type is defined by the following ABNF:
296///
297/// ```text
298/// execution-time-observation = bls-public-key duration
299/// duration =  u64 ; seconds
300///             u32 ; subsecond nanoseconds
301/// ```
302#[derive(Debug, Hash, PartialEq, Eq, Clone)]
303#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
304#[cfg_attr(
305    feature = "serde",
306    derive(serde_derive::Serialize, serde_derive::Deserialize)
307)]
308pub struct ValidatorExecutionTimeObservation {
309    pub validator: crate::Bls12381PublicKey,
310    pub duration: std::time::Duration,
311}
312
313/// Key for an execution time observation
314///
315/// # BCS
316///
317/// The BCS serialized form for this type is defined by the following ABNF:
318///
319/// ```text
320/// execution-time-observation-key  =  %x00 move-entry-point
321///                                 =/ %x01 ; transfer-objects
322///                                 =/ %x02 ; split-coins
323///                                 =/ %x03 ; merge-coins
324///                                 =/ %x04 ; publish
325///                                 =/ %x05 ; make-move-vec
326///                                 =/ %x06 ; upgrade
327///
328/// move-entry-point = object-id string string (vec type-tag)
329/// ```
330#[derive(Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Clone)]
331#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
332#[cfg_attr(
333    feature = "serde",
334    derive(serde_derive::Serialize, serde_derive::Deserialize)
335)]
336pub enum ExecutionTimeObservationKey {
337    // Containts all the fields from `ProgrammableMoveCall` besides `arguments`.
338    MoveEntryPoint {
339        /// The package containing the module and function.
340        package: ObjectId,
341        /// The specific module in the package containing the function.
342        module: String,
343        /// The function to be called.
344        function: String,
345        /// The type arguments to the function.
346        /// NOTE: This field is currently not populated.
347        type_arguments: Vec<TypeTag>,
348    },
349    TransferObjects,
350    SplitCoins,
351    MergeCoins,
352    Publish, // special case: should not be used; we only use hard-coded estimate for this
353    MakeMoveVec,
354    Upgrade,
355}
356
357/// Expire old JWKs
358///
359/// # BCS
360///
361/// The BCS serialized form for this type is defined by the following ABNF:
362///
363/// ```text
364/// authenticator-state-expire = u64 u64
365/// ```
366#[derive(Clone, Debug, PartialEq, Eq)]
367#[cfg_attr(
368    feature = "serde",
369    derive(serde_derive::Serialize, serde_derive::Deserialize)
370)]
371#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
372pub struct AuthenticatorStateExpire {
373    /// expire JWKs that have a lower epoch than this
374    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
375    pub min_epoch: u64,
376
377    /// The initial version of the authenticator object that it was shared at.
378    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
379    pub authenticator_object_initial_shared_version: u64,
380}
381
382/// Update the set of valid JWKs
383///
384/// # BCS
385///
386/// The BCS serialized form for this type is defined by the following ABNF:
387///
388/// ```text
389/// authenticator-state-update = u64 ; epoch
390///                              u64 ; round
391///                              (vector active-jwk)
392///                              u64 ; initial version of the authenticator object
393/// ```
394#[derive(Clone, Debug, PartialEq, Eq)]
395#[cfg_attr(
396    feature = "serde",
397    derive(serde_derive::Serialize, serde_derive::Deserialize)
398)]
399#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
400pub struct AuthenticatorStateUpdate {
401    /// Epoch of the authenticator state update transaction
402    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
403    pub epoch: u64,
404
405    /// Consensus round of the authenticator state update
406    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
407    pub round: u64,
408
409    /// newly active jwks
410    pub new_active_jwks: Vec<ActiveJwk>,
411
412    /// The initial version of the authenticator object that it was shared at.
413    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
414    pub authenticator_obj_initial_shared_version: u64,
415}
416
417/// A new Jwk
418///
419/// # BCS
420///
421/// The BCS serialized form for this type is defined by the following ABNF:
422///
423/// ```text
424/// active-jwk = jwk-id jwk u64
425/// ```
426#[derive(Clone, Debug, PartialEq, Eq)]
427#[cfg_attr(
428    feature = "serde",
429    derive(serde_derive::Serialize, serde_derive::Deserialize)
430)]
431#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
432pub struct ActiveJwk {
433    /// Identifier used to uniquely identify a Jwk
434    pub jwk_id: JwkId,
435
436    /// The Jwk
437    pub jwk: Jwk,
438
439    /// Most recent epoch in which the jwk was validated
440    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
441    pub epoch: u64,
442}
443
444/// V1 of the consensus commit prologue system transaction
445///
446/// # BCS
447///
448/// The BCS serialized form for this type is defined by the following ABNF:
449///
450/// ```text
451/// consensus-commit-prologue = u64 u64 u64
452/// ```
453#[derive(Clone, Debug, PartialEq, Eq)]
454#[cfg_attr(
455    feature = "serde",
456    derive(serde_derive::Serialize, serde_derive::Deserialize)
457)]
458#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
459pub struct ConsensusCommitPrologue {
460    /// Epoch of the commit prologue transaction
461    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
462    pub epoch: u64,
463
464    /// Consensus round of the commit
465    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
466    pub round: u64,
467
468    /// Unix timestamp from consensus
469    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
470    pub commit_timestamp_ms: CheckpointTimestamp,
471}
472
473/// V2 of the consensus commit prologue system transaction
474///
475/// # BCS
476///
477/// The BCS serialized form for this type is defined by the following ABNF:
478///
479/// ```text
480/// consensus-commit-prologue-v2 = u64 u64 u64 digest
481/// ```
482#[derive(Clone, Debug, PartialEq, Eq)]
483#[cfg_attr(
484    feature = "serde",
485    derive(serde_derive::Serialize, serde_derive::Deserialize)
486)]
487#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
488pub struct ConsensusCommitPrologueV2 {
489    /// Epoch of the commit prologue transaction
490    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
491    pub epoch: u64,
492
493    /// Consensus round of the commit
494    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
495    pub round: u64,
496
497    /// Unix timestamp from consensus
498    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
499    pub commit_timestamp_ms: CheckpointTimestamp,
500
501    /// Digest of consensus output
502    pub consensus_commit_digest: ConsensusCommitDigest,
503}
504
505/// Version assignments performed by consensus
506///
507/// # BCS
508///
509/// The BCS serialized form for this type is defined by the following ABNF:
510///
511/// ```text
512/// consensus-determined-version-assignments = canceled-transactions
513///
514/// canceled-transactions = %x00 (vector canceled-transaction)
515/// ```
516#[derive(Clone, Debug, PartialEq, Eq)]
517#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
518pub enum ConsensusDeterminedVersionAssignments {
519    /// Canceled transaction version assignment.
520    CanceledTransactions {
521        #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
522        canceled_transactions: Vec<CanceledTransaction>,
523    },
524}
525
526/// A transaction that was canceled
527///
528/// # BCS
529///
530/// The BCS serialized form for this type is defined by the following ABNF:
531///
532/// ```text
533/// canceled-transaction = digest (vector version-assignment)
534/// ```
535#[derive(Clone, Debug, PartialEq, Eq)]
536#[cfg_attr(
537    feature = "serde",
538    derive(serde_derive::Serialize, serde_derive::Deserialize)
539)]
540#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
541pub struct CanceledTransaction {
542    pub digest: TransactionDigest,
543    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
544    pub version_assignments: Vec<VersionAssignment>,
545}
546
547/// Object version assignment from consensus
548///
549/// # BCS
550///
551/// The BCS serialized form for this type is defined by the following ABNF:
552///
553/// ```text
554/// version-assignment = object-id u64
555/// ```
556#[derive(Clone, Debug, PartialEq, Eq)]
557#[cfg_attr(
558    feature = "serde",
559    derive(serde_derive::Serialize, serde_derive::Deserialize)
560)]
561#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
562pub struct VersionAssignment {
563    pub object_id: ObjectId,
564    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
565    pub version: Version,
566}
567
568/// V3 of the consensus commit prologue system transaction
569///
570/// # BCS
571///
572/// The BCS serialized form for this type is defined by the following ABNF:
573///
574/// ```text
575/// consensus-commit-prologue-v3 = u64 u64 (option u64) u64 digest
576///                                consensus-determined-version-assignments
577/// ```
578#[derive(Clone, Debug, PartialEq, Eq)]
579#[cfg_attr(
580    feature = "serde",
581    derive(serde_derive::Serialize, serde_derive::Deserialize)
582)]
583#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
584pub struct ConsensusCommitPrologueV3 {
585    /// Epoch of the commit prologue transaction
586    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
587    pub epoch: u64,
588
589    /// Consensus round of the commit
590    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
591    pub round: u64,
592
593    /// The sub DAG index of the consensus commit. This field will be populated if there
594    /// are multiple consensus commits per round.
595    #[cfg_attr(
596        feature = "serde",
597        serde(with = "crate::_serde::OptionReadableDisplay")
598    )]
599    pub sub_dag_index: Option<u64>,
600
601    /// Unix timestamp from consensus
602    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
603    pub commit_timestamp_ms: CheckpointTimestamp,
604
605    /// Digest of consensus output
606    pub consensus_commit_digest: ConsensusCommitDigest,
607
608    /// Stores consensus handler determined shared object version assignments.
609    pub consensus_determined_version_assignments: ConsensusDeterminedVersionAssignments,
610}
611
612/// V4 of the consensus commit prologue system transaction
613///
614/// # BCS
615///
616/// The BCS serialized form for this type is defined by the following ABNF:
617///
618/// ```text
619/// consensus-commit-prologue-v4 = u64 u64 (option u64) u64 digest
620///                                consensus-determined-version-assignments
621///                                digest
622/// ```
623#[derive(Clone, Debug, PartialEq, Eq)]
624#[cfg_attr(
625    feature = "serde",
626    derive(serde_derive::Serialize, serde_derive::Deserialize)
627)]
628#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
629pub struct ConsensusCommitPrologueV4 {
630    /// Epoch of the commit prologue transaction
631    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
632    pub epoch: u64,
633
634    /// Consensus round of the commit
635    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
636    pub round: u64,
637
638    /// The sub DAG index of the consensus commit. This field will be populated if there
639    /// are multiple consensus commits per round.
640    #[cfg_attr(
641        feature = "serde",
642        serde(with = "crate::_serde::OptionReadableDisplay")
643    )]
644    pub sub_dag_index: Option<u64>,
645
646    /// Unix timestamp from consensus
647    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
648    pub commit_timestamp_ms: CheckpointTimestamp,
649
650    /// Digest of consensus output
651    pub consensus_commit_digest: ConsensusCommitDigest,
652
653    /// Stores consensus handler determined shared object version assignments.
654    pub consensus_determined_version_assignments: ConsensusDeterminedVersionAssignments,
655
656    /// Digest of any additional state computed by the consensus handler.
657    /// Used to detect forking bugs as early as possible.
658    pub additional_state_digest: Digest,
659}
660
661/// System transaction used to change the epoch
662///
663/// # BCS
664///
665/// The BCS serialized form for this type is defined by the following ABNF:
666///
667/// ```text
668/// change-epoch = u64  ; next epoch
669///                u64  ; protocol version
670///                u64  ; storage charge
671///                u64  ; computation charge
672///                u64  ; storage rebate
673///                u64  ; non-refundable storage fee
674///                u64  ; epoch start timestamp
675///                (vector system-package)
676/// ```
677#[derive(Clone, Debug, PartialEq, Eq)]
678#[cfg_attr(
679    feature = "serde",
680    derive(serde_derive::Serialize, serde_derive::Deserialize)
681)]
682#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
683pub struct ChangeEpoch {
684    /// The next (to become) epoch ID.
685    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
686    pub epoch: EpochId,
687
688    /// The protocol version in effect in the new epoch.
689    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
690    pub protocol_version: ProtocolVersion,
691
692    /// The total amount of gas charged for storage during the epoch.
693    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
694    pub storage_charge: u64,
695
696    /// The total amount of gas charged for computation during the epoch.
697    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
698    pub computation_charge: u64,
699
700    /// The amount of storage rebate refunded to the txn senders.
701    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
702    pub storage_rebate: u64,
703
704    /// The non-refundable storage fee.
705    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
706    pub non_refundable_storage_fee: u64,
707
708    /// Unix timestamp when epoch started
709    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
710    pub epoch_start_timestamp_ms: u64,
711
712    /// System packages (specifically framework and move stdlib) that are written before the new
713    /// epoch starts. This tracks framework upgrades on chain. When executing the ChangeEpoch txn,
714    /// the validator must write out the modules below.  Modules are provided with the version they
715    /// will be upgraded to, their modules in serialized form (which include their package ID), and
716    /// a list of their transitive dependencies.
717    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
718    pub system_packages: Vec<SystemPackage>,
719}
720
721/// System package
722///
723/// # BCS
724///
725/// The BCS serialized form for this type is defined by the following ABNF:
726///
727/// ```text
728/// system-package = u64                ; version
729///                  (vector bytes)     ; modules
730///                  (vector object-id) ; dependencies
731/// ```
732#[derive(Clone, Debug, PartialEq, Eq)]
733#[cfg_attr(
734    feature = "serde",
735    derive(serde_derive::Serialize, serde_derive::Deserialize)
736)]
737#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
738pub struct SystemPackage {
739    #[cfg_attr(feature = "serde", serde(with = "crate::_serde::ReadableDisplay"))]
740    pub version: Version,
741    #[cfg_attr(
742        feature = "serde",
743        serde(
744            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
745        )
746    )]
747    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
748    pub modules: Vec<Vec<u8>>,
749    pub dependencies: Vec<ObjectId>,
750}
751
752/// The genesis transaction
753///
754/// # BCS
755///
756/// The BCS serialized form for this type is defined by the following ABNF:
757///
758/// ```text
759/// genesis-transaction = (vector genesis-object)
760/// ```
761#[derive(Clone, Debug, PartialEq, Eq)]
762#[cfg_attr(
763    feature = "serde",
764    derive(serde_derive::Serialize, serde_derive::Deserialize)
765)]
766#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
767pub struct GenesisTransaction {
768    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
769    pub objects: Vec<GenesisObject>,
770}
771
772/// A user transaction
773///
774/// Contains a series of native commands and move calls where the results of one command can be
775/// used in future commands.
776///
777/// # BCS
778///
779/// The BCS serialized form for this type is defined by the following ABNF:
780///
781/// ```text
782/// ptb = (vector input) (vector command)
783/// ```
784#[derive(Clone, Debug, PartialEq, Eq)]
785#[cfg_attr(
786    feature = "serde",
787    derive(serde_derive::Serialize, serde_derive::Deserialize)
788)]
789#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
790pub struct ProgrammableTransaction {
791    /// Input objects or primitive values
792    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=10).lift()))]
793    pub inputs: Vec<Input>,
794
795    /// The commands to be executed sequentially. A failure in any command will
796    /// result in the failure of the entire transaction.
797    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=10).lift()))]
798    pub commands: Vec<Command>,
799}
800
801/// An input to a user transaction
802///
803/// # BCS
804///
805/// The BCS serialized form for this type is defined by the following ABNF:
806///
807/// ```text
808/// input = input-pure / input-immutable-or-owned / input-shared / input-receiving
809///
810/// input-pure                  = %x00 bytes
811/// input-immutable-or-owned    = %x01 object-ref
812/// input-shared                = %x02 object-id u64 bool
813/// input-receiving             = %x04 object-ref
814/// ```
815#[derive(Clone, Debug, PartialEq, Eq)]
816#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
817pub enum Input {
818    /// A move value serialized as BCS.
819    ///
820    /// For normal operations this is required to be a move primitive type and not contain structs
821    /// or objects.
822    Pure { value: Vec<u8> },
823
824    /// A move object that is either immutable or address owned
825    ImmutableOrOwned(ObjectReference),
826
827    /// A move object whose owner is "Shared"
828    Shared {
829        object_id: ObjectId,
830        initial_shared_version: u64,
831
832        /// Controls whether the caller asks for a mutable reference to the shared object.
833        mutable: bool,
834    },
835
836    /// A move object that is attempted to be received in this transaction.
837    // TODO add discussion around what receiving is
838    Receiving(ObjectReference),
839}
840
841/// A single command in a programmable transaction.
842///
843/// # BCS
844///
845/// The BCS serialized form for this type is defined by the following ABNF:
846///
847/// ```text
848/// command =  command-move-call
849///         =/ command-transfer-objects
850///         =/ command-split-coins
851///         =/ command-merge-coins
852///         =/ command-publish
853///         =/ command-make-move-vector
854///         =/ command-upgrade
855///
856/// command-move-call           = %x00 move-call
857/// command-transfer-objects    = %x01 transfer-objects
858/// command-split-coins         = %x02 split-coins
859/// command-merge-coins         = %x03 merge-coins
860/// command-publish             = %x04 publish
861/// command-make-move-vector    = %x05 make-move-vector
862/// command-upgrade             = %x06 upgrade
863/// ```
864#[derive(Clone, Debug, PartialEq, Eq)]
865#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
866pub enum Command {
867    /// A call to either an entry or a public Move function
868    MoveCall(MoveCall),
869
870    /// `(Vec<forall T:key+store. T>, address)`
871    /// It sends n-objects to the specified address. These objects must have store
872    /// (public transfer) and either the previous owner must be an address or the object must
873    /// be newly created.
874    TransferObjects(TransferObjects),
875
876    /// `(&mut Coin<T>, Vec<u64>)` -> `Vec<Coin<T>>`
877    /// It splits off some amounts into a new coins with those amounts
878    SplitCoins(SplitCoins),
879
880    /// `(&mut Coin<T>, Vec<Coin<T>>)`
881    /// It merges n-coins into the first coin
882    MergeCoins(MergeCoins),
883
884    /// Publishes a Move package. It takes the package bytes and a list of the package's transitive
885    /// dependencies to link against on-chain.
886    Publish(Publish),
887
888    /// `forall T: Vec<T> -> vector<T>`
889    /// Given n-values of the same type, it constructs a vector. For non objects or an empty vector,
890    /// the type tag must be specified.
891    MakeMoveVector(MakeMoveVector),
892
893    /// Upgrades a Move package
894    /// Takes (in order):
895    /// 1. A vector of serialized modules for the package.
896    /// 2. A vector of object ids for the transitive dependencies of the new package.
897    /// 3. The object ID of the package being upgraded.
898    /// 4. An argument holding the `UpgradeTicket` that must have been produced from an earlier command in the same
899    ///    programmable transaction.
900    Upgrade(Upgrade),
901}
902
903/// Command to transfer ownership of a set of objects to an address
904///
905/// # BCS
906///
907/// The BCS serialized form for this type is defined by the following ABNF:
908///
909/// ```text
910/// transfer-objects = (vector argument) argument
911/// ```
912#[derive(Clone, Debug, PartialEq, Eq)]
913#[cfg_attr(
914    feature = "serde",
915    derive(serde_derive::Serialize, serde_derive::Deserialize)
916)]
917#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
918pub struct TransferObjects {
919    /// Set of objects to transfer
920    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
921    pub objects: Vec<Argument>,
922
923    /// The address to transfer ownership to
924    pub address: Argument,
925}
926
927/// Command to split a single coin object into multiple coins
928///
929/// # BCS
930///
931/// The BCS serialized form for this type is defined by the following ABNF:
932///
933/// ```text
934/// split-coins = argument (vector argument)
935/// ```
936#[derive(Clone, Debug, PartialEq, Eq)]
937#[cfg_attr(
938    feature = "serde",
939    derive(serde_derive::Serialize, serde_derive::Deserialize)
940)]
941#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
942pub struct SplitCoins {
943    /// The coin to split
944    pub coin: Argument,
945
946    /// The amounts to split off
947    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
948    pub amounts: Vec<Argument>,
949}
950
951/// Command to merge multiple coins of the same type into a single coin
952///
953/// # BCS
954///
955/// The BCS serialized form for this type is defined by the following ABNF:
956///
957/// ```text
958/// merge-coins = argument (vector argument)
959/// ```
960#[derive(Clone, Debug, PartialEq, Eq)]
961#[cfg_attr(
962    feature = "serde",
963    derive(serde_derive::Serialize, serde_derive::Deserialize)
964)]
965#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
966pub struct MergeCoins {
967    /// Coin to merge coins into
968    pub coin: Argument,
969
970    /// Set of coins to merge into `coin`
971    ///
972    /// All listed coins must be of the same type and be the same type as `coin`
973    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
974    pub coins_to_merge: Vec<Argument>,
975}
976
977/// Command to publish a new move package
978///
979/// # BCS
980///
981/// The BCS serialized form for this type is defined by the following ABNF:
982///
983/// ```text
984/// publish = (vector bytes)        ; the serialized move modules
985///           (vector object-id)    ; the set of package dependencies
986/// ```
987#[derive(Clone, Debug, PartialEq, Eq)]
988#[cfg_attr(
989    feature = "serde",
990    derive(serde_derive::Serialize, serde_derive::Deserialize)
991)]
992#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
993pub struct Publish {
994    /// The serialized move modules
995    #[cfg_attr(
996        feature = "serde",
997        serde(
998            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
999        )
1000    )]
1001    pub modules: Vec<Vec<u8>>,
1002
1003    /// Set of packages that the to-be published package depends on
1004    pub dependencies: Vec<ObjectId>,
1005}
1006
1007/// Command to build a move vector out of a set of individual elements
1008///
1009/// # BCS
1010///
1011/// The BCS serialized form for this type is defined by the following ABNF:
1012///
1013/// ```text
1014/// make-move-vector = (option type-tag) (vector argument)
1015/// ```
1016#[derive(Clone, Debug, PartialEq, Eq)]
1017#[cfg_attr(
1018    feature = "serde",
1019    derive(serde_derive::Serialize, serde_derive::Deserialize)
1020)]
1021#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1022pub struct MakeMoveVector {
1023    /// Type of the individual elements
1024    ///
1025    /// This is required to be set when the type can't be inferred, for example when the set of
1026    /// provided arguments are all pure input values.
1027    #[cfg_attr(feature = "serde", serde(rename = "type"))]
1028    pub type_: Option<TypeTag>,
1029
1030    /// The set individual elements to build the vector with
1031    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1032    pub elements: Vec<Argument>,
1033}
1034
1035/// Command to upgrade an already published package
1036///
1037/// # BCS
1038///
1039/// The BCS serialized form for this type is defined by the following ABNF:
1040///
1041/// ```text
1042/// upgrade = (vector bytes)        ; move modules
1043///           (vector object-id)    ; dependencies
1044///           object-id             ; package-id of the package
1045///           argument              ; upgrade ticket
1046/// ```
1047#[derive(Clone, Debug, PartialEq, Eq)]
1048#[cfg_attr(
1049    feature = "serde",
1050    derive(serde_derive::Serialize, serde_derive::Deserialize)
1051)]
1052#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1053pub struct Upgrade {
1054    /// The serialized move modules
1055    #[cfg_attr(
1056        feature = "serde",
1057        serde(
1058            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
1059        )
1060    )]
1061    pub modules: Vec<Vec<u8>>,
1062
1063    /// Set of packages that the to-be published package depends on
1064    pub dependencies: Vec<ObjectId>,
1065
1066    /// Package id of the package to upgrade
1067    pub package: ObjectId,
1068
1069    /// Ticket authorizing the upgrade
1070    pub ticket: Argument,
1071}
1072
1073/// An argument to a programmable transaction command
1074///
1075/// # BCS
1076///
1077/// The BCS serialized form for this type is defined by the following ABNF:
1078///
1079/// ```text
1080/// argument    =  argument-gas
1081///             =/ argument-input
1082///             =/ argument-result
1083///             =/ argument-nested-result
1084///
1085/// argument-gas            = %x00
1086/// argument-input          = %x01 u16
1087/// argument-result         = %x02 u16
1088/// argument-nested-result  = %x03 u16 u16
1089/// ```
1090#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1091#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1092pub enum Argument {
1093    /// The gas coin. The gas coin can only be used by-ref, except for with
1094    /// `TransferObjects`, which can use it by-value.
1095    Gas,
1096
1097    /// One of the input objects or primitive values (from
1098    /// `ProgrammableTransaction` inputs)
1099    Input(u16),
1100
1101    /// The result of another command (from `ProgrammableTransaction` commands)
1102    Result(u16),
1103
1104    /// Like a `Result` but it accesses a nested result. Currently, the only usage
1105    /// of this is to access a value from a Move call with multiple return values.
1106    // (command index, subresult index)
1107    NestedResult(u16, u16),
1108}
1109
1110impl Argument {
1111    /// Turn a Result into a NestedResult. If the argument is not a Result, returns None.
1112    pub fn nested(&self, ix: u16) -> Option<Argument> {
1113        match self {
1114            Argument::Result(i) => Some(Argument::NestedResult(*i, ix)),
1115            _ => None,
1116        }
1117    }
1118}
1119
1120/// Command to call a move function
1121///
1122/// Functions that can be called by a `MoveCall` command are those that have a function signature
1123/// that is either `entry` or `public` (which don't have a reference return type).
1124///
1125/// # BCS
1126///
1127/// The BCS serialized form for this type is defined by the following ABNF:
1128///
1129/// ```text
1130/// move-call = object-id           ; package id
1131///             identifier          ; module name
1132///             identifier          ; function name
1133///             (vector type-tag)   ; type arguments, if any
1134///             (vector argument)   ; input arguments
1135/// ```
1136#[derive(Clone, Debug, PartialEq, Eq)]
1137#[cfg_attr(
1138    feature = "serde",
1139    derive(serde_derive::Serialize, serde_derive::Deserialize)
1140)]
1141#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1142pub struct MoveCall {
1143    /// The package containing the module and function.
1144    pub package: ObjectId,
1145
1146    /// The specific module in the package containing the function.
1147    pub module: Identifier,
1148
1149    /// The function to be called.
1150    pub function: Identifier,
1151
1152    /// The type arguments to the function.
1153    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1154    pub type_arguments: Vec<TypeTag>,
1155
1156    /// The arguments to the function.
1157    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1158    pub arguments: Vec<Argument>,
1159}