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