Struct TransactionV1Builder

pub struct TransactionV1Builder<'a> { /* private fields */ }

Available on crate feature std only.

A builder for constructing TransactionV1 instances with various configuration options.

The TransactionV1Builder provides a flexible API for specifying different transaction parameters like the target, scheduling, entry point, and signing options. Once all the required fields are set, the transaction can be built by calling build.

Fields

• args: Arguments passed to the transaction’s runtime, initialized to RuntimeArgs::new.
• target: Specifies the target of the transaction, which can be native or other custom targets. Defaults to TransactionTarget::Native.
• scheduling: Determines the scheduling mechanism of the transaction, e.g., standard or immediate, and is initialized to TransactionScheduling::Standard.
• entry_point: Defines the transaction’s entry point, such as transfer or another defined action. Defaults to TransactionEntryPoint::Transfer.
• chain_name: The name of the blockchain where the transaction will be executed. Initially set to None and must be provided before building the transaction.

Time-Related Fields

• timestamp: The timestamp at which the transaction is created. It is either set to the current time using Timestamp::now or Timestamp::zero without the std-fs-io feature.
• ttl: Time-to-live for the transaction, specified as a TimeDiff, representing how long the transaction is valid for execution. Defaults to Self::DEFAULT_TTL.

Pricing and Initiator Fields

• pricing_mode: Specifies the pricing mode to use for transaction execution (e.g., fixed or dynamic). Defaults to Self::DEFAULT_PRICING_MODE.
• initiator_addr: The address of the initiator who creates and signs the transaction. Initially set to None and must be set before building.

Signing Fields

• secret_key: The secret key used to sign the transaction. This field is conditional based on the compilation environment:
  • In normal mode, it holds a reference to the secret key (Option<&'a SecretKey>).
  • In testing mode or with the std feature enabled, it holds an owned secret key (Option<SecretKey>).

Invalid Approvals

• invalid_approvals: A collection of invalid approvals used for testing purposes. This field is available only when the std or testing features are enabled, or in a test environment.

Phantom Data

• _phantom_data: Ensures the correct lifetime 'a is respected for the builder, helping with proper borrowing and memory safety.

Implementations

impl<'a> TransactionV1Builder<'a>

pub const DEFAULT_TTL: TimeDiff = _

The default time-to-live for transactions, i.e. 30 minutes.

pub const DEFAULT_PRICING_MODE: PricingMode = _

The default pricing mode for v1 transactions, ie FIXED cost.

pub const DEFAULT_SCHEDULING: TransactionScheduling = TransactionScheduling::Standard

The default scheduling for transactions, i.e. Standard.

pub fn new_transfer<A: Into<U512>, T: Into<TransferTarget>>( amount: A, maybe_source: Option<URef>, target: T, maybe_id: Option<u64>, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native transfer transaction.

pub fn new_add_bid<A: Into<U512>>( public_key: PublicKey, delegation_rate: u8, amount: A, minimum_delegation_amount: Option<u64>, maximum_delegation_amount: Option<u64>, reserved_slots: Option<u32>, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native add_bid transaction.

pub fn new_withdraw_bid<A: Into<U512>>( public_key: PublicKey, amount: A, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native withdraw_bid transaction.

pub fn new_delegate<A: Into<U512>>( delegator: PublicKey, validator: PublicKey, amount: A, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native delegate transaction.

pub fn new_undelegate<A: Into<U512>>( delegator: PublicKey, validator: PublicKey, amount: A, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native undelegate transaction.

pub fn new_redelegate<A: Into<U512>>( delegator: PublicKey, validator: PublicKey, amount: A, new_validator: PublicKey, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native redelegate transaction.

pub fn new_change_bid_public_key<A: Into<U512>>( public_key: PublicKey, new_public_key: PublicKey, ) -> Result<Self, CLValueError>

Returns a new TransactionV1Builder suitable for building a native change_bid_public_key transaction.

pub fn new_add_reservations( reservations: Vec<Reservation>, ) -> Result<Self, CLValueError>

Available on crate feature testing only.

Returns a new TransactionV1Builder suitable for building a native add_reservations transaction.

pub fn new_cancel_reservations( validator: PublicKey, delegators: Vec<PublicKey>, ) -> Result<Self, CLValueError>

Available on crate feature testing only.

Returns a new TransactionV1Builder suitable for building a native cancel_reservations transaction.

pub fn new_targeting_invocable_entity<E: Into<String>>( hash: AddressableEntityHash, entry_point: E, runtime: TransactionRuntime, transferred_value: u64, ) -> Self

Returns a new TransactionV1Builder suitable for building a transaction targeting a stored entity.

pub fn new_targeting_invocable_entity_via_alias<A: Into<String>, E: Into<String>>( alias: A, entry_point: E, runtime: TransactionRuntime, transferred_value: u64, ) -> Self

Returns a new TransactionV1Builder suitable for building a transaction targeting a stored entity via its alias.

pub fn new_targeting_package<E: Into<String>>( hash: PackageHash, version: Option<EntityVersion>, entry_point: E, runtime: TransactionRuntime, transferred_value: u64, ) -> Self

Returns a new TransactionV1Builder suitable for building a transaction targeting a package.

pub fn new_targeting_package_via_alias<A: Into<String>, E: Into<String>>( alias: A, version: Option<EntityVersion>, entry_point: E, runtime: TransactionRuntime, transferred_value: u64, ) -> Self

Returns a new TransactionV1Builder suitable for building a transaction targeting a package via its alias.

pub fn new_session( is_install_upgrade: bool, module_bytes: Bytes, runtime: TransactionRuntime, transferred_value: u64, seed: Option<[u8; 32]>, ) -> Self

Returns a new TransactionV1Builder suitable for building a transaction for running session logic, i.e. compiled Wasm.

pub fn new_random(rng: &mut TestRng) -> Self

Available on crate feature testing only.

Returns a new TransactionV1Builder which will build a random, valid but possibly expired transaction.

The transaction can be made invalid in the following ways:

• unsigned by calling with_no_secret_key
• given an invalid approval by calling with_invalid_approval

pub fn new_random_with_category_and_timestamp_and_ttl( rng: &mut TestRng, lane: u8, timestamp: Option<Timestamp>, ttl: Option<TimeDiff>, ) -> Self

Available on crate feature testing only.

Returns a new TransactionV1Builder which will build a random not expired transaction of given category

The transaction can be made invalid in the following ways:

• unsigned by calling with_no_secret_key
• given an invalid approval by calling with_invalid_approval

pub fn with_chain_name<C: Into<String>>(self, chain_name: C) -> Self

Sets the chain_name in the transaction.

Must be provided or building will fail.

pub fn with_timestamp(self, timestamp: Timestamp) -> Self

Sets the timestamp in the transaction.

If not provided, the timestamp will be set to the time when the builder was constructed.

pub fn with_ttl(self, ttl: TimeDiff) -> Self

Sets the ttl (time-to-live) in the transaction.

If not provided, the ttl will be set to Self::DEFAULT_TTL.

pub fn with_pricing_mode(self, pricing_mode: PricingMode) -> Self

Sets the pricing_mode in the transaction.

If not provided, the pricing mode will be set to Self::DEFAULT_PRICING_MODE.

pub fn with_initiator_addr<I: Into<InitiatorAddr>>( self, initiator_addr: I, ) -> Self

Sets the initiator_addr in the transaction.

If not provided, the public key derived from the secret key used in the builder will be used as the InitiatorAddr::PublicKey in the transaction.

pub fn with_secret_key(self, secret_key: &'a SecretKey) -> Self

Sets the secret key used to sign the transaction on calling build.

If not provided, the transaction can still be built, but will be unsigned and will be invalid until subsequently signed.

pub fn with_runtime_arg<K: Into<String>>( self, key: K, cl_value: CLValue, ) -> Self

Appends the given runtime arg into the body’s args.

pub fn with_runtime_args(self, args: RuntimeArgs) -> Self

Sets the runtime args in the transaction.

NOTE: this overwrites any existing runtime args. To append to existing args, use TransactionV1Builder::with_runtime_arg.

pub fn with_chunked_args(self, args: Bytes) -> Self

Sets the runtime args in the transaction.

pub fn with_transaction_args(self, args: TransactionArgs) -> Self

Sets the transaction args in the transaction.

pub fn with_runtime(self, runtime: TransactionRuntime) -> Self

Sets the runtime for the transaction.

NOTE: This has no effect for native transactions, i.e. where the body.target is TransactionTarget::Native.

pub fn with_scheduling(self, scheduling: TransactionScheduling) -> Self

Sets the scheduling for the transaction.

If not provided, the scheduling will be set to Self::DEFAULT_SCHEDULING.

pub fn with_entry_point(self, entry_point: TransactionEntryPoint) -> Self

Sets the entry point for the transaction.

pub fn with_no_secret_key(self) -> Self

Available on crate feature testing only.

Sets the secret key to None, meaning the transaction can still be built but will be unsigned and will be invalid until subsequently signed.

pub fn with_invalid_approval(self, rng: &mut TestRng) -> Self

Available on crate feature testing only.

Sets an invalid approval in the transaction.

pub fn with_additional_fields( self, additional_fields: BTreeMap<u16, Bytes>, ) -> Self

Available on crate feature testing only.

Manually sets additional fields

pub fn build(self) -> Result<TransactionV1, TransactionV1BuilderError>

Returns the new transaction, or an error if non-defaulted fields were not set.

For more info, see the TransactionBuilder documentation.

Trait Implementations

impl<'a> Debug for TransactionV1Builder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.