Protocol Utilities

Use protocol utility functions for hashing and calculations

The @zkp2p/contracts-v2/utils/protocolUtils module provides utility functions for protocol operations including hashing, currency handling, and intent calculations.

Import Utilities

import { 
  getKeccak256Hash,
  calculateIntentHash,
  Currency,
  getCurrencyCodeFromHash,
  calculatePaymentMethodHash
} from '@zkp2p/contracts-v2/utils/protocolUtils';

Currency Constants

The Currency object provides pre-computed Keccak256 hashes for all supported currencies:

import { Currency } from '@zkp2p/contracts-v2/utils/protocolUtils';

console.log(Currency.USD);
// "0xc4ae21aac0c6549d71dd96035b7e0bdb6c79ebdba8891b666115bc976d16a29e"

console.log(Currency.EUR);
// "0xfff16d60be267153303bbfa66e593fb8d06e24ea5ef24b6acca5224c2ca6b907"

console.log(Currency.GBP);
// "0x90832e2dc3221e4d56977c1aa8f6a6706b9ad6542fbbdaac13097d0fa5e42e67"

Supported Currencies

All 33 supported currency codes:

Major Currencies

• USD - United States Dollar
• EUR - Euro
• GBP - British Pound Sterling
• JPY - Japanese Yen
• CHF - Swiss Franc
• CAD - Canadian Dollar
• AUD - Australian Dollar
• NZD - New Zealand Dollar

Asian Currencies

• CNY - Chinese Yuan
• HKD - Hong Kong Dollar
• SGD - Singapore Dollar
• INR - Indian Rupee
• IDR - Indonesian Rupiah
• MYR - Malaysian Ringgit
• PHP - Philippine Peso
• THB - Thai Baht
• VND - Vietnamese Dong

European Currencies

• CZK - Czech Koruna
• DKK - Danish Krone
• HUF - Hungarian Forint
• NOK - Norwegian Krone
• PLN - Polish Zloty
• RON - Romanian Leu
• SEK - Swedish Krona

Other Currencies

• AED - UAE Dirham
• ARS - Argentine Peso
• ILS - Israeli Shekel
• KES - Kenyan Shilling
• MXN - Mexican Peso
• SAR - Saudi Riyal
• TRY - Turkish Lira
• UGX - Ugandan Shilling
• ZAR - South African Rand

Hashing Functions

getKeccak256Hash

Compute Keccak256 hash of a string value:

import { getKeccak256Hash } from '@zkp2p/contracts-v2/utils/protocolUtils';

const hash = getKeccak256Hash("venmo");
console.log(hash);
// "0x90262a3db0edd0be2369c6b28f9e8511ec0bac7136cefbada0880602f87e7268"

// Hash payment provider domain
const providerHash = getKeccak256Hash("venmo.com");

value · string · required

The string value to hash

return · string

Keccak256 hash as a hex string with 0x prefix

calculatePaymentMethodHash

Calculate payment method hash (alias for getKeccak256Hash):

import { calculatePaymentMethodHash } from '@zkp2p/contracts-v2/utils/protocolUtils';

const venmoHash = calculatePaymentMethodHash("venmo");
const revolutHash = calculatePaymentMethodHash("revolut");
const wiseHash = calculatePaymentMethodHash("wise");

Intent Hash Calculation

calculateIntentHash

Calculate the unique hash for an intent, constrained to the Circom field:

import { ethers } from 'ethers';
import { calculateIntentHash } from '@zkp2p/contracts-v2/utils/protocolUtils';

const orchestratorAddress = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4";
const intentCounter = 12345;

const intentHash = calculateIntentHash(
  orchestratorAddress,
  intentCounter
);

console.log('Intent Hash:', intentHash);
// "0x..."

orchestrator · string · required

Address of the Orchestrator contract

intentCounter · BigNumber | number · required

The intent counter value (can be ethers BigNumber or number)

return · string

Intent hash constrained to Circom field, zero-padded to 32 bytes

The intent hash is computed as keccak256(orchestrator, intentCounter) modulo the Circom field prime: 21888242871839275222246405745257275088548364400416034343698204186575808495617

Currency Helpers

getCurrencyCodeFromHash

Reverse lookup to get currency code from its hash:

import { Currency, getCurrencyCodeFromHash } from '@zkp2p/contracts-v2/utils/protocolUtils';

const usdHash = Currency.USD;
const code = getCurrencyCodeFromHash(usdHash);
console.log(code); // "USD"

// Unknown hash returns empty string
const unknown = getCurrencyCodeFromHash("0xinvalidhash");
console.log(unknown); // ""

hash · string · required

The currency hash to look up

return · string

Currency code (e.g., “USD”, “EUR”) or empty string if not found

Complete Example

Building Intent Parameters

import { ethers } from 'ethers';
import { base } from '@zkp2p/contracts-v2/addresses';
import { Orchestrator } from '@zkp2p/contracts-v2/abis/base';
import { 
  Currency,
  calculateIntentHash,
  calculatePaymentMethodHash 
} from '@zkp2p/contracts-v2/utils/protocolUtils';

const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

const orchestrator = new ethers.Contract(
  base.Orchestrator,
  Orchestrator,
  signer
);

// Get current intent counter for this address
const userAddress = await signer.getAddress();
const intentCounter = await orchestrator.intentCounter(userAddress);

// Calculate intent hash
const intentHash = calculateIntentHash(
  base.Orchestrator,
  intentCounter
);

console.log('Intent Hash:', intentHash);

// Prepare intent parameters
const depositId = 1;
const amount = ethers.utils.parseUnits('100', 6); // 100 USDC
const to = await signer.getAddress();
const paymentMethodHash = calculatePaymentMethodHash('venmo');
const currencyHash = Currency.USD;
const priceLimit = ethers.utils.parseUnits('1.01', 6); // 1.01 price limit
const paymentIdentifier = "[e-mail]";
const encryptedPaymentDetails = "0x..."; // Encrypted details

// Signal intent
const tx = await orchestrator.signalIntent(
  depositId,
  amount,
  to,
  paymentMethodHash,
  currencyHash,
  priceLimit,
  paymentIdentifier,
  encryptedPaymentDetails
);

await tx.wait();
console.log('Intent signaled with hash:', intentHash);

Currency Validation

import { Currency, getCurrencyCodeFromHash } from '@zkp2p/contracts-v2/utils/protocolUtils';
import { base as paymentMethods } from '@zkp2p/contracts-v2/paymentMethods';

function validateCurrencyForPaymentMethod(
  paymentMethod: string,
  currencyHash: string
): boolean {
  const config = paymentMethods.methods[paymentMethod];
  
  if (!config) {
    throw new Error(`Unknown payment method: ${paymentMethod}`);
  }
  
  const isSupported = config.currencies.includes(currencyHash);
  
  if (!isSupported) {
    const currencyCode = getCurrencyCodeFromHash(currencyHash);
    console.error(
      `${paymentMethod} does not support ${currencyCode || 'this currency'}`
    );
  }
  
  return isSupported;
}

// Validate Venmo supports USD
const valid = validateCurrencyForPaymentMethod('venmo', Currency.USD);
console.log('Valid:', valid); // true

// Validate Venmo supports EUR (will fail)
const invalid = validateCurrencyForPaymentMethod('venmo', Currency.EUR);
// Error: venmo does not support EUR

Type Definitions

// Currency object type
const Currency: Readonly<{
  AED: string;
  ARS: string;
  AUD: string;
  // ... all 33 currencies
  ZAR: string;
}>;

// Function signatures
function getKeccak256Hash(value: string): string;
function calculatePaymentMethodHash(paymentMethod: string): string;
function calculateIntentHash(
  orchestrator: string,
  intentCounter: BigNumber | number
): string;
function getCurrencyCodeFromHash(hash: string): string;

Next Steps

Payment Methods

Work with payment method configurations

Constants

Access protocol constants