@hydra-sdk/transaction

Classes

TxBuilder

Main class for building and managing Cardano transactions with comprehensive support for all Cardano features.

`TxBuilder.constructor(options?: TxBuilderOptions) → TxBuilder`

Initializes a new transaction builder.

Parameters:

options? (TxBuilderOptions): Configuration options
- fetcher?: Custom fetcher
- submitter?: Custom submitter
- isHydra?: Allows creating transactions for Hydra Head
- params?: Custom protocol parameters
- verbose?: Enable verbose mode

Example:

typescript

import { TxBuilder } from '@hydra-sdk/transaction'

// Create a basic builder
const txBuilder = new TxBuilder()

// With custom protocol parameters
const txBuilder = new TxBuilder({
  params: {
    minFeeA: 44,
    minFeeB: 155381,
    maxTxSize: 16384
  }
})

// For Hydra transactions
const txBuilder = new TxBuilder({
  isHydra: true,
  params: protocolParams,
  verbose: true
})

Returns: TxBuilder
A new TxBuilder instance

`TxBuilder.selectUtxosFrom(utxos: UTxO[], strategy?: CoinSelectionStrategy) → TxBuilder`

Select UTxOs using a coin selection strategy.

Parameters:

utxos (UTxO): List of available UTxOs
strategy? (CoinSelectionStrategy): Selection strategy. Default: 'LargestFirstMultiAsset'
- LargestFirst: Select largest coins first
- RandomImprove: Random selection with improvement
- LargestFirstMultiAsset: Multi-asset friendly
- RandomImproveMultiAsset: Multi-asset friendly random

Example:

typescript

const utxos = await wallet.queryUtxos()

// Default strategy
const tx1 = await txBuilder.selectUtxosFrom(utxos).complete()

// Specific strategy
const tx2 = await txBuilder.selectUtxosFrom(utxos, 'RandomImprove').complete()

Returns: TxBuilder
Returns the builder for method chaining

`TxBuilder.setInputs(utxos: UTxO[]) → TxBuilder`

Set specific UTxOs as inputs.

Parameters:

utxos (UTxO): List of UTxOs to use

Example:

typescript

const specificUtxos = utxos.filter(utxo => 
  utxo.output.amount.some(asset => asset.unit !== 'lovelace')
)
const tx = await txBuilder.setInputs(specificUtxos).complete()

Returns: TxBuilder

`TxBuilder.txIn(txHash: string, outputIndex: number, amount?: Asset[], address?: string) → TxBuilder`

Add a transaction input.

Parameters:

txHash (string): Transaction hash
outputIndex (number): Output index
amount? (Asset): Asset amounts (optional)
address? (string): Address (optional)

Example:

typescript

txBuilder.txIn(
  'a1b2c3d4e5f6...',
  0,
  [{ unit: 'lovelace', quantity: '2000000' }],
  'addr_test1...'
)

Returns: TxBuilder

`TxBuilder.txOut(address: string, amount: Asset[]) → TxBuilder`

Add a transaction output.

Parameters:

address (string): Recipient address
amount (Asset): List of assets

Example:

typescript

// ADA only
txBuilder.txOut('addr_test1...', [
  { unit: 'lovelace', quantity: '2000000' }
])

// Multi-asset
txBuilder.txOut('addr_test1...', [
  { unit: 'lovelace', quantity: '2000000' },
  { unit: 'policyId.assetName', quantity: '100' }
])

Returns: TxBuilder

`TxBuilder.changeAddress(address: string) → TxBuilder`

Set the change address.

Parameters:

address (string): Change address

Example:

typescript

const account = wallet.getAccount(0, 0)
txBuilder.changeAddress(account.baseAddressBech32)

Returns: TxBuilder

`TxBuilder.mint(quantity: string, policyId: string, assetName: string) → TxBuilder`

Mint or burn assets.

Parameters:

quantity (string): Quantity (negative to burn)
policyId (string): Policy ID
assetName (string): Asset name

Example:

typescript

// Mint tokens
txBuilder.mint('1000', policyId, 'TokenName')

// Burn tokens
txBuilder.mint('-500', policyId, 'TokenName')

Returns: TxBuilder

`TxBuilder.txInScript(scriptCbor: string) → TxBuilder`

Attach a Plutus script to the last input.

Parameters:

scriptCbor (string): Script in CBOR hex format

Example:

typescript

txBuilder.txIn(txHash, outputIndex)
  .txInScript(scriptCbor)

Returns: TxBuilder

`TxBuilder.txInDatumHash(datum: PlutusData) → TxBuilder`

Add a datum hash for script input.

Parameters:

datum (PlutusData): Plutus data

Example:

typescript

const datum = CardanoWASM.PlutusData.from_hex('d87980')
txBuilder.txIn(txHash, outputIndex)
  .txInDatumHash(datum)

Returns: TxBuilder

`TxBuilder.txInInlineDatum(inlineDatum: PlutusData) → TxBuilder`

Add an inline datum for script input.

Parameters:

inlineDatum (PlutusData): Plutus data

Example:

typescript

const inlineDatum = CardanoWASM.PlutusData.from_hex('d87980')
txBuilder.txIn(txHash, outputIndex)
  .txInInlineDatum(inlineDatum)

Returns: TxBuilder

`TxBuilder.txInEmptyRedeemer() → TxBuilder`

Add an empty redeemer for script input.

Example:

typescript

txBuilder.txIn(txHash, outputIndex)
  .txInScript(scriptCbor)
  .txInEmptyRedeemer()

Returns: TxBuilder

`TxBuilder.txOutInlineDatumValue(inlineDatum: PlutusData) → TxBuilder`

Add an inline datum for the last output.

Parameters:

inlineDatum (PlutusData): Plutus data

Example:

typescript

const datum = CardanoWASM.PlutusData.from_hex('d87980')
txBuilder.txOut('addr_test1...', amount)
  .txOutInlineDatumValue(datum)

Returns: TxBuilder

`TxBuilder.registerStake(rewardAddress: string) → TxBuilder`

Parameters:

rewardAddress (string): Stake reward address

Example:

typescript

txBuilder.registerStake('stake_test1...')

Returns: TxBuilder

`TxBuilder.delegateStake(rewardAddress: string, poolKeyHash: string) → TxBuilder`

Delegate stake to a pool.

Parameters:

rewardAddress (string): Stake reward address
poolKeyHash (string): Pool key hash

Example:

typescript

txBuilder.delegateStake('stake_test1...', 'pool1...')

Returns: TxBuilder

`TxBuilder.withdraw(rewardAddress: string, amount: string) → TxBuilder`

Withdraw rewards from a stake address.

Parameters:

rewardAddress (string): Stake reward address
amount (string): Amount in lovelace

Example:

typescript

txBuilder.withdraw('stake_test1...', '5000000')

Returns: TxBuilder

`TxBuilder.txInCollateral(txHash: string, outputIndex: number, amount: Asset[], address: string) → TxBuilder`

Add a collateral input.

Parameters:

txHash (string): Transaction hash
outputIndex (number): Output index
amount (Asset): Asset amounts
address (string): Address

Example:

typescript

txBuilder.txInCollateral(
  collateralTxHash,
  0,
  [{ unit: 'lovelace', quantity: '5000000' }],
  'addr_test1...'
)

Returns: TxBuilder

`TxBuilder.totalCollateral(amount: string) → TxBuilder`

Set the total collateral amount.

Parameters:

amount (string): Amount in lovelace

Example:

typescript

txBuilder.totalCollateral('5000000')

Returns: TxBuilder

`TxBuilder.metadataValue(label: string, metadata: any) → TxBuilder`

Add metadata to the transaction.

Parameters:

label (string): Metadata label
metadata (any): Metadata content

Example:

typescript

// NFT metadata (CIP-25)
txBuilder.metadataValue('721', {
  [policyId]: {
    [assetName]: {
      name: 'My NFT',
      image: 'ipfs://...',
      description: 'A unique NFT'
    }
  }
})

// Text metadata
txBuilder.metadataValue('674', {
  msg: ['Hello', 'World']
})

Returns: TxBuilder

`TxBuilder.invalidBefore(slot: number) → TxBuilder`

Set the transaction validity start time.

Parameters:

slot (number): Slot number

Example:

typescript

txBuilder.invalidBefore(1000000)

Returns: TxBuilder

`TxBuilder.invalidAfter(slot: number) → TxBuilder`

Set the transaction validity end time.

Parameters:

slot (number): Slot number

Example:

typescript

txBuilder.invalidAfter(2000000)

Returns: TxBuilder

`TxBuilder.complete() → Promise<Transaction>`

Build and complete the transaction.

Example:

typescript

const tx = await txBuilder
  .selectUtxosFrom(utxos)
  .txOut('addr_test1...', [{ unit: 'lovelace', quantity: '2000000' }])
  .changeAddress(changeAddress)
  .complete()

console.log('Transaction CBOR:', tx.to_hex())

Returns: Promise<Transaction>
Completed transaction

`TxBuilder.reset() → TxBuilder`

Reset the builder to its initial state.

Example:

typescript

txBuilder.reset()
// Builder is ready for a new transaction

Returns: TxBuilder

`TxBuilder.calculateFee() → BigNum`

Calculate the minimum fee.

Example:

typescript

const minFee = txBuilder.calculateFee()
console.log('Minimum fee:', minFee.to_str())

Returns: BigNum
Minimum fee

`TxBuilder.minAda(output: TransactionOutput, protocolParams: Protocol) → BigNum` (Static)

Calculate minimum ADA for an output.

Parameters:

output (TransactionOutput): Transaction output
protocolParams (Protocol): Protocol parameters

Example:

typescript

const output = CardanoWASM.TransactionOutput.new(
  CardanoWASM.Address.from_bech32('addr_test1...'),
  CardanoWASM.Value.new(CardanoWASM.BigNum.from_str('1000000'))
)

const minAda = TxBuilder.minAda(output, protocolParams)
console.log('Minimum ADA:', minAda.to_str())

Returns: BigNum
Minimum ADA amount

Utility Functions

`buildDatum(data: any) → PlutusData`

Build PlutusData from data.

Parameters:

data (any): Input data

Example:

typescript

import { buildDatum } from '@hydra-sdk/transaction'

const datum = buildDatum({
  constructor: 0,
  fields: [{ int: 42 }, { bytes: 'a1b2' }]
})

Returns: PlutusData

`buildRedeemer() → Redeemer`

Build a redeemer for Plutus script.

Example:

typescript

import { buildRedeemer } from '@hydra-sdk/transaction'

const redeemer = buildRedeemer()

Returns: Redeemer

`emptyRedeemer() → Redeemer`

Create an empty redeemer.

Example:

typescript

import { emptyRedeemer } from '@hydra-sdk/transaction'

const redeemer = emptyRedeemer()

Returns: Redeemer

`metadataObjToMetadatum(obj: any) → TransactionMetadatum`

Convert metadata object to TransactionMetadatum.

Parameters:

obj (any): Metadata object

Example:

typescript

import { metadataObjToMetadatum } from '@hydra-sdk/transaction'

const metadata = metadataObjToMetadatum({
  '1': 'Hello',
  '2': 12345
})

Returns: TransactionMetadatum

Types and Interfaces

TxBuilderOptions

typescript

interface TxBuilderOptions {
  fetcher?: IFetcher
  submitter?: ISubmitter
  isHydra?: boolean
  params?: Partial<Protocol>
  verbose?: boolean
}

CoinSelectionStrategy

typescript

type CoinSelectionStrategy = 
  | 'LargestFirst'
  | 'RandomImprove'
  | 'LargestFirstMultiAsset'
  | 'RandomImproveMultiAsset'

Asset

typescript

interface Asset {
  unit: string      // 'lovelace' or 'policyId.assetName'
  quantity: string  // Amount as string
}

Complete Examples

Simple ADA Transfer

typescript

import { TxBuilder } from '@hydra-sdk/transaction'
import { AppWallet } from '@hydra-sdk/core'

async function sendAda() {
  const wallet = new AppWallet({
    networkId: 0,
    key: { type: 'mnemonic', words: AppWallet.brew() }
  })

  const account = wallet.getAccount(0, 0)
  const utxos = await wallet.queryUtxos(account.baseAddressBech32)

  const tx = await new TxBuilder()
    .selectUtxosFrom(utxos)
    .txOut('addr_test1qqr585tvlc7ylnqvz8pyqwauzrdu0mxag3m7q56grgmgu7sxu2hyfhlkwuxupa9d5085eunq2qywy7hvmvej456flknswgndm3', [
      { unit: 'lovelace', quantity: '2000000' }
    ])
    .changeAddress(account.baseAddressBech32)
    .complete()

  const signedTx = await wallet.signTx(tx.to_hex(), false, 0, 0)
  console.log('Signed transaction:', signedTx)
}

Multi-Asset Transaction

typescript

async function sendMultiAsset() {
  const tx = await new TxBuilder()
    .selectUtxosFrom(utxos)
    .txOut('addr_test1...', [
      { unit: 'lovelace', quantity: '2000000' },
      { unit: 'policyId.TokenA', quantity: '100' },
      { unit: 'policyId.TokenB', quantity: '50' }
    ])
    .changeAddress(changeAddress)
    .complete()

  return tx
}

NFT Minting with Metadata

typescript

async function mintNFT() {
  const policyId = 'your_policy_id'
  const assetName = 'MyNFT'
  const mintingScript = 'minting_script_cbor'

  const tx = await new TxBuilder()
    .selectUtxosFrom(utxos)
    .mint('1', policyId, assetName)
    .txOut(recipientAddress, [
      { unit: 'lovelace', quantity: '2000000' },
      { unit: `${policyId}.${assetName}`, quantity: '1' }
    ])
    .metadataValue('721', {
      [policyId]: {
        [assetName]: {
          name: 'My Unique NFT',
          image: 'ipfs://QmHash...',
          description: 'A one-of-a-kind digital collectible'
        }
      }
    })
    .changeAddress(changeAddress)
    .complete()

  return tx
}

Plutus Script Interaction

typescript

async function interactWithPlutusScript() {
  const scriptCbor = 'plutus_script_cbor'
  const datum = CardanoWASM.PlutusData.new_map(
    CardanoWASM.PlutusMap.new()
  )

  const tx = await new TxBuilder()
    .selectUtxosFrom(utxos)
    .txIn(scriptUtxoHash, scriptUtxoIndex)
    .txInScript(scriptCbor)
    .txInDatumHash(datum)
    .txInEmptyRedeemer()
    .txInCollateral(collateralHash, 0, [{ unit: 'lovelace', quantity: '5000000' }], collateralAddress)
    .txOut(recipientAddress, [{ unit: 'lovelace', quantity: '10000000' }])
    .changeAddress(changeAddress)
    .complete()

  return tx
}

Core API - Wallet and utilities
Hydra Bridge API - Hydra Layer 2 integration