Utility Functions

Anvil Utility Functions

Anvil provides several utility endpoints to simplify common operations when building Cardano applications. These endpoints handle tasks like address parsing, native script analysis, and time-slot conversions.

Available Utility Endpoints

Address Utilities

POST /utils/addresses/parse

What It Does:

• Extracts payment and stake key hashes from Cardano addresses

Parameters:

• address: Bech32 or hex encoded address

Returns:

• payment: Payment key hash (hex encoded)

• stake: Optional stake key hash (hex encoded)

Common Use Case:

• Getting the payment key hash from a wallet address for policy scripts

• Extracting stake key hash for delegation operations

TypeScript Example: Parse an address

async function getPaymentCredentialFromAddress(address) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/addresses/parse', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      address: address
    })
  });

  return await response.json();
}
// Sample Output
// {
//   "payment": "addr1egrtarthsndgre...",
//   "stake": "stake1grhyjajuwsfbudh...",
// }

Native Script Utilities

POST /utils/native-scripts/parse

What It Does:

• Calculates policy ID and returns policy ID from the provided native script

Parameters:

• script: Hex encoded native script

Returns:

• policyId: The hash of the script (policy ID)

Common Use Case:

• Extracting a policy ID from a minting script

• Verifying script properties before transaction submission

TypeScript Example: Get policy ID from a native script

async function getPolicyId(nativeScriptHex) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/native-scripts/get-info', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      script: nativeScriptHex
    })
  });

  const result = await response.json();
  return result.policyId;
}
// Sample Output
// {
//   "policyId": "df37e17a949b061c15c53c485609652a6516315de90a88b611c03a9c"
// }

Network Time Utilities

POST /utils/network/slot-to-time

What It Does:

• Converts a Cardano slot number to a timestamp

Parameters:

• slot: Absolute slot number

Returns:

• time: Unix timestamp in milliseconds (UTC)

Common Use Case:

• Converting slot-based time locks to human-readable dates

• Displaying blockchain time information to users

TypeScript Example: Convert a slot to a timestamp

async function slotToTimestamp(slotNumber) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/network/slot-to-time', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      slot: slotNumber
    })
  });

  const result = await response.json();
  // Returns Unix timestamp in milliseconds
  return new Date(result.time);
}

POST /utils/network/time-to-slot

What It Does:

• Returns the enclosing slot of the provided timestamp

Parameters:

• time: Unix timestamp in milliseconds (UTC)

Returns:

• slot: Absolute slot number

Common Use Case:

• Setting expiration times for minting policies

• Creating time-bounded transactions

TypeScript Example: Convert a date to a slot

async function dateToSlot(date) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/network/time-to-slot', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      time: date.getTime() // Unix timestamp in milliseconds
    })
  });

  const result = await response.json();
  return result.slot;
}

Best Practices

1. Environment Awareness

   • Remember that slot calculations differ between Mainnet, Preprod, and Preview

   • Always use the appropriate network endpoint for your target environment

2. Error Handling

   • Always check for error responses from utility endpoints

   • Handle edge cases appropriately in your application logic

3. Caching

   • Consider caching results from utility functions when appropriate

   • This can reduce API calls and improve application performance