evaluateTransaction

Evaluate script execution costs for a transaction

Evaluate the execution cost of Plutus scripts in a transaction without submitting it. This is essential for setting correct execution unit budgets and calculating accurate fees.

Request

{
  "jsonrpc": "2.0",
  "method": "evaluateTransaction",
  "params": {
    "transaction": {
      "cbor": "84a400818258203e40d0530281df85e08fb0c5ac7a44c8cd94cabae4b6d32f0c29ab05dcfc79e600..."
    },
    "additionalUtxo": [
      {
        "transaction": { "id": "abc123..." },
        "index": 0,
        "address": "addr1...",
        "value": { "ada": { "lovelace": 10000000 } }
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
`transaction.cbor`	`string`	Yes	Transaction in CBOR hex format
`additionalUtxo`	`array`	No	Additional UTxOs to include in evaluation context

The transaction doesn't need to be signed for evaluation. This allows you to calculate costs before signing.

Response

{
  "jsonrpc": "2.0",
  "method": "evaluateTransaction",
  "result": [
    {
      "validator": {
        "purpose": "spend",
        "index": 0
      },
      "budget": {
        "memory": 1234567,
        "cpu": 987654321
      }
    },
    {
      "validator": {
        "purpose": "mint",
        "index": 0
      },
      "budget": {
        "memory": 234567,
        "cpu": 123456789
      }
    }
  ]
}

Response Fields

Field	Type	Description
`validator.purpose`	`string`	Script purpose: `spend`, `mint`, `withdraw`, `publish`
`validator.index`	`number`	Index in the transaction inputs/mints/etc.
`budget.memory`	`number`	Memory units required
`budget.cpu`	`number`	CPU steps required

Code Examples

async function evaluateTransaction(txCbor, additionalUtxos = []) {
const response = await fetch('https://api.nacho.builders/v1/ogmios', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.NACHO_API_KEY
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'evaluateTransaction',
    params: {
      transaction: { cbor: txCbor },
      additionalUtxo: additionalUtxos
    }
  })
});

const data = await response.json();

if (data.error) {
  console.error('Evaluation failed:', data.error.message);
  throw new Error(data.error.message);
}

return data.result;
}

// Calculate total execution units
function getTotalExUnits(evaluationResult) {
return evaluationResult.reduce((acc, item) => ({
  memory: acc.memory + item.budget.memory,
  cpu: acc.cpu + item.budget.cpu
}), { memory: 0, cpu: 0 });
}

const result = await evaluateTransaction(txCbor);
const total = getTotalExUnits(result);
console.log('Total memory:', total.memory);
console.log('Total CPU:', total.cpu);

Error Responses

Invalid Script

{
  "error": {
    "code": 3100,
    "message": "Script execution failed",
    "data": {
      "validationError": "ExUnitsTooBig",
      "scriptHash": "abc123...",
      "reason": "Exceeded maximum execution units"
    }
  }
}

Missing Datum

{
  "error": {
    "code": 3101,
    "message": "Missing datum",
    "data": {
      "datumHash": "abc123..."
    }
  }
}

Missing Redeemer

{
  "error": {
    "code": 3102,
    "message": "Missing redeemer",
    "data": {
      "scriptHash": "abc123..."
    }
  }
}

Workflow: Build → Evaluate → Submit

async function buildAndSubmitTx() {
  // 1. Build transaction (without execution units)
  const txDraft = buildTransaction({
    inputs: [...],
    outputs: [...],
    collateral: [...],
    // Don't include exUnits yet
  });

  // 2. Evaluate to get execution units
  const evaluation = await evaluateTransaction(txDraft.toCbor());

  // 3. Update transaction with execution units
  const txWithUnits = txDraft.setExUnits(evaluation);

  // 4. Calculate final fee
  const fee = calculateFee(txWithUnits, protocolParams);
  const txWithFee = txWithUnits.setFee(fee);

  // 5. Sign and submit
  const signedTx = sign(txWithFee, signingKey);
  const txHash = await submitTransaction(signedTx.toCbor());

  return txHash;
}

Always add a small buffer (10-20%) to evaluated execution units to account for variance in actual execution.

Additional UTxOs

Use additionalUtxo when evaluating transactions that depend on UTxOs not yet on-chain (e.g., in a multi-transaction workflow):

// Transaction B depends on UTxO from Transaction A (not yet submitted)
const evaluation = await evaluateTransaction(txBCbor, [
  {
    transaction: { id: txAHash },
    index: 0,
    address: "addr1...",
    value: { ada: { lovelace: 10000000 } },
    datum: "d8799f..." // If script requires datum
  }
]);

Use Cases

Fee calculation - Determine exact fees before signing
Script debugging - Validate scripts work correctly
Cost estimation - Show users expected costs
Budget optimization - Ensure scripts fit within limits

Full Ogmios API Reference

Was this page helpful?