Developer Tools

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.

See full examples of the utility functions in the examples repository.

Quick Reference#

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 native scripts
• Extracting stake key hash for delegation operations

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...",
// }

POST /addresses/info#

What It Does:

• Returns detailed information about a Cardano address including payment and stake hashes
• Detects whether payment and stake hashes are script-based or key-based

Parameters:

• address: Bech32 or hex encoded address

Returns:

• payment: Object containing payment hash information
  • hash: Payment hash (hex encoded)
  • isScript: Boolean indicating if payment hash is a script hash
• stake: Optional object containing stake hash information
  • hash: Stake hash (hex encoded)
  • isScript: Boolean indicating if stake hash is a script hash

Common Use Cases:

• Transaction Building: Extract payment hashes for transaction inputs/outputs and stake hashes for delegation
• Address Analysis: Determine if an address uses script hashes for smart contract interactions
• Multi-signature Setup: Identify key hashes for multi-sig wallet configurations
• Staking Management: Extract stake hashes for delegation to different stake pools
• Policy Creation: Use payment hashes as conditions in native script minting policies

async function getAddressInfo(address) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/addresses/info', {
    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": {
//     "hash": "1dd6dd756e5397e019debb4d116e11748a93d2f09fd7a894ec8f8af2",
//     "isScript": false
//   },
//   "stake": {
//     "hash": "7ba59464b2e19d6dcb3af04f6c0529a42d489290f3595ad68836df09",
//     "isScript": false
//   }
// }

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

async function getPolicyId(nativeScriptHex) {
  const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/utils/native-scripts/parse', {
    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"
// }

POST /utils/native-scripts/serialize#

What It Does:

• Converts a native script JSON schema into CBOR hex-encoded format and generates its policy ID
• Essential for creating minting policies that can be used in transactions

Parameters:

• schema: The JSON representation of the native script (see Native Scripts documentation for structure details)

Returns:

• policyId: The hash of the script - this becomes your token's policy ID
• script: The CBOR hex-encoded script ready for transactions

Common Use Cases:

• Creating minting policies for NFT collections
• Setting up time-locked or multi-signature token policies

async function createNativeScript(keyHash, slotNumber) {
  // Define a native script that requires signature AND time constraint
  const nativeScriptSchema = {
    type: "all",
    scripts: [
      {
        type: "sig",
        keyHash: keyHash // Payment key hash from wallet
      },
      {
        type: "before",
        slot: slotNumber // Minting deadline slot
      }
    ]
  };

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

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

// Sample Output
// {
//   "policyId": "df37e17a949b061c15c53c485609652a6516315de90a88b611c03a9c",
//   "script": "8201828200581c3910f0db63599cd9cb1484d5591491629470761a89cde0473e4b94f682051a06a60080"
// }

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 DateTimes
• Displaying blockchain time information to users

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
• Creating time-bounded transactions

async function timeToSlot(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