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