@beclab/olaresid 0.1.1 → 0.1.3

package/src/business/index.ts

@@ -0,0 +1,1492 @@
+import { DIDConsole } from '..';
+import { ethers } from 'ethers';
+import { parseContractError } from '../utils/error-parser';
+import { TagContext } from './tag-context';
+import { TagTypeBuilder } from '../utils/tag-type-builder';
+import { normalizeToDomain } from '../utils/olares-id';
+
+export interface TransactionResult<T = any> {
+	// Basic transaction information
+	success: boolean;
+	transactionHash: string;
+	gasUsed?: bigint;
+	blockNumber?: number;
+
+	// Possible business data
+	data?: T;
+
+	error?: string;
+}
+
+export interface DomainMetaInfo {
+	id: string;
+	name: string;
+	did: string;
+	note: string;
+	allowSubdomain: boolean;
+}
+
+export interface DomainInfo {
+	meta: DomainMetaInfo;
+	owner: string;
+	tags: TagInfo[];
+	subdomains?: string[];
+}
+
+export interface TagInfo {
+	name: string;
+	type: string;
+	value: any;
+}
+
+// Re-export from crypto-utils
+export {
+	createRsaKeyPair,
+	generateMnemonic,
+	getEthereumAddressFromMnemonic,
+	getEVMPrivateKeyFromMnemonic,
+	getDIDFromMnemonic,
+	generateDIDKeyData,
+	deriveDIDFromMnemonic
+} from '../utils/crypto-utils';
+export type { RSAPublicKeyData, DIDKeyData } from '../utils/crypto-utils';
+
+// Re-export Tag-related classes
+export { TagContext } from './tag-context';
+export { TagTypeBuilder } from '../utils/tag-type-builder';
+
+/**
+ * Domain registration type
+ */
+export enum UserType {
+	IndividualOrganizationalUser = 'Individual:OrganizationalUser',
+	IndividualTerminusUser = 'Individual:TerminusUser',
+	Organization = 'Organization',
+	Entity = 'Entity'
+}
+
+export class DomainContext {
+	private domainName: string;
+	private console: DIDConsole;
+	private owner?: string;
+	private tokenId?: string;
+
+	constructor(domainName: string, console: DIDConsole) {
+		// Support Olares ID format (user@domain.com) by converting to standard domain format
+		this.domainName = normalizeToDomain(domainName);
+		this.console = console;
+	}
+
+	/**
+	 * Calculate the tokenId for the domain name
+	 * This is a pure function that hashes the domain name using keccak256
+	 * The result is cached after the first call
+	 * @returns The tokenId as a decimal string
+	 */
+	getTokenId(): string {
+		if (!this.tokenId) {
+			const hash = ethers.keccak256(ethers.toUtf8Bytes(this.domainName));
+			// Convert hex string to decimal string (BigInt format)
+			this.tokenId = BigInt(hash).toString();
+		}
+		return this.tokenId;
+	}
+
+	/**
+	 * Get only the basic information of the domain
+	 * Uses parallel RPC calls to get metadata and latest DID for optimal performance
+	 * TokenId is calculated locally using keccak256
+	 * @throws Error if domain is not registered or RPC call fails
+	 */
+	async getMetaInfo(): Promise<DomainMetaInfo> {
+		const didContract = this.console.getContractDID();
+		const resolverContract = this.console.getContractRootResolver();
+
+		// Calculate tokenId locally (no RPC call needed)
+		const tokenId = this.getTokenId();
+
+		// Parallel execution: Get metadata and latestDID simultaneously
+		const [metadata, latestDID] = await Promise.all([
+			didContract.getMetadata(tokenId),
+			// Use catch to handle cases where latestDID is not set
+			resolverContract.getLatestDID(this.domainName).catch(() => '')
+		]);
+
+		// Use latestDID if it has a value, otherwise fallback to metadata.did
+		const finalDid =
+			latestDID && latestDID.trim() !== '' ? latestDID : metadata.did;
+
+		return {
+			id: tokenId,
+			name: metadata.domain,
+			did: finalDid,
+			note: metadata.notes,
+			allowSubdomain: metadata.allowSubdomain
+		};
+	}
+
+	/**
+	 * Get the owner address of the domain
+	 * Uses cached value if available, otherwise fetches from chain
+	 * @throws Error if domain is not registered or RPC call fails
+	 */
+	async getOwner(): Promise<string> {
+		// Return cached owner if available
+		if (this.owner) {
+			return this.owner;
+		}
+
+		const contract = this.console.getContractDID();
+
+		// Calculate tokenId locally (no RPC call needed)
+		const tokenId = this.getTokenId();
+
+		// Single RPC call to get owner
+		const owner = await contract.ownerOf(tokenId);
+
+		// Cache the owner for later use
+		this.owner = owner;
+		return owner;
+	}
+
+	/**
+	 * Check if the connected signer is the owner of the domain
+	 * @throws Error if no signer is connected or RPC call fails
+	 */
+	async isOwner(): Promise<boolean> {
+		const signer = this.console.getSigner();
+		const signerAddress = await signer.getAddress();
+		const owner = await this.getOwner();
+
+		return signerAddress.toLowerCase() === owner.toLowerCase();
+	}
+
+	/**
+	 * Register a subdomain using mnemonic-derived keys
+	 *
+	 * @param subdomain Subdomain label only (e.g., "child" for "child.parent.com")
+	 * @param mnemonic BIP39 mnemonic phrase (12 words by default) to derive owner and DID
+	 * @returns Transaction result with success status and transaction hash
+	 * @throws Error if no signer is connected, parent domain doesn't exist, or transaction fails
+	 *
+	 * The subdomain's metadata:
+	 * - owner: derived from mnemonic using Trust Wallet Core (same as TermiPass)
+	 * - DID: derived from mnemonic using Ed25519 (same as TermiPass)
+	 * - note: inherits from parent domain
+	 * - allowSubdomain: inherits from parent domain
+	 *
+	 * @example
+	 * ```typescript
+	 * // For parent domain "parent.com", register subdomain "child"
+	 * const parentDomain = olaresId.domain('parent.com');
+	 * const mnemonic = generateMnemonic(12);
+	 *
+	 * const result = await parentDomain.registerSubdomain('child', mnemonic);
+	 * // This will register "child.parent.com"
+	 *
+	 * if (result.success) {
+	 *   console.log('Full domain:', result.data.fullDomainName); // "child.parent.com"
+	 *   console.log('Owner:', result.data.owner);
+	 *   console.log('DID:', result.data.did);
+	 * }
+	 * ```
+	 */
+	async registerSubdomain(
+		subdomain: string,
+		mnemonic: string
+	): Promise<TransactionResult> {
+		try {
+			// 1. Get parent domain metadata to inherit note and allowSubdomain
+			const parentMetadata = await this.getMetaInfo();
+
+			// 2. Construct full domain name: subdomain.parentDomain
+			const fullDomainName = `${subdomain}.${parentMetadata.name}`;
+
+			// 3. Derive owner and DID from mnemonic using Trust Wallet Core
+			const { deriveDIDFromMnemonic } = await import(
+				'../utils/crypto-utils'
+			);
+			const { owner, did } = await deriveDIDFromMnemonic(mnemonic);
+
+			// 4. Prepare metadata for subdomain (inherit from parent)
+			const subdomainNote = parentMetadata.note as UserType;
+			const subdomainAllowSubdomain = parentMetadata.allowSubdomain;
+
+			// 5. Call register function on the contract
+			const contract = this.console.getSignerContractDID();
+
+			const metadata = {
+				domain: fullDomainName,
+				did: did,
+				notes: subdomainNote,
+				allowSubdomain: subdomainAllowSubdomain
+			};
+
+			const tx = await contract.register(owner, metadata);
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber,
+				data: {
+					owner,
+					did,
+					subdomain,
+					fullDomainName
+				}
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Transfer domain ownership to a new owner derived from mnemonic
+	 *
+	 * @param mnemonic BIP39 mnemonic phrase to derive new owner and DID
+	 * @returns Transaction result with success status
+	 *
+	 * This function performs two operations:
+	 * 1. Transfer NFT ownership via DID contract's transferFrom
+	 * 2. Update DID via RootResolver's setLatestDID
+	 *
+	 * @example
+	 * ```typescript
+	 * const mnemonic = generateMnemonic(12);
+	 * const result = await domain.transfer(mnemonic);
+	 * if (result.success) {
+	 *   console.log('Domain transferred!');
+	 *   console.log('New Owner:', result.data.newOwner);
+	 *   console.log('New DID:', result.data.newDid);
+	 * }
+	 * ```
+	 */
+	async transfer(mnemonic: string): Promise<TransactionResult> {
+		try {
+			// 1. Get current domain info
+			const currentOwner = await this.getOwner();
+			const tokenId = this.getTokenId();
+
+			// 2. Derive new owner and DID from mnemonic
+			const { deriveDIDFromMnemonic } = await import(
+				'../utils/crypto-utils'
+			);
+			const { owner: newOwner, did: newDid } =
+				await deriveDIDFromMnemonic(mnemonic);
+
+			// 3. Update DID FIRST (while current owner still has permission)
+			// This must be done before transferFrom, because after transfer,
+			// the current owner will lose permission to call setLatestDID
+			const resolverContract =
+				this.console.getSignerContractRootResolver();
+			const setDidTx = await resolverContract.setLatestDID(
+				this.domainName,
+				newDid
+			);
+			const setDidReceipt = await setDidTx.wait();
+
+			// 4. Transfer NFT ownership (DID contract)
+			// After this, the new owner will have control
+			const didContract = this.console.getSignerContractDID();
+			const transferTx = await didContract.transferFrom(
+				currentOwner,
+				newOwner,
+				tokenId
+			);
+			const transferReceipt = await transferTx.wait();
+
+			// Calculate total gas used
+			const totalGasUsed =
+				setDidReceipt.gasUsed + transferReceipt.gasUsed;
+
+			return {
+				success: true,
+				transactionHash: transferReceipt.hash,
+				gasUsed: totalGasUsed,
+				blockNumber: transferReceipt.blockNumber,
+				data: {
+					newOwner,
+					newDid,
+					tokenId,
+					setDidTxHash: setDidReceipt.hash,
+					transferTxHash: transferReceipt.hash
+				}
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Set the RSA public key for your own domain
+	 * Users can use the helper function createRsaKeyPair to generate a new RSA key pair
+	 * The pubKey parameter should be in RSA PKCS8 ASN.1 format
+	 * @param rsaPublicKey - The RSA public key in PEM format or DER hex format (with or without '0x' prefix)
+	 * @throws Error if no signer is connected or transaction fails
+	 */
+	async setRSAPublicKey(rsaPublicKey: string): Promise<TransactionResult> {
+		const contract = this.console.getSignerContractRootResolver();
+
+		try {
+			let pubKeyBytes: string;
+
+			// Check if input is PEM format (contains BEGIN/END markers)
+			if (rsaPublicKey.includes('BEGIN')) {
+				// Convert PEM to DER hex format
+				pubKeyBytes = pemToDer(rsaPublicKey);
+			} else {
+				// Assume it's already in hex format, ensure it has '0x' prefix
+				pubKeyBytes = rsaPublicKey.startsWith('0x')
+					? rsaPublicKey
+					: '0x' + rsaPublicKey;
+			}
+
+			const tx = await contract.setRsaPubKey(
+				this.domainName,
+				pubKeyBytes
+			);
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Remove the RSA public key for your own domain
+	 * This is done by calling setRsaPubKey with empty bytes
+	 * @throws Error if no signer is connected or transaction fails
+	 */
+	async removeRSAPublicKey(): Promise<TransactionResult> {
+		const contract = this.console.getSignerContractRootResolver();
+
+		try {
+			// Pass empty bytes to remove the RSA public key
+			const tx = await contract.setRsaPubKey(this.domainName, '0x');
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Get the RSA public key for the domain
+	 * @returns The RSA public key in PEM PKCS#8 format, or null if not set
+	 * @throws Error if network error or unexpected contract error occurs
+	 */
+	async getRSAPublicKey(): Promise<string | null> {
+		const contract = this.console.getContractRootResolver();
+
+		try {
+			const pubKey = await contract.getRsaPubKey(this.domainName);
+			// If pubKey is empty bytes, return null
+			if (pubKey === '0x' || pubKey.length === 2) {
+				return null;
+			}
+			// Convert DER hex format to PEM PKCS#8 format
+			return derToPem(pubKey);
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			// If tag doesn't exist, return null (this is expected)
+			if (
+				parsedError.errorName === 'RootTagNoExists' ||
+				parsedError.errorName === 'TagNotExist'
+			) {
+				return null;
+			}
+
+			// For other contract errors, throw with friendly message
+			throw new Error(parsedError.message);
+		}
+	}
+
+	/**
+	 * Set the DNS A record for your own domain, currently the contract only supports IPv4 address format
+	 * The parameter is an IPv4 address, in xxx.xxx.xxx.xxx format
+	 * @param aRecord - IPv4 address string (e.g., "192.168.1.1")
+	 * @throws Error if no signer is connected or transaction fails
+	 */
+	async setIP(aRecord: string): Promise<TransactionResult> {
+		const contract = this.console.getSignerContractRootResolver();
+
+		try {
+			// Convert IPv4 string to bytes4 format
+			const ipv4Bytes = ipv4ToBytes4(aRecord);
+
+			const tx = await contract.setDnsARecord(this.domainName, ipv4Bytes);
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Remove the DNS A record for your own domain
+	 * This is done by calling setDnsARecord with bytes4(0)
+	 * @throws Error if no signer is connected or transaction fails
+	 */
+	async removeIP(): Promise<TransactionResult> {
+		const contract = this.console.getSignerContractRootResolver();
+
+		try {
+			// Pass bytes4(0) to remove the DNS A record
+			const tx = await contract.setDnsARecord(
+				this.domainName,
+				'0x00000000'
+			);
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber
+			};
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: parsedError.message
+			};
+		}
+	}
+
+	/**
+	 * Get the DNS A record for your own domain
+	 * @returns The IPv4 address as a string (e.g., "192.168.1.1"), or null if not set
+	 * @throws Error if network error or unexpected contract error occurs
+	 */
+	async getIP(): Promise<string | null> {
+		const contract = this.console.getContractRootResolver();
+
+		try {
+			const ipv4Bytes = await contract.getDnsARecord(this.domainName);
+			// If ipv4Bytes is 0x00000000, return null
+			if (ipv4Bytes === '0x00000000') {
+				return null;
+			}
+			// Convert bytes4 to IPv4 string
+			return bytes4ToIpv4(ipv4Bytes);
+		} catch (error: any) {
+			const parsedError = parseContractError(error);
+
+			// Always throw network errors
+			if (parsedError.isNetworkError) {
+				throw new Error(`Network error: ${parsedError.message}`);
+			}
+
+			// If tag doesn't exist, return null (this is expected)
+			if (
+				parsedError.errorName === 'RootTagNoExists' ||
+				parsedError.errorName === 'TagNotExist'
+			) {
+				return null;
+			}
+
+			// For other contract errors, throw with friendly message
+			throw new Error(parsedError.message);
+		}
+	}
+
+	/**
+	 * Add EVM wallet address to the domain's authenticated address tag
+	 * @param evmPrivateKey - EVM private key (hex string with 0x prefix)
+	 * @returns Transaction result with success status and transaction hash
+	 */
+	async addEVMWallet(evmPrivateKey: string): Promise<TransactionResult> {
+		try {
+			// Get wallet address from private key
+			const wallet = new ethers.Wallet(evmPrivateKey);
+			const evmAddress = wallet.address;
+
+			// Get current timestamp
+			const signAt = Math.floor(Date.now() / 1000) - 30 * 60; // 30 minutes ago
+
+			// Prepare the request value
+			const value = {
+				addr: evmAddress,
+				domain: this.domainName,
+				signAt: signAt,
+				action: 0 // Action.Add
+			};
+
+			// Get domain owner's signer
+			const domainOwner = this.console.getSigner();
+			if (!domainOwner) {
+				throw new Error(
+					'Signer not set. Please call setSigner() first.'
+				);
+			}
+
+			// Get RootTagger2 contract
+			const rootTagger = this.console.getSignerContractRootResolver2();
+			const chainId = (await domainOwner.provider?.getNetwork())?.chainId;
+
+			// Define EIP-712 domain
+			const domain = {
+				name: 'Terminus DID Root Tagger',
+				version: '1',
+				chainId: chainId,
+				verifyingContract: await rootTagger.getAddress()
+			};
+
+			// Define EIP-712 types
+			const types = {
+				EVMAuthAddressReq: [
+					{ name: 'addr', type: 'address' },
+					{ name: 'domain', type: 'string' },
+					{ name: 'signAt', type: 'uint256' },
+					{ name: 'action', type: 'uint8' }
+				]
+			};
+
+			// Sign by domain owner
+			const sigFromDomainOwner = await domainOwner.signTypedData(
+				domain,
+				types,
+				value
+			);
+
+			// Sign by the EVM wallet
+			const sigFromAuthAddr = await wallet.signTypedData(
+				domain,
+				types,
+				value
+			);
+
+			// Call contract
+			const tx = await rootTagger.updateEVMWallet(
+				value,
+				sigFromDomainOwner,
+				sigFromAuthAddr
+			);
+
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber,
+				data: { address: evmAddress }
+			};
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Always throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(`Network error: ${errorInfo.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: errorInfo.message
+			};
+		}
+	}
+
+	/**
+	 * Remove EVM wallet address from the domain's authenticated address tag
+	 * @param evmPrivateKey - EVM private key (hex string with 0x prefix)
+	 * @returns Transaction result with success status and transaction hash
+	 */
+	async removeEVMWallet(evmPrivateKey: string): Promise<TransactionResult> {
+		try {
+			// Get wallet address from private key
+			const wallet = new ethers.Wallet(evmPrivateKey);
+			const evmAddress = wallet.address;
+
+			// Get current timestamp
+			const signAt = Math.floor(Date.now() / 1000) - 30 * 60; // 30 minutes ago
+
+			// Prepare the request value
+			const value = {
+				addr: evmAddress,
+				domain: this.domainName,
+				signAt: signAt,
+				action: 1 // Action.Remove
+			};
+
+			// Get domain owner's signer
+			const domainOwner = this.console.getSigner();
+			if (!domainOwner) {
+				throw new Error(
+					'Signer not set. Please call setSigner() first.'
+				);
+			}
+
+			// Get RootTagger2 contract
+			const rootTagger = this.console.getSignerContractRootResolver2();
+			const chainId = (await domainOwner.provider?.getNetwork())?.chainId;
+
+			// Define EIP-712 domain
+			const domain = {
+				name: 'Terminus DID Root Tagger',
+				version: '1',
+				chainId: chainId,
+				verifyingContract: await rootTagger.getAddress()
+			};
+
+			// Define EIP-712 types
+			const types = {
+				EVMAuthAddressReq: [
+					{ name: 'addr', type: 'address' },
+					{ name: 'domain', type: 'string' },
+					{ name: 'signAt', type: 'uint256' },
+					{ name: 'action', type: 'uint8' }
+				]
+			};
+
+			// Sign by domain owner
+			const sigFromDomainOwner = await domainOwner.signTypedData(
+				domain,
+				types,
+				value
+			);
+
+			// For remove action, signature from address is not required (pass empty bytes)
+			const sigFromAuthAddr = '0x';
+
+			// Call contract
+			const tx = await rootTagger.updateEVMWallet(
+				value,
+				sigFromDomainOwner,
+				sigFromAuthAddr
+			);
+
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber,
+				data: { address: evmAddress }
+			};
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Always throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(`Network error: ${errorInfo.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: errorInfo.message
+			};
+		}
+	}
+
+	/**
+	 * Get all EVM wallet addresses for the domain
+	 * Combines addresses from both RootTagger2 (new) and RootResolver (legacy) for backward compatibility
+	 * @returns Array of unique EVM wallet addresses
+	 */
+	async getEVMWallets(): Promise<string[]> {
+		const addresses: string[] = [];
+
+		// Get addresses from RootTagger2 (new method)
+		try {
+			const rootTagger2 = this.console.getContractRootResolver2();
+			const result = await rootTagger2.getEVMWallets(this.domainName);
+
+			// Extract addresses from the result
+			// Result is array of { algorithm, addr }
+			const tagger2Addresses = result.map((item: any) =>
+				item.addr.toLowerCase()
+			);
+			addresses.push(...tagger2Addresses);
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Only skip if it's a contract error (tag doesn't exist, etc.)
+			// Re-throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(
+					`Network error fetching from RootTagger2: ${errorInfo.message}`
+				);
+			}
+			// Contract errors are silently handled (tag doesn't exist is normal)
+		}
+
+		// Get addresses from RootResolver (legacy method for backward compatibility)
+		try {
+			const rootResolver = this.console.getContractRootResolver();
+			const result = await rootResolver.getAuthenticationAddresses(
+				this.domainName
+			);
+
+			// Extract addresses from the result
+			// Result is array of { algorithm, addr }
+			const legacyAddresses = result.map((item: any) =>
+				item.addr.toLowerCase()
+			);
+			addresses.push(...legacyAddresses);
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Only skip if it's a contract error
+			// Re-throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(
+					`Network error fetching from RootResolver (legacy): ${errorInfo.message}`
+				);
+			}
+			// Contract errors are silently handled
+		}
+
+		// Remove duplicates and return
+		return [...new Set(addresses)];
+	}
+
+	/**
+	 * Add Solana wallet address to the domain's authenticated address tag
+	 * @param solanaPrivateKey - Solana private key (base64 or base58 encoded string)
+	 * @returns Transaction result with success status and transaction hash
+	 */
+	async addSolanaWallet(
+		solanaPrivateKey: string
+	): Promise<TransactionResult> {
+		try {
+			// Import Solana libraries dynamically
+			const { Keypair } = await import('@solana/web3.js');
+			const nacl = await import('tweetnacl');
+			const { decodeUTF8 } = await import('tweetnacl-util');
+
+			// Parse Solana private key (support both base58 and base64)
+			let solanaWallet: any;
+			try {
+				// Try base58 first (most common format for Phantom)
+				const bs58 = await import('bs58');
+				const secretKey = bs58.default.decode(solanaPrivateKey);
+				solanaWallet = Keypair.fromSecretKey(secretKey);
+			} catch {
+				// Try base64
+				try {
+					const secretKey = Buffer.from(solanaPrivateKey, 'base64');
+					solanaWallet = Keypair.fromSecretKey(secretKey);
+				} catch {
+					// Try as JSON array
+					const secretKey = JSON.parse(solanaPrivateKey);
+					solanaWallet = Keypair.fromSecretKey(
+						Uint8Array.from(secretKey)
+					);
+				}
+			}
+
+			// Get Solana address as bytes32
+			const solanaAddressBytes =
+				'0x' + solanaWallet.publicKey.toBuffer().toString('hex');
+
+			// Get current timestamp
+			const signAt = Math.floor(Date.now() / 1000) - 30 * 60; // 30 minutes ago
+
+			// Prepare the request value
+			const value = {
+				addr: solanaAddressBytes,
+				domain: this.domainName,
+				signAt: signAt,
+				action: 0 // Action.Add
+			};
+
+			// Get domain owner's signer
+			const domainOwner = this.console.getSigner();
+			if (!domainOwner) {
+				throw new Error(
+					'Signer not set. Please call setSigner() first.'
+				);
+			}
+
+			// Get RootTagger2 contract
+			const rootTagger = this.console.getSignerContractRootResolver2();
+			const chainId = (await domainOwner.provider?.getNetwork())?.chainId;
+
+			// Define EIP-712 domain
+			const domain = {
+				name: 'Terminus DID Root Tagger',
+				version: '1',
+				chainId: chainId,
+				verifyingContract: await rootTagger.getAddress()
+			};
+
+			// Define EIP-712 types for Solana
+			const types = {
+				SolanaAuthAddressReq: [
+					{ name: 'addr', type: 'bytes32' },
+					{ name: 'domain', type: 'string' },
+					{ name: 'signAt', type: 'uint256' },
+					{ name: 'action', type: 'uint8' }
+				]
+			};
+
+			// Sign by domain owner
+			const sigFromDomainOwner = await domainOwner.signTypedData(
+				domain,
+				types,
+				value
+			);
+
+			// Sign by the Solana wallet (different signature method)
+			const solanaMsg =
+				'prove ownership of Solana wallet ' +
+				solanaWallet.publicKey.toBase58() +
+				' for Terminus DID ' +
+				this.domainName;
+			const sigFromAuthAddr = nacl.default.sign.detached(
+				decodeUTF8(solanaMsg),
+				solanaWallet.secretKey
+			);
+			const sigFromAuthAddrHex =
+				'0x' + Buffer.from(sigFromAuthAddr).toString('hex');
+
+			// Call contract
+			const tx = await rootTagger.updateSolanaWallet(
+				value,
+				sigFromDomainOwner,
+				sigFromAuthAddrHex
+			);
+
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber,
+				data: {
+					address: solanaWallet.publicKey.toBase58(),
+					addressHex: solanaAddressBytes
+				}
+			};
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Always throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(`Network error: ${errorInfo.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: errorInfo.message
+			};
+		}
+	}
+
+	/**
+	 * Remove Solana wallet address from the domain's authenticated address tag
+	 * @param solanaPrivateKey - Solana private key (base64 or base58 encoded string)
+	 * @returns Transaction result with success status and transaction hash
+	 */
+	async removeSolanaWallet(
+		solanaPrivateKey: string
+	): Promise<TransactionResult> {
+		try {
+			// Import Solana libraries dynamically
+			const { Keypair } = await import('@solana/web3.js');
+
+			// Parse Solana private key
+			let solanaWallet: any;
+			try {
+				// Try base58 first
+				const bs58 = await import('bs58');
+				const secretKey = bs58.default.decode(solanaPrivateKey);
+				solanaWallet = Keypair.fromSecretKey(secretKey);
+			} catch {
+				// Try base64
+				try {
+					const secretKey = Buffer.from(solanaPrivateKey, 'base64');
+					solanaWallet = Keypair.fromSecretKey(secretKey);
+				} catch {
+					// Try as JSON array
+					const secretKey = JSON.parse(solanaPrivateKey);
+					solanaWallet = Keypair.fromSecretKey(
+						Uint8Array.from(secretKey)
+					);
+				}
+			}
+
+			// Get Solana address as bytes32
+			const solanaAddressBytes =
+				'0x' + solanaWallet.publicKey.toBuffer().toString('hex');
+
+			// Get current timestamp
+			const signAt = Math.floor(Date.now() / 1000) - 30 * 60; // 30 minutes ago
+
+			// Prepare the request value
+			const value = {
+				addr: solanaAddressBytes,
+				domain: this.domainName,
+				signAt: signAt,
+				action: 1 // Action.Remove
+			};
+
+			// Get domain owner's signer
+			const domainOwner = this.console.getSigner();
+			if (!domainOwner) {
+				throw new Error(
+					'Signer not set. Please call setSigner() first.'
+				);
+			}
+
+			// Get RootTagger2 contract
+			const rootTagger = this.console.getSignerContractRootResolver2();
+			const chainId = (await domainOwner.provider?.getNetwork())?.chainId;
+
+			// Define EIP-712 domain
+			const domain = {
+				name: 'Terminus DID Root Tagger',
+				version: '1',
+				chainId: chainId,
+				verifyingContract: await rootTagger.getAddress()
+			};
+
+			// Define EIP-712 types for Solana
+			const types = {
+				SolanaAuthAddressReq: [
+					{ name: 'addr', type: 'bytes32' },
+					{ name: 'domain', type: 'string' },
+					{ name: 'signAt', type: 'uint256' },
+					{ name: 'action', type: 'uint8' }
+				]
+			};
+
+			// Sign by domain owner
+			const sigFromDomainOwner = await domainOwner.signTypedData(
+				domain,
+				types,
+				value
+			);
+
+			// For remove action, signature from address is not required (pass empty bytes)
+			const sigFromAuthAddr = '0x';
+
+			// Call contract
+			const tx = await rootTagger.updateSolanaWallet(
+				value,
+				sigFromDomainOwner,
+				sigFromAuthAddr
+			);
+
+			const receipt = await tx.wait();
+
+			return {
+				success: true,
+				transactionHash: receipt.hash,
+				gasUsed: receipt.gasUsed,
+				blockNumber: receipt.blockNumber,
+				data: {
+					address: solanaWallet.publicKey.toBase58(),
+					addressHex: solanaAddressBytes
+				}
+			};
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Always throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(`Network error: ${errorInfo.message}`);
+			}
+
+			return {
+				success: false,
+				transactionHash: '',
+				error: errorInfo.message
+			};
+		}
+	}
+
+	/**
+	 * Get all Solana wallet addresses for the domain
+	 * @returns Array of Solana wallet addresses (in base58 format)
+	 */
+	async getSolanaWallets(): Promise<string[]> {
+		try {
+			const { PublicKey } = await import('@solana/web3.js');
+			const rootTagger = this.console.getContractRootResolver2();
+			const result = await rootTagger.getSolanaWallets(this.domainName);
+
+			// Extract addresses from the result and convert to base58
+			// Result is array of { algorithm, addr } where addr is bytes32
+			return result.map((item: any) => {
+				// Remove 0x prefix and convert hex to buffer
+				const hexStr = item.addr.startsWith('0x')
+					? item.addr.slice(2)
+					: item.addr;
+				const buffer = Buffer.from(hexStr, 'hex');
+				// Convert to Solana public key and then to base58
+				return new PublicKey(buffer).toBase58();
+			});
+		} catch (error: any) {
+			const errorInfo = parseContractError(error);
+
+			// Only skip if it's a contract error (tag doesn't exist is normal)
+			// Re-throw network errors
+			if (errorInfo.isNetworkError) {
+				throw new Error(
+					`Network error fetching Solana wallets: ${errorInfo.message}`
+				);
+			}
+
+			// For contract errors, return empty array (tag doesn't exist is normal)
+			return [];
+		}
+	}
+
+	// ========================================
+	// Tag Management
+	// ========================================
+
+	/**
+	 * Create a Tag context for advanced Tag operations
+	 * @param fromDomain The domain that defines the Tag (defaults to current domain)
+	 * @returns TagContext instance
+	 *
+	 * @example
+	 * // Use current domain as the Tag definer
+	 * const tagCtx = domain.tag();
+	 *
+	 * // Use a specific domain as the Tag definer (cross-domain operations)
+	 * const tagCtx = domain.tag('parent.com');
+	 */
+	tag(fromDomain: string = this.domainName): TagContext {
+		return new TagContext(this.console, fromDomain);
+	}
+
+	// ========================================
+	// Simplified Tag Operations (High-Level API)
+	// ========================================
+
+	/**
+	 * Set the tagger (manager) for a Tag
+	 * Only the domain owner can set the tagger
+	 *
+	 * @param tagName Tag name
+	 * @param taggerAddress Address of the tagger (manager)
+	 * @returns Transaction result
+	 *
+	 * @example
+	 * // Set a specific address as the tagger
+	 * await domain.setTagger('email', '0x1234...');
+	 *
+	 * // Set zero address to allow anyone to manage
+	 * await domain.setTagger('email', '0x0000000000000000000000000000000000000000');
+	 */
+	async setTagger(
+		tagName: string,
+		taggerAddress: string
+	): Promise<TransactionResult> {
+		return await this.tag().setTagger(tagName, taggerAddress);
+	}
+
+	/**
+	 * Get the tagger (manager) address for a Tag
+	 *
+	 * @param tagName Tag name
+	 * @returns Tagger address (returns zero address if no tagger is set)
+	 *
+	 * @example
+	 * const tagger = await domain.getTagger('email');
+	 * console.log('Tagger address:', tagger);
+	 */
+	async getTagger(tagName: string): Promise<string> {
+		return await this.tag().getTagger(tagName);
+	}
+
+	/**
+	 * Define a simple Tag type
+	 * Only supports common simple types; use tag() for complex types
+	 *
+	 * @param tagName Tag name
+	 * @param type Supported simple type
+	 * @returns Transaction result
+	 *
+	 * @example
+	 * await domain.defineSimpleTag('email', 'string');
+	 * await domain.defineSimpleTag('age', 'uint8');
+	 * await domain.defineSimpleTag('verified', 'bool');
+	 * await domain.defineSimpleTag('wallets', 'address[]');
+	 */
+	async defineSimpleTag(
+		tagName: string,
+		type:
+			| 'string'
+			| 'address'
+			| 'bool'
+			| 'uint8'
+			| 'uint16'
+			| 'uint32'
+			| 'uint64'
+			| 'uint128'
+			| 'uint256'
+			| 'int8'
+			| 'int16'
+			| 'int32'
+			| 'int64'
+			| 'int128'
+			| 'int256'
+			| 'bytes'
+			| 'bytes32'
+			| 'string[]'
+			| 'address[]'
+			| 'uint256[]'
+	): Promise<TransactionResult> {
+		const tagCtx = this.tag();
+
+		// Type mapping
+		let tagType;
+		switch (type) {
+			case 'string':
+				tagType = TagTypeBuilder.string();
+				break;
+			case 'address':
+				tagType = TagTypeBuilder.address();
+				break;
+			case 'bool':
+				tagType = TagTypeBuilder.bool();
+				break;
+			case 'uint8':
+				tagType = TagTypeBuilder.uint8();
+				break;
+			case 'uint16':
+				tagType = TagTypeBuilder.uint16();
+				break;
+			case 'uint32':
+				tagType = TagTypeBuilder.uint32();
+				break;
+			case 'uint64':
+				tagType = TagTypeBuilder.uint64();
+				break;
+			case 'uint128':
+				tagType = TagTypeBuilder.uint128();
+				break;
+			case 'uint256':
+				tagType = TagTypeBuilder.uint256();
+				break;
+			case 'int8':
+				tagType = TagTypeBuilder.int8();
+				break;
+			case 'int16':
+				tagType = TagTypeBuilder.int16();
+				break;
+			case 'int32':
+				tagType = TagTypeBuilder.int32();
+				break;
+			case 'int64':
+				tagType = TagTypeBuilder.int64();
+				break;
+			case 'int128':
+				tagType = TagTypeBuilder.int128();
+				break;
+			case 'int256':
+				tagType = TagTypeBuilder.int256();
+				break;
+			case 'bytes':
+				tagType = TagTypeBuilder.bytes();
+				break;
+			case 'bytes32':
+				tagType = TagTypeBuilder.bytes32();
+				break;
+			case 'string[]':
+				tagType = TagTypeBuilder.stringArray();
+				break;
+			case 'address[]':
+				tagType = TagTypeBuilder.addressArray();
+				break;
+			case 'uint256[]':
+				tagType = TagTypeBuilder.uint256Array();
+				break;
+			default:
+				throw new Error(
+					`Unsupported simple type: ${type}. Use tag() for complex types.`
+				);
+		}
+
+		return await tagCtx.defineTag(tagName, tagType);
+	}
+
+	/**
+	 * Set a Tag value for the current domain
+	 * from = current domain, to = current domain
+	 *
+	 * @param tagName Tag name
+	 * @param value Tag value
+	 * @returns Transaction result
+	 *
+	 * @example
+	 * await domain.setTag('email', 'user@example.com');
+	 * await domain.setTag('links', ['https://...', 'https://...']);
+	 */
+	async setTag(tagName: string, value: any): Promise<TransactionResult> {
+		return await this.tag().setTag(this.domainName, tagName, value);
+	}
+
+	/**
+	 * Get a Tag value for the current domain
+	 * from = current domain, to = current domain
+	 *
+	 * @param tagName Tag name
+	 * @returns Tag value, or null if not found
+	 */
+	async getTag(tagName: string): Promise<any | null> {
+		return await this.tag().getTag(this.domainName, tagName);
+	}
+
+	/**
+	 * Remove a Tag from the current domain
+	 * from = current domain, to = current domain
+	 *
+	 * @param tagName Tag name
+	 * @returns Transaction result
+	 */
+	async removeTag(tagName: string): Promise<TransactionResult> {
+		return await this.tag().removeTag(this.domainName, tagName);
+	}
+
+	/**
+	 * Get all Tags for the current domain
+	 * @returns Array of Tags with name and value
+	 */
+	async getAllTags(): Promise<Array<{ name: string; value: any }>> {
+		return await this.tag().getAllTags(this.domainName);
+	}
+
+	/**
+	 * Get all Tag type names defined by the current domain
+	 * @returns Array of Tag names
+	 */
+	async getDefinedTags(): Promise<string[]> {
+		return await this.tag().getDefinedTagNames();
+	}
+}
+
+/*
+ * Helper function to convert IPv4 string to bytes4 format
+ * @param ipv4 - IPv4 address string (e.g., "192.168.1.1")
+ * @returns bytes4 format as hex string with '0x' prefix
+ */
+export function ipv4ToBytes4(ipv4: string): string {
+	// Validate IPv4 format
+	const ipv4Regex = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+	const match = ipv4.match(ipv4Regex);
+
+	if (!match) {
+		throw new Error('Invalid IPv4 address format');
+	}
+
+	// Parse and validate each octet (0-255)
+	const octets = match.slice(1, 5).map((octet) => {
+		const num = parseInt(octet, 10);
+		if (num < 0 || num > 255) {
+			throw new Error(
+				`Invalid IPv4 octet: ${octet}. Must be between 0 and 255`
+			);
+		}
+		return num;
+	});
+
+	// Convert to hex bytes4 format
+	const hexString = octets
+		.map((octet) => octet.toString(16).padStart(2, '0'))
+		.join('');
+
+	return '0x' + hexString;
+}
+
+/*
+ * Helper function to convert bytes4 format to IPv4 string
+ * @param bytes4Hex - bytes4 format as hex string (with or without '0x' prefix)
+ * @returns IPv4 address string (e.g., "192.168.1.1")
+ */
+export function bytes4ToIpv4(bytes4Hex: string): string {
+	// Remove '0x' prefix if present
+	const hexString = bytes4Hex.startsWith('0x')
+		? bytes4Hex.slice(2)
+		: bytes4Hex;
+
+	// Validate hex string length (should be 8 characters for 4 bytes)
+	if (hexString.length !== 8) {
+		throw new Error(
+			`Invalid bytes4 format: expected 8 hex characters, got ${hexString.length}`
+		);
+	}
+
+	// Convert each pair of hex characters to decimal
+	const octets = [];
+	for (let i = 0; i < 8; i += 2) {
+		const octet = parseInt(hexString.slice(i, i + 2), 16);
+		octets.push(octet);
+	}
+
+	return octets.join('.');
+}
+
+/*
+ * Helper function to convert PEM format to DER hex format
+ * @param pem - PEM formatted string (with BEGIN/END markers)
+ * @returns DER format as hex string with '0x' prefix
+ */
+export function pemToDer(pem: string): string {
+	// Remove PEM headers, footers, and whitespace
+	const base64 = pem
+		.replace(/-----BEGIN.*?-----/g, '')
+		.replace(/-----END.*?-----/g, '')
+		.replace(/\s/g, '');
+
+	// Convert base64 to hex
+	let hexString: string;
+
+	// Check if running in Node.js or browser
+	if (typeof Buffer !== 'undefined') {
+		// Node.js environment
+		const derBuffer = Buffer.from(base64, 'base64');
+		hexString = derBuffer.toString('hex');
+	} else {
+		// Browser environment
+		const binaryString = atob(base64);
+		hexString = Array.from(binaryString, (char) =>
+			char.charCodeAt(0).toString(16).padStart(2, '0')
+		).join('');
+	}
+
+	// Convert to hex string with 0x prefix
+	return '0x' + hexString;
+}
+
+/*
+ * Helper function to convert DER hex format to PEM PKCS#8 format
+ * @param derHex - DER format as hex string (with or without '0x' prefix)
+ * @returns PEM formatted public key string
+ */
+export function derToPem(derHex: string): string {
+	// Remove '0x' prefix if present
+	const hexString = derHex.startsWith('0x') ? derHex.slice(2) : derHex;
+
+	// Convert hex to base64
+	let base64: string;
+
+	// Check if running in Node.js or browser
+	if (typeof Buffer !== 'undefined') {
+		// Node.js environment
+		const derBuffer = Buffer.from(hexString, 'hex');
+		base64 = derBuffer.toString('base64');
+	} else {
+		// Browser environment
+		// Convert hex string to byte array
+		const bytes = new Uint8Array(hexString.length / 2);
+		for (let i = 0; i < hexString.length; i += 2) {
+			bytes[i / 2] = parseInt(hexString.substr(i, 2), 16);
+		}
+		// Convert byte array to binary string
+		const binaryString = String.fromCharCode(...bytes);
+		// Convert to base64
+		base64 = btoa(binaryString);
+	}
+
+	// Split base64 into 64-character lines for PEM format
+	const lines: string[] = [];
+	for (let i = 0; i < base64.length; i += 64) {
+		lines.push(base64.slice(i, i + 64));
+	}
+
+	// Construct PEM format with headers and footers
+	return (
+		'-----BEGIN PUBLIC KEY-----\n' +
+		lines.join('\n') +
+		'\n-----END PUBLIC KEY-----'
+	);
+}