sui_sdk_types/transaction/
mod.rs

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