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}