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
283/// Set of Execution Time Observations from the committee.
284///
285/// # BCS
286///
287/// The BCS serialized form for this type is defined by the following ABNF:
288///
289/// ```text
290/// stored-execution-time-observations =  %x00 v1-stored-execution-time-observations
291///
292/// v1-stored-execution-time-observations = (vec
293///                                          execution-time-observation-key
294///                                          (vec execution-time-observation)
295///                                         )
296/// ```
297#[derive(Debug, Hash, PartialEq, Eq, Clone)]
298#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
299#[cfg_attr(
300    feature = "serde",
301    derive(serde_derive::Serialize, serde_derive::Deserialize)
302)]
303#[non_exhaustive]
304pub enum ExecutionTimeObservations {
305    V1(
306        #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
307        Vec<(
308            ExecutionTimeObservationKey,
309            Vec<ValidatorExecutionTimeObservation>,
310        )>,
311    ),
312}
313
314/// An execution time observation from a particular validator
315///
316/// # BCS
317///
318/// The BCS serialized form for this type is defined by the following ABNF:
319///
320/// ```text
321/// execution-time-observation = bls-public-key duration
322/// duration =  u64 ; seconds
323///             u32 ; subsecond nanoseconds
324/// ```
325#[derive(Debug, Hash, PartialEq, Eq, Clone)]
326#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
327#[cfg_attr(
328    feature = "serde",
329    derive(serde_derive::Serialize, serde_derive::Deserialize)
330)]
331pub struct ValidatorExecutionTimeObservation {
332    pub validator: crate::Bls12381PublicKey,
333    #[cfg_attr(feature = "proptest", strategy(proptest::strategy::Strategy::prop_map(proptest::arbitrary::any::<u32>(), |x| std::time::Duration::from_millis(x.into()))))]
334    pub duration: std::time::Duration,
335}
336
337/// Key for an execution time observation
338///
339/// # BCS
340///
341/// The BCS serialized form for this type is defined by the following ABNF:
342///
343/// ```text
344/// execution-time-observation-key  =  %x00 move-entry-point
345///                                 =/ %x01 ; transfer-objects
346///                                 =/ %x02 ; split-coins
347///                                 =/ %x03 ; merge-coins
348///                                 =/ %x04 ; publish
349///                                 =/ %x05 ; make-move-vec
350///                                 =/ %x06 ; upgrade
351/// ValidatorExecutionTimeObservation
352/// move-entry-point = address string string (vec type-tag)
353/// ```
354#[derive(Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Clone)]
355#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
356#[cfg_attr(
357    feature = "serde",
358    derive(serde_derive::Serialize, serde_derive::Deserialize)
359)]
360#[non_exhaustive]
361pub enum ExecutionTimeObservationKey {
362    // Containts all the fields from `ProgrammableMoveCall` besides `arguments`.
363    MoveEntryPoint {
364        /// The package containing the module and function.
365        package: Address,
366        /// The specific module in the package containing the function.
367        module: String,
368        /// The function to be called.
369        function: String,
370        /// The type arguments to the function.
371        /// NOTE: This field is currently not populated.
372        #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
373        type_arguments: Vec<TypeTag>,
374    },
375    TransferObjects,
376    SplitCoins,
377    MergeCoins,
378    Publish, // special case: should not be used; we only use hard-coded estimate for this
379    MakeMoveVec,
380    Upgrade,
381}
382
383/// Expire old JWKs
384///
385/// # BCS
386///
387/// The BCS serialized form for this type is defined by the following ABNF:
388///
389/// ```text
390/// authenticator-state-expire = u64 u64
391/// ```
392#[derive(Clone, Debug, PartialEq, Eq)]
393#[cfg_attr(
394    feature = "serde",
395    derive(serde_derive::Serialize, serde_derive::Deserialize)
396)]
397#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
398pub struct AuthenticatorStateExpire {
399    /// expire JWKs that have a lower epoch than this
400    pub min_epoch: u64,
401
402    /// The initial version of the authenticator object that it was shared at.
403    pub authenticator_object_initial_shared_version: u64,
404}
405
406/// Update the set of valid JWKs
407///
408/// # BCS
409///
410/// The BCS serialized form for this type is defined by the following ABNF:
411///
412/// ```text
413/// authenticator-state-update = u64 ; epoch
414///                              u64 ; round
415///                              (vector active-jwk)
416///                              u64 ; initial version of the authenticator object
417/// ```
418#[derive(Clone, Debug, PartialEq, Eq)]
419#[cfg_attr(
420    feature = "serde",
421    derive(serde_derive::Serialize, serde_derive::Deserialize)
422)]
423#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
424pub struct AuthenticatorStateUpdate {
425    /// Epoch of the authenticator state update transaction
426    pub epoch: u64,
427
428    /// Consensus round of the authenticator state update
429    pub round: u64,
430
431    /// newly active jwks
432    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
433    pub new_active_jwks: Vec<ActiveJwk>,
434
435    /// The initial version of the authenticator object that it was shared at.
436    pub authenticator_obj_initial_shared_version: u64,
437}
438
439/// A new Jwk
440///
441/// # BCS
442///
443/// The BCS serialized form for this type is defined by the following ABNF:
444///
445/// ```text
446/// active-jwk = jwk-id jwk u64
447/// ```
448#[derive(Clone, Debug, PartialEq, Eq)]
449#[cfg_attr(
450    feature = "serde",
451    derive(serde_derive::Serialize, serde_derive::Deserialize)
452)]
453#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
454pub struct ActiveJwk {
455    /// Identifier used to uniquely identify a Jwk
456    pub jwk_id: JwkId,
457
458    /// The Jwk
459    pub jwk: Jwk,
460
461    /// Most recent epoch in which the jwk was validated
462    pub epoch: u64,
463}
464
465/// V1 of the consensus commit prologue system transaction
466///
467/// # BCS
468///
469/// The BCS serialized form for this type is defined by the following ABNF:
470///
471/// ```text
472/// consensus-commit-prologue = u64 u64 u64
473/// ```
474#[derive(Clone, Debug, PartialEq, Eq)]
475#[cfg_attr(
476    feature = "serde",
477    derive(serde_derive::Serialize, serde_derive::Deserialize)
478)]
479#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
480pub struct ConsensusCommitPrologue {
481    /// Epoch of the commit prologue transaction
482    pub epoch: u64,
483
484    /// Consensus round of the commit
485    pub round: u64,
486
487    /// Unix timestamp from consensus
488    pub commit_timestamp_ms: CheckpointTimestamp,
489}
490
491/// V2 of the consensus commit prologue system transaction
492///
493/// # BCS
494///
495/// The BCS serialized form for this type is defined by the following ABNF:
496///
497/// ```text
498/// consensus-commit-prologue-v2 = u64 u64 u64 digest
499/// ```
500#[derive(Clone, Debug, PartialEq, Eq)]
501#[cfg_attr(
502    feature = "serde",
503    derive(serde_derive::Serialize, serde_derive::Deserialize)
504)]
505#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
506pub struct ConsensusCommitPrologueV2 {
507    /// Epoch of the commit prologue transaction
508    pub epoch: u64,
509
510    /// Consensus round of the commit
511    pub round: u64,
512
513    /// Unix timestamp from consensus
514    pub commit_timestamp_ms: CheckpointTimestamp,
515
516    /// Digest of consensus output
517    pub consensus_commit_digest: Digest,
518}
519
520/// Version assignments performed by consensus
521///
522/// # BCS
523///
524/// The BCS serialized form for this type is defined by the following ABNF:
525///
526/// ```text
527/// consensus-determined-version-assignments = canceled-transactions
528///
529/// canceled-transactions = %x00 (vector canceled-transaction)
530///                       = %x01 (vector canceled-transaction-v2)
531/// ```
532#[derive(Clone, Debug, PartialEq, Eq)]
533#[cfg_attr(
534    feature = "serde",
535    derive(serde_derive::Serialize, serde_derive::Deserialize)
536)]
537#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
538#[non_exhaustive]
539pub enum ConsensusDeterminedVersionAssignments {
540    /// Canceled transaction version assignment.
541    CanceledTransactions {
542        #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
543        canceled_transactions: Vec<CanceledTransaction>,
544    },
545    /// Canceled transaction version assignment V2.
546    CanceledTransactionsV2 {
547        #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
548        canceled_transactions: Vec<CanceledTransactionV2>,
549    },
550}
551
552/// A transaction that was canceled
553///
554/// # BCS
555///
556/// The BCS serialized form for this type is defined by the following ABNF:
557///
558/// ```text
559/// canceled-transaction = digest (vector version-assignment)
560/// ```
561#[derive(Clone, Debug, PartialEq, Eq)]
562#[cfg_attr(
563    feature = "serde",
564    derive(serde_derive::Serialize, serde_derive::Deserialize)
565)]
566#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
567pub struct CanceledTransaction {
568    pub digest: Digest,
569    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
570    pub version_assignments: Vec<VersionAssignment>,
571}
572
573/// Object version assignment from consensus
574///
575/// # BCS
576///
577/// The BCS serialized form for this type is defined by the following ABNF:
578///
579/// ```text
580/// version-assignment = address u64
581/// ```
582#[derive(Clone, Debug, PartialEq, Eq)]
583#[cfg_attr(
584    feature = "serde",
585    derive(serde_derive::Serialize, serde_derive::Deserialize)
586)]
587#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
588pub struct VersionAssignment {
589    pub object_id: Address,
590    pub version: Version,
591}
592
593/// A transaction that was canceled
594///
595/// # BCS
596///
597/// The BCS serialized form for this type is defined by the following ABNF:
598///
599/// ```text
600/// canceled-transaction-v2 = digest (vector version-assignment-v2)
601/// ```
602#[derive(Clone, Debug, PartialEq, Eq)]
603#[cfg_attr(
604    feature = "serde",
605    derive(serde_derive::Serialize, serde_derive::Deserialize)
606)]
607#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
608pub struct CanceledTransactionV2 {
609    pub digest: Digest,
610    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
611    pub version_assignments: Vec<VersionAssignmentV2>,
612}
613
614/// Object version assignment from consensus
615///
616/// # BCS
617///
618/// The BCS serialized form for this type is defined by the following ABNF:
619///
620/// ```text
621/// version-assignment-v2 = address u64 u64
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 VersionAssignmentV2 {
630    pub object_id: Address,
631    pub start_version: Version,
632    pub version: Version,
633}
634
635/// V3 of the consensus commit prologue system transaction
636///
637/// # BCS
638///
639/// The BCS serialized form for this type is defined by the following ABNF:
640///
641/// ```text
642/// consensus-commit-prologue-v3 = u64 u64 (option u64) u64 digest
643///                                consensus-determined-version-assignments
644/// ```
645#[derive(Clone, Debug, PartialEq, Eq)]
646#[cfg_attr(
647    feature = "serde",
648    derive(serde_derive::Serialize, serde_derive::Deserialize)
649)]
650#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
651pub struct ConsensusCommitPrologueV3 {
652    /// Epoch of the commit prologue transaction
653    pub epoch: u64,
654
655    /// Consensus round of the commit
656    pub round: u64,
657
658    /// The sub DAG index of the consensus commit. This field will be populated if there
659    /// are multiple consensus commits per round.
660    pub sub_dag_index: Option<u64>,
661
662    /// Unix timestamp from consensus
663    pub commit_timestamp_ms: CheckpointTimestamp,
664
665    /// Digest of consensus output
666    pub consensus_commit_digest: Digest,
667
668    /// Stores consensus handler determined shared object version assignments.
669    pub consensus_determined_version_assignments: ConsensusDeterminedVersionAssignments,
670}
671
672/// V4 of the consensus commit prologue system transaction
673///
674/// # BCS
675///
676/// The BCS serialized form for this type is defined by the following ABNF:
677///
678/// ```text
679/// consensus-commit-prologue-v4 = u64 u64 (option u64) u64 digest
680///                                consensus-determined-version-assignments
681///                                digest
682/// ```
683#[derive(Clone, Debug, PartialEq, Eq)]
684#[cfg_attr(
685    feature = "serde",
686    derive(serde_derive::Serialize, serde_derive::Deserialize)
687)]
688#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
689pub struct ConsensusCommitPrologueV4 {
690    /// Epoch of the commit prologue transaction
691    pub epoch: u64,
692
693    /// Consensus round of the commit
694    pub round: u64,
695
696    /// The sub DAG index of the consensus commit. This field will be populated if there
697    /// are multiple consensus commits per round.
698    pub sub_dag_index: Option<u64>,
699
700    /// Unix timestamp from consensus
701    pub commit_timestamp_ms: CheckpointTimestamp,
702
703    /// Digest of consensus output
704    pub consensus_commit_digest: Digest,
705
706    /// Stores consensus handler determined shared object version assignments.
707    pub consensus_determined_version_assignments: ConsensusDeterminedVersionAssignments,
708
709    /// Digest of any additional state computed by the consensus handler.
710    /// Used to detect forking bugs as early as possible.
711    pub additional_state_digest: Digest,
712}
713
714/// System transaction used to change the epoch
715///
716/// # BCS
717///
718/// The BCS serialized form for this type is defined by the following ABNF:
719///
720/// ```text
721/// change-epoch = u64  ; next epoch
722///                u64  ; protocol version
723///                u64  ; storage charge
724///                u64  ; computation charge
725///                u64  ; storage rebate
726///                u64  ; non-refundable storage fee
727///                u64  ; epoch start timestamp
728///                (vector system-package)
729/// ```
730#[derive(Clone, Debug, PartialEq, Eq)]
731#[cfg_attr(
732    feature = "serde",
733    derive(serde_derive::Serialize, serde_derive::Deserialize)
734)]
735#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
736pub struct ChangeEpoch {
737    /// The next (to become) epoch ID.
738    pub epoch: EpochId,
739
740    /// The protocol version in effect in the new epoch.
741    pub protocol_version: ProtocolVersion,
742
743    /// The total amount of gas charged for storage during the epoch.
744    pub storage_charge: u64,
745
746    /// The total amount of gas charged for computation during the epoch.
747    pub computation_charge: u64,
748
749    /// The amount of storage rebate refunded to the txn senders.
750    pub storage_rebate: u64,
751
752    /// The non-refundable storage fee.
753    pub non_refundable_storage_fee: u64,
754
755    /// Unix timestamp when epoch started
756    pub epoch_start_timestamp_ms: u64,
757
758    /// System packages (specifically framework and move stdlib) that are written before the new
759    /// epoch starts. This tracks framework upgrades on chain. When executing the ChangeEpoch txn,
760    /// the validator must write out the modules below.  Modules are provided with the version they
761    /// will be upgraded to, their modules in serialized form (which include their package ID), and
762    /// a list of their transitive dependencies.
763    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
764    pub system_packages: Vec<SystemPackage>,
765}
766
767/// System package
768///
769/// # BCS
770///
771/// The BCS serialized form for this type is defined by the following ABNF:
772///
773/// ```text
774/// system-package = u64                ; version
775///                  (vector bytes)     ; modules
776///                  (vector address) ; dependencies
777/// ```
778#[derive(Clone, Debug, PartialEq, Eq)]
779#[cfg_attr(
780    feature = "serde",
781    derive(serde_derive::Serialize, serde_derive::Deserialize)
782)]
783#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
784pub struct SystemPackage {
785    pub version: Version,
786    #[cfg_attr(
787        feature = "serde",
788        serde(
789            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
790        )
791    )]
792    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
793    pub modules: Vec<Vec<u8>>,
794    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
795    pub dependencies: Vec<Address>,
796}
797
798/// The genesis transaction
799///
800/// # BCS
801///
802/// The BCS serialized form for this type is defined by the following ABNF:
803///
804/// ```text
805/// genesis-transaction = (vector genesis-object)
806/// ```
807#[derive(Clone, Debug, PartialEq, Eq)]
808#[cfg_attr(
809    feature = "serde",
810    derive(serde_derive::Serialize, serde_derive::Deserialize)
811)]
812#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
813pub struct GenesisTransaction {
814    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
815    pub objects: Vec<GenesisObject>,
816}
817
818/// A user transaction
819///
820/// Contains a series of native commands and move calls where the results of one command can be
821/// used in future commands.
822///
823/// # BCS
824///
825/// The BCS serialized form for this type is defined by the following ABNF:
826///
827/// ```text
828/// ptb = (vector input) (vector command)
829/// ```
830#[derive(Clone, Debug, PartialEq, Eq)]
831#[cfg_attr(
832    feature = "serde",
833    derive(serde_derive::Serialize, serde_derive::Deserialize)
834)]
835#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
836pub struct ProgrammableTransaction {
837    /// Input objects or primitive values
838    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=10).lift()))]
839    pub inputs: Vec<Input>,
840
841    /// The commands to be executed sequentially. A failure in any command will
842    /// result in the failure of the entire transaction.
843    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
844    pub commands: Vec<Command>,
845}
846
847/// An input to a user transaction
848///
849/// # BCS
850///
851/// The BCS serialized form for this type is defined by the following ABNF:
852///
853/// ```text
854/// input = input-pure / input-immutable-or-owned / input-shared / input-receiving
855///
856/// input-pure                  = %x00 bytes
857/// input-immutable-or-owned    = %x01 object-ref
858/// input-shared                = %x02 address u64 bool
859/// input-receiving             = %x04 object-ref
860/// ```
861#[derive(Clone, Debug, PartialEq, Eq)]
862#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
863#[non_exhaustive]
864pub enum Input {
865    /// A move value serialized as BCS.
866    ///
867    /// For normal operations this is required to be a move primitive type and not contain structs
868    /// or objects.
869    Pure { value: Vec<u8> },
870
871    /// A move object that is either immutable or address owned
872    ImmutableOrOwned(ObjectReference),
873
874    /// A move object whose owner is "Shared"
875    Shared {
876        object_id: Address,
877        initial_shared_version: u64,
878
879        /// Controls whether the caller asks for a mutable reference to the shared object.
880        mutable: bool,
881    },
882
883    /// A move object that is attempted to be received in this transaction.
884    // TODO add discussion around what receiving is
885    Receiving(ObjectReference),
886}
887
888/// A single command in a programmable transaction.
889///
890/// # BCS
891///
892/// The BCS serialized form for this type is defined by the following ABNF:
893///
894/// ```text
895/// command =  command-move-call
896///         =/ command-transfer-objects
897///         =/ command-split-coins
898///         =/ command-merge-coins
899///         =/ command-publish
900///         =/ command-make-move-vector
901///         =/ command-upgrade
902///
903/// command-move-call           = %x00 move-call
904/// command-transfer-objects    = %x01 transfer-objects
905/// command-split-coins         = %x02 split-coins
906/// command-merge-coins         = %x03 merge-coins
907/// command-publish             = %x04 publish
908/// command-make-move-vector    = %x05 make-move-vector
909/// command-upgrade             = %x06 upgrade
910/// ```
911#[derive(Clone, Debug, PartialEq, Eq)]
912#[cfg_attr(
913    feature = "serde",
914    derive(serde_derive::Serialize, serde_derive::Deserialize)
915)]
916#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
917#[non_exhaustive]
918pub enum Command {
919    /// A call to either an entry or a public Move function
920    MoveCall(MoveCall),
921
922    /// `(Vec<forall T:key+store. T>, address)`
923    /// It sends n-objects to the specified address. These objects must have store
924    /// (public transfer) and either the previous owner must be an address or the object must
925    /// be newly created.
926    TransferObjects(TransferObjects),
927
928    /// `(&mut Coin<T>, Vec<u64>)` -> `Vec<Coin<T>>`
929    /// It splits off some amounts into a new coins with those amounts
930    SplitCoins(SplitCoins),
931
932    /// `(&mut Coin<T>, Vec<Coin<T>>)`
933    /// It merges n-coins into the first coin
934    MergeCoins(MergeCoins),
935
936    /// Publishes a Move package. It takes the package bytes and a list of the package's transitive
937    /// dependencies to link against on-chain.
938    Publish(Publish),
939
940    /// `forall T: Vec<T> -> vector<T>`
941    /// Given n-values of the same type, it constructs a vector. For non objects or an empty vector,
942    /// the type tag must be specified.
943    MakeMoveVector(MakeMoveVector),
944
945    /// Upgrades a Move package
946    /// Takes (in order):
947    /// 1. A vector of serialized modules for the package.
948    /// 2. A vector of object ids for the transitive dependencies of the new package.
949    /// 3. The object ID of the package being upgraded.
950    /// 4. An argument holding the `UpgradeTicket` that must have been produced from an earlier command in the same
951    ///    programmable transaction.
952    Upgrade(Upgrade),
953}
954
955/// Command to transfer ownership of a set of objects to an address
956///
957/// # BCS
958///
959/// The BCS serialized form for this type is defined by the following ABNF:
960///
961/// ```text
962/// transfer-objects = (vector argument) argument
963/// ```
964#[derive(Clone, Debug, PartialEq, Eq)]
965#[cfg_attr(
966    feature = "serde",
967    derive(serde_derive::Serialize, serde_derive::Deserialize)
968)]
969#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
970pub struct TransferObjects {
971    /// Set of objects to transfer
972    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
973    pub objects: Vec<Argument>,
974
975    /// The address to transfer ownership to
976    pub address: Argument,
977}
978
979/// Command to split a single coin object into multiple coins
980///
981/// # BCS
982///
983/// The BCS serialized form for this type is defined by the following ABNF:
984///
985/// ```text
986/// split-coins = argument (vector argument)
987/// ```
988#[derive(Clone, Debug, PartialEq, Eq)]
989#[cfg_attr(
990    feature = "serde",
991    derive(serde_derive::Serialize, serde_derive::Deserialize)
992)]
993#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
994pub struct SplitCoins {
995    /// The coin to split
996    pub coin: Argument,
997
998    /// The amounts to split off
999    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1000    pub amounts: Vec<Argument>,
1001}
1002
1003/// Command to merge multiple coins of the same type into a single coin
1004///
1005/// # BCS
1006///
1007/// The BCS serialized form for this type is defined by the following ABNF:
1008///
1009/// ```text
1010/// merge-coins = argument (vector argument)
1011/// ```
1012#[derive(Clone, Debug, PartialEq, Eq)]
1013#[cfg_attr(
1014    feature = "serde",
1015    derive(serde_derive::Serialize, serde_derive::Deserialize)
1016)]
1017#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1018pub struct MergeCoins {
1019    /// Coin to merge coins into
1020    pub coin: Argument,
1021
1022    /// Set of coins to merge into `coin`
1023    ///
1024    /// All listed coins must be of the same type and be the same type as `coin`
1025    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1026    pub coins_to_merge: Vec<Argument>,
1027}
1028
1029/// Command to publish a new move package
1030///
1031/// # BCS
1032///
1033/// The BCS serialized form for this type is defined by the following ABNF:
1034///
1035/// ```text
1036/// publish = (vector bytes)        ; the serialized move modules
1037///           (vector address)    ; the set of package dependencies
1038/// ```
1039#[derive(Clone, Debug, PartialEq, Eq)]
1040#[cfg_attr(
1041    feature = "serde",
1042    derive(serde_derive::Serialize, serde_derive::Deserialize)
1043)]
1044#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1045pub struct Publish {
1046    /// The serialized move modules
1047    #[cfg_attr(
1048        feature = "serde",
1049        serde(
1050            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
1051        )
1052    )]
1053    pub modules: Vec<Vec<u8>>,
1054
1055    /// Set of packages that the to-be published package depends on
1056    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1057    pub dependencies: Vec<Address>,
1058}
1059
1060/// Command to build a move vector out of a set of individual elements
1061///
1062/// # BCS
1063///
1064/// The BCS serialized form for this type is defined by the following ABNF:
1065///
1066/// ```text
1067/// make-move-vector = (option type-tag) (vector argument)
1068/// ```
1069#[derive(Clone, Debug, PartialEq, Eq)]
1070#[cfg_attr(
1071    feature = "serde",
1072    derive(serde_derive::Serialize, serde_derive::Deserialize)
1073)]
1074#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1075pub struct MakeMoveVector {
1076    /// Type of the individual elements
1077    ///
1078    /// This is required to be set when the type can't be inferred, for example when the set of
1079    /// provided arguments are all pure input values.
1080    #[cfg_attr(feature = "serde", serde(rename = "type"))]
1081    pub type_: Option<TypeTag>,
1082
1083    /// The set individual elements to build the vector with
1084    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1085    pub elements: Vec<Argument>,
1086}
1087
1088/// Command to upgrade an already published package
1089///
1090/// # BCS
1091///
1092/// The BCS serialized form for this type is defined by the following ABNF:
1093///
1094/// ```text
1095/// upgrade = (vector bytes)        ; move modules
1096///           (vector address)    ; dependencies
1097///           address             ; package-id of the package
1098///           argument              ; upgrade ticket
1099/// ```
1100#[derive(Clone, Debug, PartialEq, Eq)]
1101#[cfg_attr(
1102    feature = "serde",
1103    derive(serde_derive::Serialize, serde_derive::Deserialize)
1104)]
1105#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1106pub struct Upgrade {
1107    /// The serialized move modules
1108    #[cfg_attr(
1109        feature = "serde",
1110        serde(
1111            with = "::serde_with::As::<Vec<::serde_with::IfIsHumanReadable<crate::_serde::Base64Encoded, ::serde_with::Bytes>>>"
1112        )
1113    )]
1114    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=1).lift()))]
1115    pub modules: Vec<Vec<u8>>,
1116
1117    /// Set of packages that the to-be published package depends on
1118    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1119    pub dependencies: Vec<Address>,
1120
1121    /// Package id of the package to upgrade
1122    pub package: Address,
1123
1124    /// Ticket authorizing the upgrade
1125    pub ticket: Argument,
1126}
1127
1128/// An argument to a programmable transaction command
1129///
1130/// # BCS
1131///
1132/// The BCS serialized form for this type is defined by the following ABNF:
1133///
1134/// ```text
1135/// argument    =  argument-gas
1136///             =/ argument-input
1137///             =/ argument-result
1138///             =/ argument-nested-result
1139///
1140/// argument-gas            = %x00
1141/// argument-input          = %x01 u16
1142/// argument-result         = %x02 u16
1143/// argument-nested-result  = %x03 u16 u16
1144/// ```
1145#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1146#[cfg_attr(
1147    feature = "serde",
1148    derive(serde_derive::Serialize, serde_derive::Deserialize)
1149)]
1150#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1151pub enum Argument {
1152    /// The gas coin. The gas coin can only be used by-ref, except for with
1153    /// `TransferObjects`, which can use it by-value.
1154    Gas,
1155
1156    /// One of the input objects or primitive values (from
1157    /// `ProgrammableTransaction` inputs)
1158    Input(u16),
1159
1160    /// The result of another command (from `ProgrammableTransaction` commands)
1161    Result(u16),
1162
1163    /// Like a `Result` but it accesses a nested result. Currently, the only usage
1164    /// of this is to access a value from a Move call with multiple return values.
1165    // (command index, subresult index)
1166    NestedResult(u16, u16),
1167}
1168
1169impl Argument {
1170    /// Turn a Result into a NestedResult. If the argument is not a Result, returns None.
1171    pub fn nested(&self, ix: u16) -> Option<Argument> {
1172        match self {
1173            Argument::Result(i) => Some(Argument::NestedResult(*i, ix)),
1174            _ => None,
1175        }
1176    }
1177}
1178
1179/// Command to call a move function
1180///
1181/// Functions that can be called by a `MoveCall` command are those that have a function signature
1182/// that is either `entry` or `public` (which don't have a reference return type).
1183///
1184/// # BCS
1185///
1186/// The BCS serialized form for this type is defined by the following ABNF:
1187///
1188/// ```text
1189/// move-call = address           ; package id
1190///             identifier          ; module name
1191///             identifier          ; function name
1192///             (vector type-tag)   ; type arguments, if any
1193///             (vector argument)   ; input arguments
1194/// ```
1195#[derive(Clone, Debug, PartialEq, Eq)]
1196#[cfg_attr(
1197    feature = "serde",
1198    derive(serde_derive::Serialize, serde_derive::Deserialize)
1199)]
1200#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
1201pub struct MoveCall {
1202    /// The package containing the module and function.
1203    pub package: Address,
1204
1205    /// The specific module in the package containing the function.
1206    pub module: Identifier,
1207
1208    /// The function to be called.
1209    pub function: Identifier,
1210
1211    /// The type arguments to the function.
1212    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1213    pub type_arguments: Vec<TypeTag>,
1214
1215    /// The arguments to the function.
1216    #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=2).lift()))]
1217    pub arguments: Vec<Argument>,
1218}