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