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

Native Script Utilities

POST /utils/native-scripts/get-info

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

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

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

Best Practices

1. Environment Awareness

   • Remember that slot calculations differ between Mainnet, Preprod, and other networks

   • 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

Integration Example

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

// Example: Converting a date to a slot number for a policy script
async function dateToSlotForPolicy(date) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/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;
}

Other Resources

• Explore Policy Units to understand how Cardano measures assets

• Learn about Automatic UTXO Selection for transaction building

• Build transactions with the Transaction guides