Struct Transaction 

pub struct Transaction<State: IsTransactionBodyState> { /* private fields */ }

A transaction, either under construction or fully signed.

The State captures the current state of the transaction and restricts the methods available based on the state. In practice, a transaction starts in the state::InConstruction using either Self::default or provided in the callback to Self::build.

Then it reaches the state::ReadyForSigning which enables the method Self::sign, and forbid any method that modifies the transaction body.

Note that Self::build is currently the only way by which one can get a transaction in the state::ReadyForSigning.

Implementations

impl Transaction<InConstruction>

pub fn build<F>( params: &ProtocolParameters, resolved_inputs: &BTreeMap<Input, Output>, build: F, ) -> Result<Transaction<ReadyForSigning>>

where F: Fn(&mut Self) -> Result<&mut Self>,

Build a transaction by repeatedly executing some building logic with different fee and execution units settings. Stops when a fixed point is reached.

The final transaction has corresponding fees, execution units, collateral return and script integrity hash set.

notes

• any input specified in the transaction (either as input, reference input or collateral) must be present in the provided resolved_inputs.
• with_change_strategy must always be present for there’s no default change strategy.
• while it is allowed (for whatever reasons), you aren’t expected to fiddle with fees here; this is entirely managed by the build loop.

examples

A simple transaction from a single input to a single recipient, with change.

// The available UTxO, typically fetched from a blockchain provider or an indexer.
let resolved_inputs = BTreeMap::from([
  (
    input!("32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c", 1),
    output!(
      "addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47",
      value!(10_000_000),
    ),
  )
]);

// Send a minimum lovelace value to an arbitrary address, and the change back to the
// sender.
assert_eq!(
  Transaction::build(&ProtocolParameters::mainnet(), &resolved_inputs, |tx| tx
    .with_inputs(vec![
      input!("32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c", 1, _),
    ])
    .with_outputs(vec![
      output!("addr1wyhcwt6h7mf6rlaqadmhh5awnyd44t7v4lju5ur430fk4xczzq8aw"),
    ])
    .with_change_strategy(ChangeStrategy::as_last_output(
      address!("addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47"),
    ))
    .ok()
  ).unwrap().to_string(),
  indoc!{"
    Transaction (id = 6f8e53f61fe0a709e1c895c1bd9487e555779de0902ad25377d4de1df48f08b8) {
        inputs: [
            Input(32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c#1),
        ],
        outputs: [
            Output {
                address: addr1wyhcwt6h7mf6rlaqadmhh5awnyd44t7v4lju5ur430fk4xczzq8aw,
                value: Value {
                    lovelace: 857690,
                },
            },
            Output {
                address: addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47,
                value: Value {
                    lovelace: 8976061,
                },
            },
        ],
        fee: 166249,
        validity: ]-∞; +∞[,
    }"
  }
);

Minting assets using a plutus script.

let resolved_inputs = BTreeMap::from([
  (
    input!("32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c", 1),
    output!(
      "addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47",
      value!(10_000_000),
    ),
  )
]);

// Notice the absence of outputs and of collateral return. We let the builder handler those for us.
assert_eq!(
  Transaction::build(&ProtocolParameters::mainnet(), &resolved_inputs, |tx| tx
    .with_inputs(vec![
      input!("32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c", 1, _),
    ])
    .with_collaterals(vec![
      input!("32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c", 1),
    ])
    .with_change_strategy(ChangeStrategy::as_last_output(
      address!("addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47"),
    ))
    .with_mint(assets!(
      (
        "bd3ae991b5aafccafe5ca70758bd36a9b2f872f57f6d3a1ffa0eb777",
        "7768617465766572",
        100_i64,
        PlutusData::list::<PlutusData>([]),
      ),
    ))
    .with_validity_interval(SlotBound::None, SlotBound::Exclusive(123456789))
    .with_plutus_scripts(vec![
      plutus_script!(PlutusVersion::V3, "5101010023259800a518a4d136564004ae69")
    ])
    .ok()
  ).unwrap().to_string(),
  indoc!{"
    Transaction (id = 07fbde0af6eaceb28a59f764e442002382181af756707e0ce0325354d2b26fac) {
        inputs: [
            Input(32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c#1),
        ],
        outputs: [
            Output {
                address: addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47,
                value: Value {
                    lovelace: 9824087,
                    assets: {
                        bd3ae991b5aafccafe5ca70758bd36a9b2f872f57f6d3a1ffa0eb777: {
                            whatever: 100,
                        },
                    },
                },
            },
        ],
        fee: 175913,
        validity: ]-∞; 123456789[,
        mint: Value {
            lovelace: 0,
            assets: {
                bd3ae991b5aafccafe5ca70758bd36a9b2f872f57f6d3a1ffa0eb777: {
                    whatever: 100,
                },
            },
        },
        script_integrity_hash: b5a66ea46c7628f9b151d6e029f322058d9dff3793a98f3cfed6e21ed7064c4f,
        collaterals: [
            Input(32b5e793d26af181cb837ab7470ba6e10e15ff638088bc6b099bb22b54b4796c#1),
        ],
        collateral_return: Output {
            address: addr1vx7n46v3kk40ejh7tjnswk9ax65m97rj74lk6wsllg8twacak3e47,
            value: Value {
                lovelace: 9736130,
            },
        },
        total_collateral: 263870,
        scripts: [
            v3(bd3ae991b5aafccafe5ca70758bd36a9b2f872f57f6d3a1ffa0eb777),
        ],
        redeemers: {
            Mint(0): Redeemer(
                CBOR(80),
                ExecutionUnits {
                    mem: 1601,
                    cpu: 316149,
                },
            ),
        },
    }"
  },
);

impl Transaction<InConstruction>

pub fn ok(&mut self) -> Result<&mut Self>

pub fn with_inputs( &mut self, inputs: impl IntoIterator<Item = (Input, Option<PlutusData<'static>>)>, ) -> &mut Self

pub fn with_collaterals( &mut self, collaterals: impl IntoIterator<Item = Input>, ) -> &mut Self

pub fn with_reference_inputs( &mut self, reference_inputs: impl IntoIterator<Item = Input>, ) -> &mut Self

pub fn with_specified_signatories( &mut self, verification_key_hashes: impl IntoIterator<Item = Hash<28>>, ) -> &mut Self

pub fn with_outputs( &mut self, outputs: impl IntoIterator<Item = Output>, ) -> &mut Self

pub fn with_change_strategy(&mut self, with: ChangeStrategy) -> &mut Self

pub fn with_mint( &mut self, mint: BTreeMap<(Hash<28>, PlutusData<'_>), BTreeMap<Vec<u8>, i64>>, ) -> &mut Self

pub fn with_validity_interval( &mut self, from: SlotBound, until: SlotBound, ) -> &mut Self

pub fn with_fee(&mut self, fee: u64) -> &mut Self

pub fn with_datums( &mut self, datums: impl IntoIterator<Item = PlutusData<'static>>, ) -> &mut Self

pub fn with_plutus_scripts( &mut self, scripts: impl IntoIterator<Item = PlutusScript>, ) -> &mut Self

impl Transaction<ReadyForSigning>

pub fn sign(&mut self, signing_key: &SigningKey) -> &mut Self

pub fn sign_with<VerificationKeyLike: Borrow<VerificationKey>, SignatureLike: Borrow<Signature>>( &mut self, sign: impl FnOnce(Hash<32>) -> (VerificationKeyLike, SignatureLike), ) -> &mut Self

Like ‘sign’, but allows signing through a callback to avoid leaking the signing key.

impl<State: IsTransactionBodyState> Transaction<State>

pub fn id(&self) -> Hash<32>

The transaction identifier, as a blake2b-256 hash digest of its serialised body.

While the method can be called at any time, any change on the transaction body will alter the id. It is only stable when the state is [`state::ReadyForSigning`]

pub fn fee(&self) -> u64

pub fn total_collateral(&self) -> u64

pub fn inputs(&self) -> Box<dyn Iterator<Item = Input> + '_>

The declared transaction inputs, which are spent in case of successful transaction.

pub fn collaterals(&self) -> Box<dyn Iterator<Item = Input> + '_>

The declared transaction collaterals, which are spent in case of failed transaction.

pub fn reference_inputs(&self) -> Box<dyn Iterator<Item = Input> + '_>

The declared transaction reference inputs, which are never spent but contribute to the script context for smart-contract execution.

pub fn mint(&self) -> Value<i64>

pub fn outputs(&self) -> Box<dyn Iterator<Item = Output> + '_>

The declared transaction outputs, which are produced in case of successful transaction.

pub fn as_resolved_inputs(&self) -> BTreeMap<Input, Output>

View this transaction as a UTxO, mapping each output to its corresponding input reference.

Trait Implementations

impl<State: IsTransactionBodyState> Debug for Transaction<State>

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

Formats the value using the given formatter.

impl<'d, C> Decode<'d, C> for Transaction<ReadyForSigning>

fn decode(d: &mut Decoder<'d>, ctx: &mut C) -> Result<Self, Error>

Decode a value using the given Decoder.

fn nil() -> Option<Self>

If possible, return a nil value of Self.

impl<'d, C> Decode<'d, C> for Transaction<Unknown>

fn decode(d: &mut Decoder<'d>, ctx: &mut C) -> Result<Self, Error>

Decode a value using the given Decoder.

fn nil() -> Option<Self>

If possible, return a nil value of Self.

impl Default for Transaction<InConstruction>

fn default() -> Self

Returns the “default value” for a type.

impl<State: IsTransactionBodyState> Display for Transaction<State>

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

Formats the value using the given formatter.

impl<C, State: IsTransactionBodyState> Encode<C> for Transaction<State>

fn encode<W: Write>( &self, e: &mut Encoder<W>, ctx: &mut C, ) -> Result<(), Error<W::Error>>

Encode a value of this type using the given Encoder.

fn is_nil(&self) -> bool

Is this value of Self a nil value?