@enclave-hq/chain-utils
Version:
Multi-chain utilities for Enclave - SLIP-44 mappings, universal address encoding, and chain conversions
315 lines (305 loc) • 9.1 kB
TypeScript
/**
* Chain type enumeration
*/
declare enum ChainType {
EVM = "evm",
TRON = "tron",
SOLANA = "solana",
COSMOS = "cosmos"
}
/**
* Chain information interface
*/
interface ChainInfo {
/** Native Chain ID (ID used in wallets) */
nativeChainId: number | string;
/** SLIP-44 Chain ID (used in Enclave system) */
slip44: number;
/** Chain name */
name: string;
/** Chain type */
chainType: ChainType;
/** Native token symbol */
symbol: string;
/** Whether it is a testnet */
isTestnet?: boolean;
}
/**
* Universal Address structure
*/
interface UniversalAddress {
/** SLIP-44 Chain ID (4 bytes) */
slip44: number;
/** Address (32 bytes, left-padded) */
address: Uint8Array;
/** Native Chain ID (optional, for reverse lookup) */
nativeChainId?: number | string;
/** Native address format (optional) */
nativeAddress?: string;
}
/**
* Universal Address serialization format (36 bytes)
* Format: SLIP-44 (4 bytes) + Address (32 bytes)
*/
type UniversalAddressBytes = Uint8Array;
/**
* Universal Address hex format
* Format: 0x + 72 hex characters (36 bytes)
*/
type UniversalAddressHex = `0x${string}`;
/**
* Address converter interface
*/
interface AddressConverter {
/**
* Convert native address to bytes (32 bytes, left-padded)
*/
toBytes(nativeAddress: string): Uint8Array;
/**
* Convert bytes back to native address
*/
fromBytes(bytes: Uint8Array): string;
/**
* Validate native address format
*/
isValid(nativeAddress: string): boolean;
}
/**
* SLIP-44 Chain ID mapping and conversion
*
* SLIP-44 Standard: https://github.com/satoshilabs/slips/blob/master/slip-0044.md
*/
/**
* Convert Native Chain ID to SLIP-44 ID
*
* @param nativeChainId - Native chain ID (e.g., 1, 56, 137 in MetaMask)
* @returns SLIP-44 ID, or null if not found
*
* @example
* nativeToSlip44(1) // => 60 (Ethereum)
* nativeToSlip44(56) // => 714 (BSC)
* nativeToSlip44(137) // => 966 (Polygon)
*/
declare function nativeToSlip44(nativeChainId: number | string): number | null;
/**
* Convert SLIP-44 ID to Native Chain ID
*
* @param slip44 - SLIP-44 Chain ID
* @returns Native Chain ID, or null if not found
*
* @example
* slip44ToNative(60) // => 1 (Ethereum)
* slip44ToNative(714) // => 56 (BSC)
* slip44ToNative(966) // => 137 (Polygon)
*/
declare function slip44ToNative(slip44: number): number | string | null;
/**
* Get chain information (by SLIP-44 ID)
*/
declare function getChainInfoBySlip44(slip44: number): ChainInfo | null;
/**
* Get chain information (by Native Chain ID)
*/
declare function getChainInfoByNative(nativeChainId: number | string): ChainInfo | null;
/**
* Get chain type (by SLIP-44 ID)
*/
declare function getChainType(slip44: number): ChainType | null;
/**
* Check if the chain is supported
*/
declare function isSupportedChain(nativeChainId: number | string): boolean;
/**
* Check if the SLIP-44 ID is supported
*/
declare function isSupportedSlip44(slip44: number): boolean;
/**
* Register a new chain (extensible API)
*
* @param chainInfo - Chain information
*
* @example
* registerChain({
* nativeChainId: 250,
* slip44: 60, // Fantom also uses Ethereum's SLIP-44
* name: 'Fantom Opera',
* chainType: ChainType.EVM,
* symbol: 'FTM',
* })
*/
declare function registerChain(chainInfo: ChainInfo): void;
/**
* Get all supported chains
*/
declare function getAllSupportedChains(): ChainInfo[];
/**
* Get all supported SLIP-44 IDs
*/
declare function getAllSupportedSlip44s(): number[];
/**
* Universal Address (36 bytes) conversion
*
* Format: SLIP-44 ChainID (4 bytes) + Address (32 bytes)
*/
/**
* Encode native address to Universal Address (36 bytes)
*
* @param slip44 - SLIP-44 Chain ID
* @param nativeAddress - Native address format (EVM: 0x..., Tron: T...)
* @returns 36 bytes Uint8Array
*
* @example
* encodeUniversalAddress(60, '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0')
* // => Uint8Array(36) [0,0,0,60, 0,0,0,0,0,0,0,0,0,0,0,0, 116,45,35,...]
*/
declare function encodeUniversalAddress(slip44: number, nativeAddress: string): UniversalAddressBytes;
/**
* Decode Universal Address to native address
*
* @param universalAddress - 36 bytes Uint8Array
* @returns { slip44, nativeAddress, nativeChainId }
*
* @example
* decodeUniversalAddress(bytes36)
* // => { slip44: 60, nativeAddress: '0x742d...', nativeChainId: 1 }
*/
declare function decodeUniversalAddress(universalAddress: UniversalAddressBytes): {
slip44: number;
nativeAddress: string;
nativeChainId: number | string | null;
};
/**
* Convert Universal Address bytes to hex string
*
* @param bytes - 36 bytes Uint8Array
* @returns 0x + 72 hex characters
*
* @example
* bytesToHex(new Uint8Array(36))
* // => '0x0000003c000000000000000000000000...'
*/
declare function bytesToHex(bytes: UniversalAddressBytes): UniversalAddressHex;
/**
* Convert hex string to Universal Address bytes
*
* @param hex - 0x + 72 hex characters
* @returns 36 bytes Uint8Array
*
* @example
* hexToBytes('0x0000003c000000000000000000000000...')
* // => Uint8Array(36)
*/
declare function hexToBytes(hex: UniversalAddressHex | string): UniversalAddressBytes;
/**
* Convenience function: Create Universal Address from Native Chain ID + Address
*
* @param nativeChainId - Native Chain ID
* @param nativeAddress - Native address
* @returns 36 bytes Uint8Array
*/
declare function createUniversalAddress(nativeChainId: number | string, nativeAddress: string): UniversalAddressBytes;
/**
* Convenience function: Create and return hex format Universal Address
*/
declare function createUniversalAddressHex(nativeChainId: number | string, nativeAddress: string): UniversalAddressHex;
/**
* Validate Universal Address format
*/
declare function isValidUniversalAddress(address: UniversalAddressBytes | UniversalAddressHex): boolean;
/**
* EVM address conversion
*/
/**
* EVM address converter
*
* EVM address format: 0x + 40 hex characters (20 bytes)
* Universal Address: 32 bytes (left-padded to 32 bytes)
*/
declare class EVMAddressConverter implements AddressConverter {
/**
* Convert EVM address to 32 bytes (left-padded)
*
* @param nativeAddress - EVM address (0x...)
* @returns 32 bytes Uint8Array
*
* @example
* toBytes('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0')
* // => Uint8Array(32) [0,0,0,0,0,0,0,0,0,0,0,0,116,45,53,204,...]
*/
toBytes(nativeAddress: string): Uint8Array;
/**
* Convert 32 bytes back to EVM address
*
* @param bytes - 32 bytes Uint8Array
* @returns EVM address (0x...)
*
* @example
* fromBytes(new Uint8Array(32))
* // => '0x742d35cc6634c0532925a3b844bc9e7595f0beb0'
*/
fromBytes(bytes: Uint8Array): string;
/**
* Validate EVM address format
*
* @param nativeAddress - EVM address
* @returns Whether it is valid
*/
isValid(nativeAddress: string): boolean;
/**
* Format EVM address (normalize to lowercase)
*/
format(nativeAddress: string): string;
}
declare const evmConverter: EVMAddressConverter;
/**
* Tron address conversion
*/
/**
* Tron address converter
*
* Tron address format: Base58 encoded (starts with T, 34 characters)
* Universal Address: First convert to hex (21 bytes), then left-pad to 32 bytes
*/
declare class TronAddressConverter implements AddressConverter {
private static readonly BASE58_ALPHABET;
/**
* Convert Tron address to 32 bytes (first to hex, then left-pad)
*
* @param nativeAddress - Tron address (T...)
* @returns 32 bytes Uint8Array
*
* @example
* toBytes('TRX9hash...')
* // => Uint8Array(32) [0,0,0,0,0,0,0,0,0,0,0,0,...]
*/
toBytes(nativeAddress: string): Uint8Array;
/**
* Convert 32 bytes back to Tron address
*
* @param bytes - 32 bytes Uint8Array
* @returns Tron address (T...)
*/
fromBytes(bytes: Uint8Array): string;
/**
* Validate Tron address format
*/
isValid(nativeAddress: string): boolean;
/**
* Base58 decode
*/
private base58Decode;
/**
* Base58 encode
*/
private base58Encode;
/**
* Calculate checksum (first 4 bytes of double SHA256)
*/
private calculateChecksum;
/**
* Compare two Uint8Arrays for equality
*/
private arraysEqual;
}
declare const tronConverter: TronAddressConverter;
export { type AddressConverter, type ChainInfo, ChainType, EVMAddressConverter, TronAddressConverter, type UniversalAddress, type UniversalAddressBytes, type UniversalAddressHex, bytesToHex, createUniversalAddress, createUniversalAddressHex, decodeUniversalAddress, encodeUniversalAddress, evmConverter, getAllSupportedChains, getAllSupportedSlip44s, getChainInfoByNative, getChainInfoBySlip44, getChainType, hexToBytes, isSupportedChain, isSupportedSlip44, isValidUniversalAddress, nativeToSlip44, registerChain, slip44ToNative, tronConverter };