Helios API/ API Reference/ Classes/

Tx

Represents a Cardano transaction. Can also be used as a transaction builder.

Hierarchy

CborData

↳ Tx

Index

Constructors

constructor

• new Tx(body?, witnesses?, valid?, metadata?, validTo?, validFrom?)

Use Tx.new() instead of this constructor for creating a new Tx builder.

Parameters

Name	Type
`body?`	`TxBody`
`witnesses?`	`TxWitnesses`
`valid?`	`boolean`
`metadata?`	`null` \| `TxMetadata`
`validTo?`	`null` \| `bigint` \| `Date`
`validFrom?`	`null` \| `bigint` \| `Date`

Overrides

CborData.constructor

Accessors

body

• get body(): TxBody

Returns

bodyHash

• get bodyHash(): number[]

Returns

number[]

profileReport

• get profileReport(): string

Returns

string

witnesses

• get witnesses(): TxWitnesses

Returns

Methods

addCollateral

▸ addCollateral(input): Tx

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 during transaction building. Returns the transaction instance so build methods can be chained.

Parameters

Name	Type
`input`	`TxInput`

Returns

addDCert

▸ addDCert(dcert): Tx

Add a DCert to the transactions being built. DCert contains information about a staking-related action.

TODO: implement all DCert (de)serialization methods.

Returns the transaction instance so build methods can be chained.

Parameters

Name	Type
`dcert`	`DCert`

Returns

addInput

▸ addInput(input, rawRedeemer?): Tx

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 (unless the script is a known NativeScript).

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

Parameters

Name	Type
`input`	`TxInput`
`rawRedeemer?`	`null` \| `UplcData` \| `HeliosData` \| `UplcDataValue`

Returns

addInputs

▸ addInputs(inputs, redeemer?): Tx

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 (unless the script is a known NativeScript).

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

Parameters

Name	Type
`inputs`	`TxInput`[]
`redeemer?`	`null` \| `UplcData` \| `HeliosData` \| `UplcDataValue`

Returns

addMetadata

▸ addMetadata(tag, data): Tx

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.

Parameters

Name	Type
`tag`	`number`
`data`	`Metadata`

Returns

addOutput

▸ addOutput(output): Tx

Add a TxOutput instance to the transaction being built.

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

Parameters

Name	Type
`output`	`TxOutput`

Returns

addOutputs

▸ addOutputs(outputs): Tx

Add multiple TxOutput instances at once.

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

Parameters

Name	Type
`outputs`	`TxOutput`[]

Returns

addRefInput

▸ addRefInput(input, refScript?): Tx

Add a TxInput instance as a reference input to the transaction being built. Any 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 during transaction building. Returns the transaction instance so build methods can be chained.

Parameters

Name	Type
`input`	`TxInput`
`refScript?`	`null` \| `UplcProgram`

Returns

addRefInputs

▸ addRefInputs(inputs): Tx

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

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

Parameters

Name	Type
`inputs`	`TxInput`[]

Returns

addSignature

▸ addSignature(signature, verify?): Tx

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

Parameters

Name	Type	Description
`signature`	`Signature`
`verify?`	`boolean`	Defaults to `true`

Returns

addSignatures

▸ addSignatures(signatures, verify?): Tx

Adds multiple signatures at once. Only available after the transaction has been finalized. Optionally verifies each signature is correct.

Parameters

Name	Type
`signatures`	`Signature`[]
`verify?`	`boolean`

Returns

addSigner

▸ addSigner(hash): Tx

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 during transaction building. Returns the transaction instance so build methods can be chained.

Parameters

Name	Type
`hash`	`PubKeyHash`

Returns

attachScript

▸ attachScript(program): Tx

Attaches a script witness to the transaction being built. The script witness can be either a UplcProgram or a legacy NativeScript. A UplcProgram instance can be created by compiling a Helios Program. A legacy NativeScript instance can be created by deserializing its original CBOR representation.

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 during transaction building. Returns the transaction instance so build methods can be chained.

Note: a NativeScript must be attached before associated inputs are added or tokens are minted.

Parameters

Name	Type
`program`	`UplcProgram` \| `NativeScript`

Returns

completeInputData

▸ completeInputData(fn): Promise<void>

A serialized tx throws away input information This must be refetched from the network if the tx needs to be analyzed

Parameters

Name	Type
`fn`	(`id`: `TxOutputId`) => `Promise`<`TxOutput`>

Returns

Promise<void>

dump

▸ dump(params?): any

Parameters

Name	Type	Description
`params?`	`null` \| `NetworkParams`	If specified: dump all the runtime details of each redeemer (datum, redeemer, scriptContext)

Returns

any

finalize

▸ finalize(networkParams, changeAddress, spareUtxos?): Promise<Tx>

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.

Sets the validatity range automatically if a call to tx.time_range is detected in any of the attached Helios scripts.

Parameters

Name	Type	Description
`networkParams`	`NetworkParams`
`changeAddress`	`Address`
`spareUtxos?`	`TxInput`[]	might be used during balancing if there currently aren't enough inputs

Returns

Promise<Tx>

id

▸ id(): TxId

Returns

isValid

▸ isValid(slot): boolean

Used by emulator to check if tx is valid.

Parameters

Name	Type
`slot`	`bigint`

Returns

boolean

mintTokens

▸ mintTokens(mph, tokens, redeemer): Tx

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 during transaction building the transaction. Returns the transaction instance so build methods can be chained.

Also throws an error if the redeemer is null, and the minting policy isn't a known NativeScript.

Parameters

Name	Type	Description
`mph`	`HashProps` \| `MintingPolicyHash`
`tokens`	[`ByteArray` \| `ByteArrayProps`, `HInt` \| `HIntProps`][]	list of pairs of [tokenName, quantity], tokenName can be list of bytes or hex-string
`redeemer`	`null` \| `UplcData` \| `UplcDataValue`

Returns

toCbor

▸ toCbor(): number[]

Returns

number[]

Inherited from

CborData.toCbor

toCborHex

▸ toCborHex(): string

Returns

string

Inherited from

CborData.toCborHex

toTxData

▸ toTxData(networkParams): UplcData

Parameters

Name	Type
`networkParams`	`NetworkParams`

Returns

validFrom

▸ validFrom(slotOrTime): Tx

Set the start of the valid time range by specifying either a Date or a slot.

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

Note: since Helios v0.13.29 this is set automatically if any of the Helios validator scripts call tx.time_range.

Parameters

Name	Type
`slotOrTime`	`bigint` \| `Date`

Returns

validTo

▸ validTo(slotOrTime): Tx

Set the end of the valid time range by specifying either a Date or a slot.

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

Note: since Helios v0.13.29 this is set automatically if any of the Helios validator scripts call tx.time_range.

Parameters

Name	Type
`slotOrTime`	`bigint` \| `Date`

Returns

withoutMetadata

▸ withoutMetadata(): Tx

Creates a new Tx without the metadata for client-side signing where the client can't know the metadata before tx-submission.

Returns

finalizeUplcData

▸ Static finalizeUplcData(data, networkParams, changeAddress, spareUtxos, scripts): Promise<Tx>

Used by bundler for macro finalization

Parameters

Name	Type	Description
`data`	`UplcData`
`networkParams`	`NetworkParams`
`changeAddress`	`Address`
`spareUtxos`	`TxInput`[]
`scripts`	`Object`	UplcPrograms can be lazy

Returns

Promise<Tx>

fromCbor

▸ Static fromCbor(raw): Tx

Deserialize a CBOR encoded Cardano transaction (input is either an array of bytes, or a hex string).

Parameters

Name	Type
`raw`	`string` \| `number`[]

Returns

new

▸ Static new(): Tx

Create a new Tx builder.

Returns