Tx

Represents a cardano transaction. Can also be used a transaction builder.

Constructor

Init a new transaction builder.

new helios.Tx()

Static methods

fromCbor

Deserialize a CBOR encoded Cardano transaction.

helios.Tx.fromCbor(bytes: number[]): helios.Tx

Methods

addCollateral

Add a UTxO instance as collateral to the transaction being built. Usually adding only one collateral input is enough. The number of collateral inputs must be greater than 0 if script witnesses are used in the transaction, and must be less than the limit defined in the NetworkParams.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addCollateral(input: helios.TxInput): helios.Tx

addInput

Add a UTxO instance as an input to the transaction being built. Throws an error if the UTxO is locked at a script address but a redeemer isn't specified.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addInput(
    input: helios.UTxO,
    redeemer: ?(helios.UplcData | helios.UplcDataValue) = null
): helios.Tx

addInputs

Add multiple UTxO instances as inputs to the transaction being built. Throws an error if the UTxOs are locked at a script address but a redeemer isn't specified.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addInputs(
    inputs: helios.UTxO[],
    redeemer: ?(helios.UplcData | helios.UplcDataValue) = null
): helios.Tx

addMetadata

Add metadata to a transaction. Metadata can be used to store data on-chain, but can't be consumed by validator scripts. Metadata can for example be used for CIP 25.

tx.addMetadata(
    tag: number, // whole number
    metadata: Metadata
)

The Metadata type is an alias for the following JSON schema:

@typedef {
  string |
  number | // whole numbers only
  Metadata[] | 
  {map: [Metadata, Metadata][]} // a map is implemented as a list of pairs because order needs to be respected
} Metadata

addOutput

Add a TxOutput instance to the transaction being built.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addOutput(output: helios.TxOutput): helios.Tx

addOutputs

Add multiple TxOutput instances at once.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addOutputs(outputs: helios.TxOutput[]): helios.Tx

addRefInput

Add a TxRefInput instance as a reference input to the transaction being built. An associated reference script, as a UplcProgram instance, must also be included in the transaction at this point (so the that the execution budget can be calculated correctly).

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addRefInput(
    input: helios.TxRefInput
    refScript: ?helios.UplcProgram = null
): helios.Tx

addRefInputs

Add multiple TxRefInput instances as reference inputs to the transaction being built.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addRefInputs(inputs: helios.TxRefInput[]): helios.Tx

addSignature

Add a signature created by a wallet. Only available after the transaction has been finalized. Optionally verify that the signature is correct.

tx.addSignature(
    signature: helios.Signature,
    verify: boolean = true
): helios.Tx

addSignatures

Add multiple signatures at once. Only available after the transaction has been finalized. Optionally verify correctness (could be slow for many signatures).

tx.addSignatures(
    signatures: helios.Signature[],
    verify: boolean = true
): helios.Tx

addSigner

Add a signatory PubKeyHash to the transaction being built. The added entry becomes available in the tx.signatories field in the Helios script.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.addSigner(hash: helios.PubKeyHash): helios.Tx

attachScript

Attach a script witness to the transaction being built. The script witness is a UplcProgram instance and can be created by compiling a Helios Program.

Throws an error if script has already been added. Throws an error if the script isn't used upon finalization.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.attachScript(script: helios.UplcProgram): helios.Tx

finalize

Executes all the attached scripts with appropriate redeemers and calculates execution budgets. Balances the transaction, and optionally uses some spare UTxOs if the current inputs don't contain enough lovelace to cover the fees and min output deposits.

Inputs, minted assets, and withdrawals are sorted.

tx.finalize(
    networkParams: helios.NetworkParams,
    changeAddress: helios.Address,
    spareUtxos:    helios.UTxO[]
): Promise<Tx>

mintTokens

Mint a list of tokens associated with a given MintingPolicyHash. Throws an error if the given MintingPolicyHash was already used in a previous call to mintTokens. The token names can either by a list of bytes or a hexadecimal string.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.mintTokens(
    mph: helios.MintingPolicyHash,
    tokens: [number[] | string, bigint][],
    redeemer: helios.UplcData | helios.UplcDataValue
): helios.Tx

toCbor

Serialize a transaction.

tx.toCbor(): number[]

validFrom

Set the start of the valid time range.

Mutates the transaction. Only available when building the transaction. Returns the transaction instance so build methods can be chained.

tx.validFrom(time: Date): helios.Tx

validTo

Set the end of the valid time range. Mutates the transaction. Only available when building a transaction.

Returns the transaction instance so build methods can be chained.

tx.validTo(time: Date): helios.Tx