@beclab/olaresid 0.1.13 → 0.2.0

package/examples/create-with-rpc-demo.ts

@@ -0,0 +1,142 @@
+import OlaresID from '../src/index';
+
+/**
+ * Example: Using createWithRpc factory function
+ *
+ * This demonstrates the middle-ground factory function that:
+ * - Allows you to specify a custom RPC endpoint
+ * - Automatically configures all contract addresses based on network type
+ * - Simpler than createConsole but more flexible than createMainnet/createTestnet
+ *
+ * Use cases:
+ * - You want to use your own RPC endpoint for better performance
+ * - You need to connect through a specific RPC provider
+ * - You want mainnet/testnet contracts but custom connectivity
+ *
+ * Run: npx ts-node examples/create-with-rpc-demo.ts
+ */
+
+async function main() {
+	console.log('🚀 createWithRpc Demo\n');
+	console.log('='.repeat(80));
+	console.log('This example demonstrates three factory methods:\n');
+
+	// ============================================================================
+	// 1. createMainnet() - Fully configured for mainnet
+	// ============================================================================
+	console.log('📝 Method 1: createMainnet()');
+	console.log('-'.repeat(80));
+	console.log('✅ Pros: Zero configuration, ready to use');
+	console.log('❌ Cons: Uses default public RPC (may be slow)\n');
+
+	const consoleMainnet = OlaresID.createMainnet();
+	console.log(`RPC: ${consoleMainnet.rpcNode}`);
+	console.log(`Query Contract: ${consoleMainnet.queryContractAddress}`);
+
+	// ============================================================================
+	// 2. createWithRpc() - Custom RPC with auto contract config
+	// ============================================================================
+	console.log('\n📝 Method 2: createWithRpc(customRpc, network)');
+	console.log('-'.repeat(80));
+	console.log('✅ Pros: Custom RPC for better performance');
+	console.log('✅ Pros: All contracts auto-configured for network');
+	console.log('❌ Cons: Need to specify RPC endpoint\n');
+
+	// Example: Using a custom mainnet RPC
+	const customMainnetRpc = 'https://optimism.llamarpc.com';
+	const consoleCustomMainnet = OlaresID.createWithRpc(
+		customMainnetRpc,
+		'mainnet'
+	);
+	console.log(`Custom Mainnet:`);
+	console.log(`  RPC: ${consoleCustomMainnet.rpcNode}`);
+	console.log(
+		`  Query Contract: ${consoleCustomMainnet.queryContractAddress}`
+	);
+
+	// Example: Using a custom sepolia RPC
+	const customSepoliaRpc = 'https://sepolia.optimism.io';
+	const consoleCustomSepolia = OlaresID.createWithRpc(
+		customSepoliaRpc,
+		'sepolia'
+	);
+	console.log(`\nCustom Sepolia:`);
+	console.log(`  RPC: ${consoleCustomSepolia.rpcNode}`);
+	console.log(
+		`  Query Contract: ${consoleCustomSepolia.queryContractAddress}`
+	);
+
+	// Network defaults to 'mainnet' if not specified
+	const consoleDefaultNetwork = OlaresID.createWithRpc(
+		'https://my-optimism-rpc.com'
+	);
+	console.log(`\nDefault Network (mainnet):`);
+	console.log(`  RPC: ${consoleDefaultNetwork.rpcNode}`);
+	console.log(
+		`  Query Contract: ${consoleDefaultNetwork.queryContractAddress}`
+	);
+
+	// ============================================================================
+	// 3. createConsole() - Fully manual configuration
+	// ============================================================================
+	console.log('\n📝 Method 3: createConsole(...all params)');
+	console.log('-'.repeat(80));
+	console.log('✅ Pros: Complete control over all contracts');
+	console.log('❌ Cons: Most verbose, need to know all addresses\n');
+
+	const consoleManual = OlaresID.createConsole(
+		'https://optimism-rpc.publicnode.com',
+		'0x5DA4Fa8E567d86e52Ef8Da860de1be8f54cae97D', // contractDid
+		'0x9bA3D0D3d2046aeD57e9897F7F79C58DfAa5325A', // contractRootResolver
+		'0x9ae3F16bD99294Af1784beB1a0A5C84bf2636365', // contractAbiType
+		'0x7e7961aB771cA942CE4DB6e79579e016a33Dc95B', // contractRootResolver2
+		'https://api.olares.com/did/support', // supportSvcUrl
+		'0x8305411EEa5C3F99f9426845Cf2977E77D5a1711' // queryContract
+	);
+	console.log(`Manual Configuration:`);
+	console.log(`  RPC: ${consoleManual.rpcNode}`);
+	console.log(`  Query Contract: ${consoleManual.queryContractAddress}`);
+
+	// ============================================================================
+	// Test with real query
+	// ============================================================================
+	console.log('\n\n📊 Real Query Test');
+	console.log('='.repeat(80));
+	console.log('Testing createWithRpc with a real domain query...\n');
+
+	const testConsole = OlaresID.createWithRpc(
+		'https://optimism-rpc.publicnode.com', // Use default public RPC
+		'mainnet'
+	);
+
+	const totalSupply = await testConsole.getTotalSupply();
+	console.log(`✅ Total domains: ${totalSupply}`);
+
+	// Fetch a single domain
+	const domain = await testConsole.fetchDomain('tw7613781.olares.com');
+	if (domain) {
+		console.log(`✅ Fetched domain: ${domain.name}`);
+		console.log(`   Owner: ${domain.owner}`);
+		console.log(`   Tags: ${domain.tags.length}`);
+	}
+
+	console.log('\n' + '='.repeat(80));
+	console.log('✅ Demo completed successfully!');
+	console.log('\n💡 Summary:');
+	console.log('   createMainnet()         → Default RPC + mainnet contracts');
+	console.log('   createTestnet()         → Default RPC + sepolia contracts');
+	console.log(
+		'   createWithRpc(rpc, net) → Custom RPC + auto contracts (NEW!)'
+	);
+	console.log('   createConsole(...)      → Full manual control');
+}
+
+// Run the example
+main().catch((error) => {
+	console.error('\n❌ Error:', error);
+	if (error instanceof Error) {
+		console.error('Message:', error.message);
+		console.error('Stack:', error.stack);
+	}
+	process.exit(1);
+});

package/examples/fetch-all-flat-demo.ts

@@ -0,0 +1,159 @@
+import OlaresID from '../src/index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Example: Using fetchAllFlat to efficiently fetch all domains
+ *
+ * Usage:
+ *
+ * # Test on OP Sepolia (default)
+ * npx ts-node examples/fetch-all-flat-demo.ts
+ *
+ * # Test on Mainnet
+ * NETWORK=mainnet npx ts-node examples/fetch-all-flat-demo.ts
+ */
+
+async function main() {
+	console.log('🚀 fetchAllFlat Demo\n');
+	console.log('='.repeat(80));
+
+	// Setup
+	const network = process.env.NETWORK || 'sepolia'; // 'sepolia' or 'mainnet'
+
+	console.log('📝 Config:');
+	console.log(`  Network: ${network}`);
+
+	// Create console based on network
+	const didConsole =
+		network === 'mainnet'
+			? OlaresID.createMainnet()
+			: OlaresID.createTestnet();
+
+	console.log(
+		`  Using ${
+			network === 'mainnet' ? 'mainnet' : 'testnet (OP Sepolia)'
+		} configuration`
+	);
+	console.log(`  RPC: ${didConsole.rpcNode}`);
+
+	// Verify query contract is configured
+	if (!didConsole.queryContractAddress) {
+		console.error(
+			`\n❌ Error: Query contract address not configured for ${network}`
+		);
+		console.error('   Please configure it in config.json');
+		process.exit(1);
+	}
+
+	console.log(`  Query Contract: ${didConsole.queryContractAddress}`);
+	console.log('='.repeat(80));
+
+	try {
+		// Fetch all domains
+		console.log('\n📦 Fetching all domains...\n');
+
+		const startTime = Date.now();
+		const domains = await didConsole.fetchAllFlat({
+			batchSize: 50,
+			onProgress: (current, total) => {
+				const percent = ((current / total) * 100).toFixed(1);
+				process.stdout.write(
+					`\r  Progress: ${current}/${total} (${percent}%)`
+				);
+			}
+		});
+		const elapsed = Date.now() - startTime;
+
+		console.log(
+			`\n\n✅ Fetched ${domains.length} domains in ${elapsed}ms\n`
+		);
+
+		// Save to JSON file
+		const outputDir = path.join(__dirname, '../output');
+		if (!fs.existsSync(outputDir)) {
+			fs.mkdirSync(outputDir, { recursive: true });
+		}
+
+		const timestamp = new Date()
+			.toISOString()
+			.replace(/[:.]/g, '-')
+			.split('T')[0];
+		const outputFile = path.join(
+			outputDir,
+			`domains-${network}-${timestamp}.json`
+		);
+		fs.writeFileSync(outputFile, JSON.stringify(domains, null, 2), 'utf-8');
+
+		console.log(`💾 Data saved to: ${outputFile}`);
+		console.log('='.repeat(80));
+
+		// Analyze results
+		console.log('\n📊 Statistics:');
+		const topLevel = domains.filter((d) => d.level === 1);
+		const subdomains = domains.filter((d) => d.level > 1);
+		const withTags = domains.filter((d) => d.tags.length > 0);
+
+		console.log(`  Total domains: ${domains.length}`);
+		console.log(`  Top-level domains: ${topLevel.length}`);
+		console.log(`  Subdomains: ${subdomains.length}`);
+		console.log(`  Domains with tags: ${withTags.length}`);
+
+		// Show examples
+		console.log('\n📝 Example domains:\n');
+
+		// Top-level domain
+		const topDomain = topLevel[0];
+		if (topDomain) {
+			console.log(`1. Top-level domain: ${topDomain.name}`);
+			console.log(`   - ID: ${topDomain.id}`);
+			console.log(`   - Level: ${topDomain.level}`);
+			console.log(`   - Owner: ${topDomain.owner}`);
+			console.log(`   - Tags: ${topDomain.tags.length}`);
+			console.log(`   - Parent ID: ${topDomain.parentId || 'none'}`);
+		}
+
+		// Subdomain
+		const subdomain = subdomains[0];
+		if (subdomain) {
+			console.log(`\n2. Subdomain: ${subdomain.name}`);
+			console.log(`   - ID: ${subdomain.id}`);
+			console.log(`   - Level: ${subdomain.level}`);
+			console.log(`   - Owner: ${subdomain.owner}`);
+			console.log(`   - Tags: ${subdomain.tags.length}`);
+			console.log(`   - Parent ID: ${subdomain.parentId || 'not found'}`);
+		}
+
+		// Domain with tags
+		const domainWithTags = withTags[0];
+		if (domainWithTags) {
+			console.log(`\n3. Domain with tags: ${domainWithTags.name}`);
+			console.log(`   - Tags count: ${domainWithTags.tags.length}`);
+
+			domainWithTags.tags.slice(0, 3).forEach((tag, i) => {
+				console.log(`   - Tag ${i + 1}: ${tag.name}`);
+				console.log(`     * From: ${tag.from || 'global'}`);
+				console.log(`     * Type: ${tag.abiType}`);
+				if (tag.valueFormatted) {
+					const preview =
+						tag.valueFormatted.length > 50
+							? tag.valueFormatted.substring(0, 50) + '...'
+							: tag.valueFormatted;
+					console.log(`     * Value: ${preview}`);
+				}
+			});
+		}
+
+		console.log('\n' + '='.repeat(80));
+		console.log('✅ Demo completed successfully!');
+	} catch (error) {
+		console.error('\n❌ Error:', error);
+		if (error instanceof Error) {
+			console.error('Message:', error.message);
+			console.error('Stack:', error.stack);
+		}
+		process.exit(1);
+	}
+}
+
+main().catch(console.error);

package/examples/fetch-by-indices-demo.ts

@@ -0,0 +1,235 @@
+import OlaresID from '../src/index';
+
+/**
+ * Example: Fetching domains by specific indices
+ *
+ * This demonstrates fetchDomainsByIndices which uses a SINGLE RPC call to:
+ * - Map indices to tokenIds (done in contract)
+ * - Fetch all domain data in one batch
+ *
+ * Benefits:
+ * - No RPC rate limiting issues (single call vs multiple parallel calls)
+ * - 20% more gas efficient than separate getTokenByIndex calls
+ * - Simpler and more reliable
+ *
+ * Use cases:
+ * - Fetching specific domains when you know their indices
+ * - Sampling domains (e.g., every 100th domain)
+ * - Retrieving bookmarked/favorite domains by index
+ * - Testing with specific domain positions
+ *
+ * Run: npx ts-node examples/fetch-by-indices-demo.ts
+ */
+
+async function main() {
+	// Use testnet for faster testing
+	const network = process.env.NETWORK || 'sepolia';
+
+	console.log('🚀 fetchDomainsByIndices Demo\n');
+	console.log('='.repeat(80));
+	console.log('📝 Config:');
+	console.log(`  Network: ${network}`);
+	console.log('='.repeat(80));
+	console.log('');
+
+	// Create console instance
+	const didConsole =
+		network === 'mainnet'
+			? OlaresID.createMainnet()
+			: OlaresID.createTestnet();
+
+	// Verify query contract is configured
+	if (!didConsole.queryContractAddress) {
+		console.error(
+			'❌ Error: Query contract address not configured for this network'
+		);
+		process.exit(1);
+	}
+
+	console.log(`📋 Query Contract: ${didConsole.queryContractAddress}\n`);
+
+	// Get total supply first
+	const totalSupply = Number(await didConsole.getTotalSupply());
+	console.log(`📊 Total domains: ${totalSupply}\n`);
+
+	// ============================================================================
+	// Example 1: Fetch specific indices
+	// ============================================================================
+	console.log('📄 Example 1: Fetch Specific Indices');
+	console.log('-'.repeat(80));
+
+	// Fetch domains at indices 5, 6, 9, 10
+	const specificIndices = [5, 6, 9, 10];
+	console.log(
+		`Fetching domains at indices: [${specificIndices.join(', ')}]\n`
+	);
+
+	const startTime1 = Date.now();
+	const specificDomains = await didConsole.fetchDomainsByIndices(
+		specificIndices
+	);
+	const elapsed1 = Date.now() - startTime1;
+
+	console.log(
+		`✅ Fetched ${specificDomains.length} domains in ${elapsed1}ms\n`
+	);
+
+	specificDomains.forEach((domain, i) => {
+		console.log(`  Index ${specificIndices[i]}: ${domain.name}`);
+		console.log(`    Owner: ${domain.owner}`);
+		console.log(`    Tags: ${domain.tags.length}, Level: ${domain.level}`);
+	});
+
+	// ============================================================================
+	// Example 2: Sample domains (every 10th domain)
+	// ============================================================================
+	if (totalSupply > 50) {
+		console.log('\n📄 Example 2: Sample Domains (every 10th)');
+		console.log('-'.repeat(80));
+
+		// Get every 10th domain up to 50
+		const samplingIndices = [0, 10, 20, 30, 40, 50].filter(
+			(i) => i < totalSupply
+		);
+		console.log(`Sampling indices: [${samplingIndices.join(', ')}]\n`);
+
+		const startTime2 = Date.now();
+		const sampledDomains = await didConsole.fetchDomainsByIndices(
+			samplingIndices
+		);
+		const elapsed2 = Date.now() - startTime2;
+
+		console.log(
+			`✅ Sampled ${sampledDomains.length} domains in ${elapsed2}ms\n`
+		);
+
+		sampledDomains.forEach((domain, i) => {
+			console.log(
+				`  Index ${samplingIndices[i]}: ${domain.name} (${domain.tags.length} tags)`
+			);
+		});
+	}
+
+	// ============================================================================
+	// Example 3: First and last domains
+	// ============================================================================
+	console.log('\n📄 Example 3: First and Last Domains');
+	console.log('-'.repeat(80));
+
+	const firstLastIndices = [0, totalSupply - 1];
+	console.log(`Fetching indices: [${firstLastIndices.join(', ')}]\n`);
+
+	const startTime3 = Date.now();
+	const firstLastDomains = await didConsole.fetchDomainsByIndices(
+		firstLastIndices
+	);
+	const elapsed3 = Date.now() - startTime3;
+
+	console.log(
+		`✅ Fetched ${firstLastDomains.length} domains in ${elapsed3}ms\n`
+	);
+
+	console.log(`  First domain (index 0):`);
+	console.log(`    Name: ${firstLastDomains[0].name}`);
+	console.log(`    Owner: ${firstLastDomains[0].owner}`);
+
+	console.log(`\n  Last domain (index ${totalSupply - 1}):`);
+	console.log(`    Name: ${firstLastDomains[1].name}`);
+	console.log(`    Owner: ${firstLastDomains[1].owner}`);
+
+	// ============================================================================
+	// Example 4: Comparison with pagination
+	// ============================================================================
+	console.log('\n📊 Example 4: Performance Comparison');
+	console.log('-'.repeat(80));
+
+	// Method 1: fetchDomainsByIndices
+	const indices = [5, 15, 25, 35, 45];
+	console.log(`\nMethod 1: fetchDomainsByIndices([${indices.join(', ')}])`);
+	const start1 = Date.now();
+	const resultByIndices = await didConsole.fetchDomainsByIndices(
+		indices.filter((i) => i < totalSupply)
+	);
+	const time1 = Date.now() - start1;
+	console.log(`✅ Fetched ${resultByIndices.length} domains in ${time1}ms`);
+
+	// Method 2: Multiple fetchDomains calls (pagination approach)
+	console.log(`\nMethod 2: Multiple fetchDomains calls (paginated)`);
+	const start2 = Date.now();
+	const resultByPagination = [];
+	for (const index of indices) {
+		if (index < totalSupply) {
+			const domains = await didConsole.fetchDomains(index, 1);
+			resultByPagination.push(...domains);
+		}
+	}
+	const time2 = Date.now() - start2;
+	console.log(
+		`✅ Fetched ${resultByPagination.length} domains in ${time2}ms`
+	);
+
+	console.log(
+		`\n💡 Performance: fetchDomainsByIndices is ${(time2 / time1).toFixed(
+			1
+		)}x faster!`
+	);
+
+	// ============================================================================
+	// Example 5: Error handling
+	// ============================================================================
+	console.log('\n⚠️  Example 5: Error Handling');
+	console.log('-'.repeat(80));
+
+	// Test invalid index
+	try {
+		await didConsole.fetchDomainsByIndices([-1]);
+	} catch (error) {
+		console.log('✅ Correctly caught error for negative index:');
+		console.log(`   ${(error as Error).message}`);
+	}
+
+	// Test out of bounds
+	try {
+		await didConsole.fetchDomainsByIndices([totalSupply + 100]);
+	} catch (error) {
+		console.log('✅ Correctly caught error for out-of-bounds index:');
+		console.log(`   ${(error as Error).message}`);
+	}
+
+	// Test empty array
+	try {
+		await didConsole.fetchDomainsByIndices([]);
+	} catch (error) {
+		console.log('✅ Correctly caught error for empty array:');
+		console.log(`   ${(error as Error).message}`);
+	}
+
+	console.log('\n' + '='.repeat(80));
+	console.log('✅ Demo completed successfully!');
+	console.log('\n💡 Use Cases for fetchDomainsByIndices:');
+	console.log('   - Fetch specific domains by position');
+	console.log('   - Sample domains at regular intervals');
+	console.log('   - Random access without pagination overhead');
+	console.log('   - Bookmarked/favorite domains by index');
+	console.log('\n💡 Key Benefits:');
+	console.log('   ✅ Single RPC call (no rate limiting issues)');
+	console.log('   ✅ 20% more gas efficient');
+	console.log('   ✅ Simpler implementation');
+	console.log('\n💡 API Differences:');
+	console.log(
+		'   fetchDomains(offset, limit)    → Contiguous range [offset, offset+limit)'
+	);
+	console.log(
+		'   fetchDomainsByIndices(indices) → Specific positions [5, 10, 50, 100]'
+	);
+}
+
+// Run the example
+main().catch((error) => {
+	console.error('\n❌ Error:', error);
+	if (error instanceof Error) {
+		console.error('Message:', error.message);
+		console.error('Stack:', error.stack);
+	}
+	process.exit(1);
+});

package/examples/fetch-domain-demo.ts

@@ -0,0 +1,137 @@
+import OlaresID from '../src/index';
+
+/**
+ * Example: Using fetchDomain to fetch a single domain
+ *
+ * Usage:
+ *
+ * # Test on OP Sepolia (default)
+ * npx ts-node examples/fetch-domain-demo.ts
+ *
+ * # Fetch by domain name
+ * DOMAIN_NAME=alice.olares.com npx ts-node examples/fetch-domain-demo.ts
+ *
+ * # Fetch by tokenId
+ * TOKEN_ID=0x123... npx ts-node examples/fetch-domain-demo.ts
+ *
+ * # Test on Mainnet
+ * NETWORK=mainnet DOMAIN_NAME=alice.olares.com npx ts-node examples/fetch-domain-demo.ts
+ */
+
+async function main() {
+	console.log('🚀 fetchDomain Demo\n');
+	console.log('='.repeat(80));
+
+	// Setup
+	const network = process.env.NETWORK || 'sepolia';
+	const domainName = process.env.DOMAIN_NAME || '1.com';
+	const tokenId = process.env.TOKEN_ID;
+
+	const nameOrTokenId = tokenId || domainName;
+
+	console.log('📝 Config:');
+	console.log(`  Network: ${network}`);
+	console.log(`  Query: ${nameOrTokenId}`);
+	console.log(`  Type: ${tokenId ? 'tokenId' : 'domain name'}`);
+
+	// Create console based on network
+	const didConsole =
+		network === 'mainnet'
+			? OlaresID.createMainnet()
+			: OlaresID.createTestnet();
+
+	console.log(
+		`  Using ${
+			network === 'mainnet' ? 'mainnet' : 'testnet (OP Sepolia)'
+		} configuration`
+	);
+	console.log(`  RPC: ${didConsole.rpcNode}`);
+
+	// Verify query contract is configured
+	if (!didConsole.queryContractAddress) {
+		console.error(
+			`\n❌ Error: Query contract address not configured for ${network}`
+		);
+		console.error('   Please configure it in config.json');
+		process.exit(1);
+	}
+
+	console.log(`  Query Contract: ${didConsole.queryContractAddress}`);
+	console.log('='.repeat(80));
+
+	try {
+		// Fetch single domain
+		console.log('\n📦 Fetching domain...\n');
+
+		const startTime = Date.now();
+		const domain = await didConsole.fetchDomain(nameOrTokenId);
+		const elapsed = Date.now() - startTime;
+
+		if (!domain) {
+			console.log('❌ Domain not found');
+			process.exit(0);
+		}
+
+		console.log(`✅ Fetched domain in ${elapsed}ms\n`);
+		console.log('='.repeat(80));
+
+		// Display domain info
+		console.log('\n📋 Domain Information:\n');
+		console.log(`  ID: ${domain.id}`);
+		console.log(`  Name: ${domain.name}`);
+		console.log(`  DID: ${domain.did}`);
+		console.log(`  Owner: ${domain.owner}`);
+		console.log(`  Level: ${domain.level}`);
+		console.log(`  Note: ${domain.note || '(empty)'}`);
+		console.log(`  Allow Subdomain: ${domain.allowSubdomain}`);
+		console.log(`  Parent ID: ${domain.parentId || 'none'}`);
+		console.log(`  Tags: ${domain.tags.length}`);
+
+		// Display tags
+		if (domain.tags.length > 0) {
+			console.log('\n🏷️  Tags:\n');
+
+			for (const tag of domain.tags) {
+				console.log(`  📌 ${tag.name}`);
+				console.log(`     From: ${tag.from || 'global'}`);
+				console.log(`     Type: ${tag.abiType}`);
+				console.log(
+					`     Value (hex): ${tag.value.substring(0, 66)}...`
+				);
+
+				if (tag.valueFormatted) {
+					console.log(`     Formatted:`);
+					const formatted =
+						typeof tag.valueFormatted === 'string'
+							? tag.valueFormatted
+							: JSON.stringify(tag.valueFormatted, null, 6);
+
+					// Indent formatted output
+					const lines = formatted.split('\n');
+					lines.forEach((line) => {
+						console.log(`       ${line}`);
+					});
+				}
+
+				if (tag.fieldNamesHash.length > 0) {
+					console.log(
+						`     Field Names Hash: ${tag.fieldNamesHash.length} hashes`
+					);
+				}
+				console.log();
+			}
+		}
+
+		console.log('='.repeat(80));
+		console.log('✅ Demo completed successfully!');
+	} catch (error) {
+		console.error('\n❌ Error:', error);
+		if (error instanceof Error) {
+			console.error('Message:', error.message);
+			console.error('Stack:', error.stack);
+		}
+		process.exit(1);
+	}
+}
+
+main().catch(console.error);