index/classes/AddressFormatter.md

AddressFormatter - Unified address format operations

Provides consistent, well-documented address formatting and validation across all services that work with wallet addresses.

Supported Formats

• Ethereum: 0x1234567890abcdef... (40 hex chars with 0x prefix)
• Backend: eth|1234567890abcdef... (40 hex chars without 0x)
• Client: client|identifier (arbitrary client identifiers)

Usage Examples

Format conversion

const formatter = new AddressFormatter();

// Ethereum to backend
formatter.toBackendFormat('0x1234...abc');
// Returns: 'eth|1234...abc'

// Backend to Ethereum
formatter.toEthereumFormat('eth|1234...abc');
// Returns: '0x1234...abc'

// Auto-detect and convert
const format = formatter.normalizeInput('0x1234...abc');
// Returns: 'eth|1234...abc' (backend format)

Validation

const formatter = new AddressFormatter();

// Check validity (no throw)
if (formatter.isValid('0x1234...abc')) {
  // Process address
}

// Validate with throw
formatter.assertValid(address, 'userAddress');
// Safe to use

Since

6.5.0

Constructors

Constructor

new AddressFormatter(): AddressFormatter

Returns

AddressFormatter

Methods

assertValid()

assertValid(address, fieldName?): void

Validate address format, throwing on invalid

Parameters

Parameter	Type	Description
address	string | undefined	Address to validate
fieldName?	string	Field name for error messages (default: 'address')

Returns

void

Throws

ValidationError if address is invalid

Example

const formatter = new AddressFormatter();

formatter.assertValid(userAddress, 'userAddress');
// Safe to use userAddress

---

detectFormat()

detectFormat(address): AddressFormatType | null

Detect the format of an address string

Parameters

Parameter	Type	Description
address	string | undefined	Address string to check

Returns

AddressFormatType | null

Format type ('ethereum', 'backend', 'client') or null if invalid

Example

const formatter = new AddressFormatter();

formatter.detectFormat('0x1234...abc');     // 'ethereum'
formatter.detectFormat('eth|1234...abc');   // 'backend'
formatter.detectFormat('client|xyz');       // 'client'
formatter.detectFormat('invalid');          // null

---

extractHex()

extractHex(address): string

Extract hex address from either format

Returns just the 40-character hex portion without any prefix.

Parameters

Parameter	Type	Description
address	string	Ethereum or backend format address

Returns

string

40-character hex string (lowercase)

Throws

ValidationError if address format is invalid

Example

const formatter = new AddressFormatter();

formatter.extractHex('0x1234...abc');
// Returns: '1234...abc'

formatter.extractHex('eth|1234...abc');
// Returns: '1234...abc'

---

isValid()

isValid(address): address is string

Check if an address is valid (without throwing)

Returns true if address is in valid Ethereum or backend format.

Parameters

Parameter	Type	Description
address	string | null | undefined	Address to check

Returns

address is string

true if valid, false otherwise

Example

const formatter = new AddressFormatter();

if (formatter.isValid('0x1234...abc')) {
  // Process address
}

---

normalize()

normalize(address): string | undefined

Normalize address casing (lowercase for consistency)

Ethereum addresses can be checksummed, but we normalize to lowercase for consistency in comparisons and storage.

Parameters

Parameter	Type	Description
address	string | undefined	Address to normalize

Returns

string | undefined

Lowercase address

Example

const formatter = new AddressFormatter();

formatter.normalize('0xABCD...DCBA');
// Returns: '0xabcd...dcba'

formatter.normalize('ETH|ABCD...DCBA');
// Returns: 'eth|abcd...dcba'

---

normalizeForBackend()

normalizeForBackend(address): AddressFormat | undefined

The spelling the launchpad backend takes in its query parameters, paths and bodies: the backend's own canonical lower-case form (see backendUserRef).

Parameters

Parameter	Type	Description
address	string | undefined	Address in any form userRef takes

Returns

AddressFormat | undefined

eth|<40 lower-case hex> / client|<id>, or undefined for undefined or ''

Throws

ValidationError if address format is invalid

---

normalizeInput()

normalizeInput(address): AddressFormat | undefined

Smart address parser - accepts both Ethereum and backend formats

Automatically detects format and converts to backend format required by SDK. Handles both "0x..." and "eth|..." formats seamlessly.

Parameters

Parameter	Type	Description
address	string | undefined	Address in either Ethereum or backend format

Returns

AddressFormat | undefined

Backend format address (eth|...)

Throws

ValidationError if address format is invalid

Example

const formatter = new AddressFormatter();

// Ethereum format input
formatter.normalizeInput('0x1234...abc');
// Returns: 'eth|1234...abc'

// Backend format input
formatter.normalizeInput('eth|1234...abc');
// Returns: 'eth|1234...abc' (unchanged)

// Plain hex (with or without 0x)
formatter.normalizeInput('1234...abc');
// Returns: 'eth|1234...abc'

---

toBackendFormat()

toBackendFormat(address): string

Convert Ethereum address to backend format

Accepts Ethereum format (with or without 0x prefix) and returns backend format. Always returns EIP-55 checksummed addresses (required by GalaChain validators).

Parameters

Parameter	Type	Description
address	string	Ethereum address (0x... or plain 40 hex)

Returns

string

Backend format address (eth|...) with EIP-55 checksummed address

Throws

ValidationError if address format is invalid

Example

const formatter = new AddressFormatter();

formatter.toBackendFormat('0x1234567890abcdef1234567890abcdef12345678');
// Returns: 'eth|1234567890aBcdEf1234567890abCdef12345678' (checksummed)

formatter.toBackendFormat('1234567890abcdef1234567890abcdef12345678');
// Returns: 'eth|1234567890aBcdEf1234567890abCdef12345678' (checksummed)

---

toEthereumFormat()

toEthereumFormat(address): string

Convert backend address format to Ethereum format

Converts backend format (eth|...) to standard Ethereum format (0x...). Preserves the original case of the address portion (including EIP-55 checksummed addresses).

Parameters

Parameter	Type	Description
address	string	Backend format address (eth|...)

Returns

string

Ethereum format address (0x...)

Throws

ValidationError if address format is invalid

Example

const formatter = new AddressFormatter();

formatter.toEthereumFormat('eth|1234567890abcdef...abcdef');
// Returns: '0x1234567890abcdef...abcdef'

formatter.toEthereumFormat('eth|5aAeb6053f3E94C9b9A09f33669435E7Ef1BeAed');
// Returns: '0x5aAeb6053f3E94C9b9A09f33669435E7Ef1BeAed' (preserves checksum case)