Radix Utils

A comprehensive utility library for Radix DLT blockchain development, providing helper functions for working with validators, staking, and various Radix-specific operations.

Installation

npm install radix-utils

Features

• Validator Information: Fetch comprehensive validator data including staking amounts, fees, and vault information
• Resource Checking: Check fungible resource balances across multiple accounts
• Fee Calculations: Compute validator fee factors with pending changes
• Date Utilities: Calculate unlock dates based on epoch information
• Decimal Operations: Radix-specific decimal operations with proper precision
• TypeScript Support: Full TypeScript definitions included

Quick Start

import { fetchValidatorInfo, BN, GatewayApiClient } from 'radix-utils';

// Initialize the Gateway API client
const gatewayApi = GatewayApiClient.initialize({
  networkId: 1, // Mainnet
  applicationName: 'Your App Name',
  applicationVersion: '1.0.0',
});

// Fetch validator information
const validatorAddress = 'validator_rdx1sd...';
const validatorInfo = await fetchValidatorInfo(gatewayApi, validatorAddress);

if (validatorInfo) {
  console.log('Total Staked XRD:', validatorInfo.totalStakedXrds);
  console.log('Current Fee:', validatorInfo.fees.current);
  console.log('Validator Metadata:', validatorInfo.metadata);
}

API Reference

Validator Functions

fetchValidatorInfo(gatewayApi, validatorAddress)

Fetches comprehensive information about a validator.

Parameters:

• gatewayApi: GatewayApiClient instance
• validatorAddress: String - The validator address (must start with 'validator_')

Returns: Promise<ValidatorInfo | undefined>

Example:

const info = await fetchValidatorInfo(gatewayApi, 'validator_rdx1sd...');
console.log(info?.totalStakedXrds);

checkResourceInUsersFungibleAssets(usersAddresses, fungibleResourceToCheck, gatewayApi, ledgerState?)

Checks if a specific fungible resource exists in users' accounts.

Parameters:

• usersAddresses: String[] - Array of account addresses to check
• fungibleResourceToCheck: String - Resource address to look for
• gatewayApi: GatewayApiClient instance
• ledgerState?: LedgerStateSelector (optional)

Returns: Promise<ResourceCheckResult>

Example:

const result = await checkResourceInUsersFungibleAssets(
  ['account_rdx1...', 'account_rdx2...'],
  'resource_rdx1...',
  gatewayApi
);
console.log('Total Amount:', result.totalAmount);
console.log('Users with Resource:', result.usersWithResourceAmount);

computeValidatorFeeFactor(currentFeeFactor, newFeeFactor, currentEpoch)

Computes validator fee factor information including pending changes.

Parameters:

• currentFeeFactor: String - Current fee factor as decimal string
• newFeeFactor: NewFeeFactor | null - New fee factor configuration
• currentEpoch: Number - Current epoch number

Returns: FeeFactor

fetchWalletBalances(gatewayApi, walletAddress, ledgerState?)

Fetches complete wallet balances including both fungible and non-fungible tokens with automatic pagination.

Parameters:

• gatewayApi: GatewayApiClient instance
• walletAddress: String - The wallet address to fetch balances for
• ledgerState?: LedgerStateSelector (optional) - For historical data

Returns: Promise<WalletBalances>

Example:

const balances = await fetchWalletBalances(gatewayApi, 'account_rdx1...');

// Access fungible token balances
Object.entries(balances.fungible).forEach(([address, balance]) => {
  console.log(`Token ${address}: ${balance.amount}`);
});

// Access NFT collections
Object.entries(balances.nonFungible).forEach(([address, collection]) => {
  console.log(`NFT Collection ${address}: ${collection.ids.length} items`);
});

Utility Functions

BN(value)

Creates a new Decimal instance with Radix-specific precision configuration.

Parameters:

• value: String | Number - Value to convert to Decimal

Returns: Decimal

Example:

const amount = BN('1000.123456789');
const result = amount.plus('500.987654321');
console.log(result.toString());

calculateEstimatedUnlockDate(epochUnlocked, currentEpoch)

Calculates the estimated unlock date based on epoch information.

Parameters:

• epochUnlocked: Number - Epoch when stake will be unlocked
• currentEpoch: Number - Current epoch number

Returns: String - Formatted date string

Example:

const unlockDate = calculateEstimatedUnlockDate(1500, 1400);
console.log('Estimated unlock:', unlockDate);

retryPromiseAll(promises, retries?, delay?)

Executes Promise.all with retry logic and exponential backoff.

Parameters:

• promises: Promise[] - Array of promises to execute
• retries?: Number (default: 3) - Number of retry attempts
• delay?: Number (default: 1000) - Initial delay in milliseconds

Returns: Promise<T[]>

Transaction Functions

getEventFromTransaction(gatewayApi, txId, eventName)

Extracts a specific event from a transaction's detailed events.

Parameters:

• gatewayApi: GatewayApiClient instance
• txId: String - Transaction intent hash
• eventName: String - Name of the event to extract

Returns: Promise<DetailedEventsItem>

Example:

const event = await getEventFromTransaction(
  gatewayApi,
  'txid_rdx1...',
  'WithdrawEvent'
);
console.log('Event data:', event);

getEventKeyValuesFromTransaction(gatewayApi, txId, eventName)

Extracts key-value pairs from a specific event in a transaction.

Parameters:

• gatewayApi: GatewayApiClient instance
• txId: String - Transaction intent hash
• eventName: String - Name of the event to extract

Returns: Promise<Record<string, string>>

Example:

const keyValues = await getEventKeyValuesFromTransaction(
  gatewayApi,
  'txid_rdx1...',
  'TransferEvent'
);
console.log('Amount:', keyValues.amount);
console.log('Recipient:', keyValues.recipient);

extractValuesFromTxEvent(event)

Extracts key-value pairs from a transaction event's fields.

Parameters:

• event: DetailedEventsItem - The event object to extract values from

Returns: Record<string, string>

Example:

const event = await getEventFromTransaction(gatewayApi, txId, 'MyEvent');
const values = extractValuesFromTxEvent(event);
console.log('Extracted values:', values);

TypeScript Types

The library exports comprehensive TypeScript types:

import type {
  ValidatorInfo,
  ValidatorVaults,
  UnlockingRewards,
  FeeFactor,
  ResourceCheckResult,
  WalletBalances,
  FungibleBalances,
  NonFungibleBalances,
} from 'radix-utils';

Key Types

• ValidatorInfo: Complete validator information including staking data, fees, and metadata
• ValidatorVaults: Validator vault addresses
• UnlockingRewards: Array of unlocking reward entries
• FeeFactor: Fee factor information with current and pending changes
• ResourceCheckResult: Result of resource balance checks
• WalletBalances: Complete wallet balance information with fungible and non-fungible tokens
• FungibleBalances: Map of fungible token balances by address
• NonFungibleBalances: Map of NFT collections by address

Contributing

Contributions are welcome! This library is designed to be easily extensible. To add new utility functions:

1. Create new files in the appropriate directory (src/validators/, src/utils/, etc.)
2. Export your functions from the relevant index files
3. Add comprehensive TypeScript types in src/types/
4. Update the main src/index.ts to export your new functions
5. Add tests for your new functionality
6. Update this README with documentation

Development Setup

# Clone the repository
git clone <repository-url>
cd radix-utils

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

Project Structure

src/
├── types/          # TypeScript type definitions
├── validators/     # Validator-related utilities
├── utils/          # General utility functions
└── index.ts        # Main export file

Dependencies

• @radixdlt/babylon-gateway-api-sdk: Radix Gateway API SDK
• decimal.js: Arbitrary precision decimal calculations

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.

Changelog

1.2.0

• Added transaction event handling utilities
• Added getEventFromTransaction function for extracting specific events from transactions
• Added getEventKeyValuesFromTransaction function for simplified key-value extraction
• Added extractValuesFromTxEvent function for parsing event field data
• Added comprehensive test coverage for transaction functionality
• Updated documentation with transaction utility examples

1.1.0

• Added fetchWalletBalances function for comprehensive wallet balance fetching
• Added support for both fungible and non-fungible token balance retrieval
• Added automatic pagination support for large wallets
• Added new TypeScript types: WalletBalances, FungibleBalances, NonFungibleBalances
• Added comprehensive test coverage for wallet functionality
• Updated documentation with wallet balance examples

1.0.0

• Initial release
• Added fetchValidatorInfo function
• Added checkResourceInUsersFungibleAssets function
• Added computeValidatorFeeFactor function
• Added decimal and date utilities
• Full TypeScript support