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