ODude Name Resolver

@odude/resolve is a comprehensive JavaScript library designed for resolving ODude Names to wallet addresses, TokenURIs, and website URLs. It also supports reverse lookups, enabling you to find ODude Names associated with wallet addresses. This package is compatible with multiple blockchain networks, including Polygon (MATIC), Ethereum (ETH), and Filecoin Virtual Machine (FVM), making it an excellent choice for integrating ODude Name services into your Web3 applications.

Features

• ODude Name Resolution: Resolve ODude Names to their corresponding wallet addresses.
• Reverse Lookup: Find ODude Names associated with specific wallet addresses.
• TokenURI Retrieval: Obtain the TokenURI associated with an ODude Name.
• Website URL Retrieval: Get the decentralized website URL linked to an ODude Name.
• Multi-Network Support: Seamlessly works with Polygon, Ethereum, and FVM networks.
• Comprehensive Token Management: Access approved addresses, owner information, and token metadata.
• Commission and TLD Information: Retrieve commission dealer data and TLD-specific information.
• Domain Enumeration: List all domains owned by an address and access total supply information.

Installation

Install the package using npm:

npm install @odude/resolve

Configuration

To use the package, you need to provide blockchain RPC URLs and a wallet private key. Store these securely in a .env file in your project root. Example configuration:

const settings = {
  matic_rpc_url: process.env.MATIC_RPC,  // Polygon RPC URL
  eth_rpc_url: process.env.ETH_RPC,       // Ethereum RPC URL
  fvm_rpc_url: process.env.FVM_RPC,       // Filecoin Virtual Machine RPC URL
  wallet_pvt_key: process.env.PVT_KEY    // Wallet private key
};

Note: For enhanced security, it is recommended to use an empty wallet's private key. The private key is solely used for read operations.

Usage Examples

1. Resolving an ODude Name to a Wallet Address

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

resolve.getAddress("hello@web3", "ETH").then(address => {
  console.log("Wallet address of hello@web3 is: ", address);
}).catch(console.error);

2. Performing a Reverse Lookup: Wallet Address to ODude Name

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

resolve.getDomain("0xaa481F8d2d966e5fCC0446fA459F5d580AE5ea9f", "MATIC").then(domain => {
    console.log("ODude Name for address 0xaa481F8d2d966e5fCC0446fA459F5d580AE5ea9f on MATIC: " + domain);
}).catch(console.error);

3. Retrieving a TokenURI

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

resolve.w3d_tokenURI("hello@web3").then(tokenURI => {
    console.log("TokenURI for hello@web3: " + tokenURI);
}).catch(console.error);

4. Retrieving a Website URL

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

resolve.getWeb("hello@web3").then(website => {
    console.log("Website URL for hello@web3 is: " + website);
}).catch(console.error);

5. Retrieving the Approved Address for a Token

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

resolve.getAddress("hello@web3", "ETH").then(async (address) => {
  if (address) {
    let contract = resolve.getContract("hello@web3");
    let tokenId = await contract.methods.getID("hello@web3").call();

    resolve.getApproved(tokenId, "web3").then(approved => {
      console.log("Approved address for token:", approved);
    }).catch(console.error);
  }
});

6. Retrieving Commission Information

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

// Get commission dealer information
resolve.getCommDealers("web3").then(commDealer => {
  console.log("Commission Dealer value:", commDealer);
}).catch(console.error);

// Get commission TLD for a specific token
resolve.getCommTLD(tokenId, "web3").then(commTLD => {
  console.log("Commission TLD:", commTLD);
}).catch(console.error);

7. Retrieving Token Owner Information

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

// Using ownerOf method (alternative to getAddress)
resolve.ownerOf(tokenId, "web3").then(owner => {
  console.log("Token owner:", owner);
}).catch(console.error);

8. Retrieving Total Supply

const ODudeName = require("@odude/resolve");
require('dotenv').config(); // Load environment variables from .env file

const settings = {
    matic_rpc_url: process.env.MATIC_RPC,
    eth_rpc_url: process.env.ETH_RPC,
    fvm_rpc_url: process.env.FVM_RPC,
    wallet_pvt_key: process.env.PVT_KEY
};

const resolve = new ODudeName(settings);

// Get total supply of tokens
resolve.totalSupply("web3").then(total => {
  console.log("Total supply:", total);
}).catch(console.error);

API Reference

Core Methods

getAddress(name, currency)

Resolves an ODude Name to its associated wallet address.

• Parameters:
  • name (string): The ODude Name (e.g., "hello@web3", "domain@fil")
  • currency (string): Currency type (usually "ETH")
• Returns: Promise<string | null> - The wallet address or null if not found

getDomain(address, provider)

Performs reverse lookup to find the ODude Name associated with a wallet address.

• Parameters:
  • address (string): The wallet address
  • provider (string): Network provider ("matic", "fvm", etc.)
• Returns: Promise<string | null> - The domain name or null if not found

getWeb(name)

Retrieves the website URL associated with an ODude Name.

• Parameters:
  • name (string): The ODude Name
• Returns: Promise<string | null> - The website URL or null if not found

Token Management Methods

getApproved(tokenId, provider)

Gets the approved address for a specific token ID.

• Parameters:
  • tokenId (number): The token ID
  • provider (string): Network provider
• Returns: Promise<string | null> - The approved address or null

ownerOf(tokenId, provider)

Gets the owner of a specific token ID.

• Parameters:
  • tokenId (number): The token ID
  • provider (string): Network provider
• Returns: Promise<string | null> - The owner address or null

totalSupply(provider)

Gets the total supply of tokens on the specified network.

• Parameters:
  • provider (string): Network provider
• Returns: Promise<number | null> - The total supply or null

Commission & TLD Methods

getCommDealers(provider)

Gets the commission dealer value.

• Parameters:
  • provider (string): Network provider
• Returns: Promise<number | null> - The commission dealer value or null

getCommTLD(tokenId, provider)

Gets the commission TLD for a specific token.

• Parameters:
  • tokenId (number): The token ID
  • provider (string): Network provider
• Returns: Promise<number | null> - The commission TLD value or null

getErcTLD(tokenId, provider)

Gets the ERC TLD address for a specific token.

• Parameters:
  • tokenId (number): The token ID
  • provider (string): Network provider
• Returns: Promise<string | null> - The ERC TLD address or null

Test Examples

Example test scripts are available in the test/ folder:

• test/address.js – Tests ODude Name to wallet address resolution
• test/domain.js – Tests wallet address to ODude Name reverse lookup
• test/hash.js – Tests ODude Name to TokenURIs & Website URL resolution
• test/extra.js – Tests additional functions (getApproved, getCommDealers, etc.)

Run the test scripts using Node.js:

node test/address.js
node test/domain.js
node test/hash.js
node test/extra.js

Supported Networks

The library supports multiple blockchain networks:

• Polygon (MATIC): For domains ending with @web3, @crypto, @nft, etc.
• Filecoin Virtual Machine (FVM): For domains ending with @fil, @fvm, @ipfs, @filecoin
• Ethereum: For domains ending with @eth

Error Handling

All methods return null under the following conditions:

• The domain does not exist or has not been minted.
• Network connection issues occur.
• Invalid parameters are provided.
• Smart contract calls fail.

Implement robust error handling in your applications:

resolve.getAddress("domain@web3", "ETH")
  .then(address => {
    if (address) {
      console.log("Address found:", address);
    } else {
      console.log("Domain not found or not minted");
    }
  })
  .catch(error => {
    console.error("Error occurred:", error);
  });

Environment Setup

1. Install Dependencies:

   npm install dotenv axios web3

2. Create .env File: Create a .env file in your project root with the following variables:

   MATIC_RPC=https://polygon-mainnet.g.alchemy.com/v2/your-api-key
   ETH_RPC=https://eth-mainnet.g.alchemy.com/v2/your-api-key
   FVM_RPC=https://api.node.glif.io/rpc/v1
   PVT_KEY=your-wallet-private-key-here

   Important: Use an empty wallet's private key for security. The private key is only used for read operations.

Developer Instructions

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/odudename/resolve.git
   cd resolve

2. Install dependencies:

   npm install

3. Create your .env file with the required RPC URLs and private key.

4. Run tests to verify everything works:

   node test/address.js
   node test/extra.js

Adding New Functions

To add new functions to the library:

1. Update ABI: Add the function definition to odudename.json
2. Implement Method: Add the method to the ODudeName class in index.js
3. Create Tests: Add test cases in the test/ folder
4. Update Documentation: Update this README with the new function details

Function Implementation Pattern

Follow this pattern when adding new functions:

/**
 * @async
 * @function functionName
 * @description Description of what the function does
 * @param {parameters} parameters - function parameters
 * @param {string} provider - The network provider (e.g., "matic", "fvm").
 * @returns {Promise<string|null>} - function result
 */
functionName = async (parameters, provider) => {
  try {
    let contract = this.getContract(provider);
    var result = await contract.methods.contractMethod(parameters).call();
    return result;
  } catch (error) {
    return null;
  }
};

Troubleshooting

Common Issues

1. "Missing required settings" Error

   • Ensure all RPC URLs and private key are provided in settings
   • Check that your .env file is properly configured

2. Network Connection Issues

   • Verify your RPC URLs are correct and accessible
   • Check if the RPC provider has rate limits

3. Domain Not Found

   • Verify the domain name format (e.g., "hello@web3")
   • Check if the domain is actually minted on the blockchain

4. Token ID Issues

   • Use getID() method first to get the token ID for a domain
   • Ensure the token ID exists before calling token-specific methods

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Make your changes following the existing code patterns
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

Please feel free to submit issues or pull requests on GitHub.

License

This project is licensed under the MIT License.

Support

For support and questions:

• GitHub Issues: https://github.com/odudename/resolve/issues
• Documentation: This README file
• Test Examples: Check the test/ folder for working examples