Resolving a Starname

This is how to get the information attached to a starname.

A starname can have two different formats:

• *domain

• name*domain

What is a valid starname format?

A Starname needs to match the following format:

• left*right, matching the regex ^[-.a-z0-9]{0,63}*[-a-z0-9]{1,32}$ . Please note the left part can be an empty string so benjamin*cosmostation and *cosmostation are two valid starnames which can be resolved.

If you look for a Starname which has an invalid format, you will fail to resolve. You can check before resolving that the format is matching the regex.

I know someone's starname, how do I know the associated info?

With a web browser, Starname explorer Big Dipper

You can easily check a starname with a web browser using the url: https://big-dipper.iov-mainnet-2.iov.one/starname/<your_starname>

For exemple, you can check https://big-dipper.iov-mainnet-2.iov.one/starname/*benjamin

On a web browser, you can see the friendly UI version of the starname at https://starname.me/<your_starname>, for exemple: https://starname.me/*benjamin

With the REST API

You can query the crypto-addresses associated with a starname ( fondation-aphp*iov as example) by running the command :

curl -X POST "https://iovnscli-rest-api.iov-mainnet-2.iov.one/starname/query/resolve" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{"starname":"fondation-aphp*iov"}'

If the starname looks like *mybusiness for example, you will run the same command :

curl -X POST "https://iovnscli-rest-api.iov-mainnet-2.iov.one/starname/query/resolve" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{"starname":"*benjamin"}'

The result of this POST is a JSON with the Starname data.

With the IOVNS CLI

You can query the crypto-addresses associated with a starname ( fondation-aphp*iov as example) by running the command :

iovnscli query starname resolve --starname fondation-aphp*iov

If the starname looks like *mybusiness for example, you will run the same command :

iovnscli query starname resolve --starname *benjamin

The result of this POST is a JSON with the Starname data.

The Starname data

These commands will return the information attached to the starname in a JSON format. To get the specific data you are looking for, you can simply parse the JSON data. It will look like this

{
    "account":{
        "domain":"iov",
        "name":"fondation-aphp",
        "owner":"star12uv6k3c650kvm2wpa38wwlq8azayq6tlh75d3y",
        "valid_until":1633046400,
        "resources":[
            {
                "uri":"asset:eth",
                "resource":"0x795997519227f64879977d1a53625707f29b25b2"
            },
            {"
                uri":"asset:btc",
                "resource":"14AcAvkYz9eUP226NpGvTf62uP4Du2NnZJ"
            },
            {
                "uri":"asset:bch",
                "resource":"bitcoincash:qzmddu0vq53dkeej9nwt6jm8nyzlfxgn2vnh46k77u"
            },
            {
                "uri":"asset:ltc",
                "resource":"M8N2BjsijFyQTYVAq7WXZGmC5dmLUbBefb"
            },
            {
                "uri":"asset:xtz",
                "resource":"tz1XAMyU4VtmMyber79FF56RESdrAcuN886z"
            },
            {
                "uri":"asset:atom",
                "resource":"cosmos18qvxu5t9h29pwhf6jtf0a2lpwt4y026e09tln9"
            }
        ],
        "certificates":null,
        "broker":"",
        "metadata_uri":""
    }
}

Field name	Description
account	the type of what has been resolved. An account is a starname, i.e. this is a name*domain
domain	the string after the * in a starname
name	the string before the * in a starname
owner	the star address of who has the right to edit and perform transactions on this starname. Note: the owner of a closed domain has the right to delete any starname of a closed domain.
valid_until	the expiry date of the starname, in seconds from 1jan1970
resources	an array of pair (uri, resource) where the uri is the unique asset-id (string) to a resource, the associated crypto address (string). The list of asset-id can use is here.
broker	the star address of who has helped registering this starname -- most likely the app that was used to register the name, and it will be rewarded for this
metadata_uri	the uri of the metadata of the starname (string) -- For example it can be the URL of a link to IPFS which return a JSON file with the full name, a picture and a small description of the starname

Typically, you will be using the Resolver to look for the specific address of the recipient for the asset you want to send.

For exemple, you want to send BTC to *benjamin. You are therefore looking for the BTC address associated with the Starname *benjamin.

• You send the request to resolve starname *benjamin (via REST or CLI), and you receive the Starname JSON data.

• Because you are sending BTC, you are looking for the data associated with the uri: asset:btc. For all common coins, the uri is asset:xxx where xxx is the ticker of the coin. You can see here all the Asset Tickers.

• At this point, get the value of the field resources. It is an array of pair uri, resource. Search for the pair where the uri is matching asset:btc and return the value of the field resource. If you don't find any matching uri, then it means that there is no BTC address associated with this Starname yet.