Edit this page

Resolution-Go

This page details basic installation, configuration, and usage of the Golang Resolution Library.

Installation

Resolution Go can be installed with the go get command.

Copy
Copied
go get github.com/unstoppabledomains/resolution-go/v3

Updating Resolution Go

Resolution Go can be updated with the go get command.

Copy
Copied
go get -u github.com/unstoppabledomains/resolution-go/v3

Initialize with Unstoppable Domains' Proxy Provider

Copy
Copied
package main
import (
	"fmt"
	"github.com/unstoppabledomains/resolution-go/v3"
)
// obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key
uns, _ := resolution.NewUnsBuilder().SetUdClient("<api_key>").Build()
zilliqaProvider := provider.NewProvider("https://api.zilliqa.com")
	zns, _ := resolution.NewZnsBuilder().SetProvider(zilliqaProvider).Build()

Initialize with Custom Ethereum Provider Configuration

Configuration

The Resolution libraries require a connection to the Ethereum network to resolve domains (.crypto, .nft, etc.). To use these libraries, you must specify an Ethereum node service provider. Once you have created an instance of the library, you can begin resolving domains. Examples of how to initialize the library with different providers are provided below.

Provider URL

Each of the Resolution Libraries supports using an Ethereum provider URL for configuration. You can obtain this URL from a service like Alchemy, which offers a free API key to users who create an account. If you wish to use an alternative Ethereum provider, see the Nodes as a Service guide for more information.

Copy
Copied
package main
import (
	"fmt"
	"github.com/Zilliqa/gozilliqa-sdk/provider"
	"github.com/ethereum/go-ethereum/ethclient"
	"github.com/unstoppabledomains/resolution-go/v3"
)
func main() {
	// obtain a key from https://www.infura.io
	var ethereumUrl = "https://mainnet.infura.io/v3/<infura_api_key>"
	var ethereumL2Url = "https://polygon-mainnet.infura.io/v3/<infura_api_key>"
	var unsBuilder := resolution.NewUnsBuilder()
	var backend, _ := ethclient.Dial(ethereumUrl)
	var backendL2, _ := ethclient.Dial(ethereumL2Url)
	unsBuilder.SetContractBackend(backend)
	unsBuilder.SetL2ContractBackend(backendL2)
	var uns, _ = unsBuilder.Build()
	zilliqaProvider := provider.NewProvider("https://api.zilliqa.com")
	zns, _ := resolution.NewZnsBuilder().SetProvider(zilliqaProvider).Build()
}
warning

Make sure to allow eth-mainnet.g.alchemy.com and polygon-mainnet.g.alchemy.com or simply https://*.g.alchemy.com (if using the default configuration) as a connect-src in your Content Security Policy to allow these requests through.

Error Handling

Unstoppable Domains follows the error handling best practices specific to each library's language. Each error data structure contains an error code, a human-readable message, and extra details that may help you debug the error.

Copy
Copied
{
  code: string; // one of our custom error codes
  message?: string; // human-readable error summary
  providerMessage?: string; // internal error message from the provider (alchemy, infura, etc.)
  errorMessage?: string; // internal error message / nested error
  method?: ResolutionMethod; // resolution method (UNS L1, UNS L2, CNS, ZNS, UD API)
  methodName?: string; // resolution method that was used (e.g. Resolution.addr, Resolution.allRecords)
  domain?: string; // domain that caused the error
  currencyTicker?: string; // currency ticker that caused the error
  recordName?: string; // record that caused the error
  namingService?: string; // naming service (UNSL1, UNSL2, ZNS, ENS, CNS, etc.)
  location?: UnsLocation; // domain location (L1, L2)
  tokenUri?: string; // domain metadata link
}

The code snippet below shows how to handle the common error cases you may encounter during integration, including:

  • Resolving an unregistered domain
  • Resolving an undefined record of a domain
  • Resolving a misconfigured domain
  • Resolving a domain with an unsupported domain ending

We handle the errors thrown by the resolution library by switching on the error code and displaying custom messages to the user. You can then perform other actions to handle the error or show the error message value from the error data structure to the user.

Copy
Copied
package main

import (
    "fmt"
    "github.com/unstoppabledomains/resolution-go/v3"
)

func main() {
    // obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key
    uns, _ := resolution.NewUnsBuilder().SetUdClient("<api_key>").Build()

    if err != nil {
        switch err.(type) {
        // UnsConfigurationError Error when UNS resolution service is configured incorrectly
        case *resolution.UnsConfigurationError:
            fmt.Println("Uns configuration error:", err.Error())
        default:
            fmt.Println("Unknown error")
        }
    }

    address, err := uns.Addr("domain-with-error.crypto", "ETH")

    if err != nil {
        switch err.(type) {
        // DomainNotRegisteredError Error when domain is missing an owner
        case *resolution.DomainNotRegisteredError:
            fmt.Println("DomainNotRegisteredError:", err.Error())
        // DomainNotConfiguredError Error when domain does not have a resolver set
        case *resolution.DomainNotConfiguredError:
            fmt.Println("DomainNotConfiguredError:", err.Error())
        // DomainNotSupportedError Error when domain is not supported by the naming service
        case *resolution.DomainNotSupportedError:
            fmt.Println("DomainNotSupportedError:", err.Error())
        // MethodIsNotSupportedError Error when naming services does not support called method
        case *resolution.MethodIsNotSupportedError:
            fmt.Println("MethodIsNotSupportedError:", err.Error())
        // InvalidDomainNameReturnedError Error when ERC721 metadata provides returns incorrect domain name
        case *resolution.InvalidDomainNameReturnedError:
            fmt.Println("InvalidDomainNameReturnedError:", err.Error())
        default:
            fmt.Println("Unknown error")
        }
    }
}

Error Codes

Error Code Description
DomainNotConfiguredError Thrown when the domain resolver contract address is not found. For example, the domain doesn't have a specified resolver.
DomainNotRegisteredError Thrown when you resolve a domain not owned by any address.
DomainNotSupportedError Thrown when you resolve a domain with an ending not supported by the current resolution instance.
InvalidDomainNameReturnedError Thrown when you resolve an invalid domain address.
MethodIsNotSupportedError Thrown when you use a method of the current resolution instance not supported by the naming service you're resolving from. For example, using the TokenURI(), TokenURIMetadata(), and Unhash() methods for the Zilliqa Name Service (ZNS).
UnsConfigurationError Thrown when the UNS resolution service is misconfigured.

Use Case: Retrieve a Domain Record

Retrieve any record of a domain. Applications sometimes set custom records for a domain to use within their application. The code snippet below show how to do this in Golang.

Copy
Copied
ethAddress, _ := uns.Addr("brad.crypto", "ETH")
fmt.Println("ETH address for brad.crypto is", ethAddress)

Use Case: Resolve Addresses Existing on Multiple Blockchains

The resolution library provides a method for resolving the addresses of tickers for different blockchains (e.g. USDT exists on EOS, ERC20, OMNI, and TRON blockchains). The code snippet below show how to do this in Golang.

Copy
Copied
usdtAddress, _ := uns.AddrVersion("udtestdev-usdt.crypto", "USDT", "ERC20")
fmt.Println("USDT-ERC20 address for udtestdev-usdt.crypto is", usdtAddress)