Working with blockchain names

BNS names are blockchain name system names. You can register one or more addresses under a name, and every name has an owner. A name can also store key=value properties. The Diode CLI can be used to register, update, lookup, inspect, unregister, and transfer ownership of a blockchain name, and to set properties on it.

The Diode CLI command to manage BNS names is:

bns

invoked as:

diode bns <command>

Read below for details!

How to use BNS names

Blockchain names can be used to give any Ethereum address a human readable name. While this is just generally helpful for recognizing an address, it is also helpful for the following use cases:

• Decentralized website name - if you host a website at your Ethereum address, your BNS name is your website's name - anyone can type it into a Diode-enabled browser and view your website
• Failover for resource publication - you can register multiple addresses to a Domain name and the network will automatically handle fail-over in case the primary address is not available.
• Group management - BNS names are convenient to register multiple addresses to in order to set publication perimeters. For example, the "diode publish" command can publish to a BNS name as its publication context/perimeter. In this way, the BNS name address list becomes an allow-list for private publication, allowing CI/CD and on/offboarding automation for OT, IT, and IoT systems.

Commands

register name

diode bns -register <name>=<address(es)>

Note that registering a name will take at least one block time (more than 10 seconds and less than 5 minutes). The messages printed in the terminal will provide updates.

Example - register one address to a name:

diode bns -register mynewname=0x123229542c4afe8cd39da33f81bf698d57d3cb2a

Example - register two addresses to a name:

diode bns -register mynewname=0x123229542c4afe8cd39da33f81bf698d57d3cb2a,0xa8721a541c4a2e8cd39d433f81af698d57d1ca33

update name

To update a BNS name, your Diode CLI's address must be the owner of the name already. If it is not, you must transfer ownership of the name to your CLI's address.

diode bns -register <name>=<updated address(es)>

Note that updating a name will take at least one block time (more than 10 seconds and less than 5 minutes). The messages printed in the terminal will provide updates.

Example - update a name with a single address:

diode bns -register myoldname=0x123229542c4afe8cd39da33f81bf698d57d3cb2a

Example - update a name with two addresses:

diode bns -register myoldname=0x123229542c4afe8cd39da33f81bf698d57d3cb2a,0xa8721a541c4a2e8cd39d433f81af698d57d1ca33

lookup name

To lookup which addresses are registered under a name use "lookup".

diode bns -lookup <name>

This will produce a list of "Lookup result" lines listing one address registered to the name per line.

unregister name

If you no longer want to own a name, use "unregister".

diode bns -unregister <name>

This will release the name and someone else will be able to register it.

Note that unregistering a name will take at least one block time (more than 10 seconds and less than 5 minutes). The messages printed in the terminal will provide updates.

transfer name

If you want to give someone else the name, use "transfer".

diode bns -transfer <name>=<new owner>

This will transfer ownership of the name to the new owner address.

Note that transferring a name will take at least one block time (more than 10 seconds and less than 5 minutes). The messages printed in the terminal will provide updates.

BNS properties

A BNS name can store extra key=value records. The owner of the name is the only account that can change them. The public gateway reads one reserved key prefix, PX:, to route names under a custom domain.

Diode names are unchanged. division1.diode.link is still the BNS name division1.

Property commands

The name is the text before the first colon. The key may contain colons. The value is everything after the first =.

diode bns -set-property <name>:<key>=<value>
diode bns -get-property <name>:<key>
diode bns -delete-property <name>:<key>

Set a gateway prefix on the BNS name acme:

diode bns -set-property acme:PX:division1=0x123229542c4afe8cd39da33f81bf698d57d3cb2a

Read it back:

diode bns -get-property acme:PX:division1

Remove it:

diode bns -delete-property acme:PX:division1

-set-property and -delete-property require the Diode client to own <name>. They write the Diode L1 BNS contract and wait for the next block, the same as -register. -set-property replaces an existing key. -get-property reads the same chain order the gateway uses.

PX: is only the gateway convention. Any other key is stored and read with the same commands, and the gateway ignores it.

Gateway hostnames

For a custom domain, the registrable label is the BNS zone. Labels in front of that zone are PX: properties on the zone. To point the domain itself at the gateway, see Configure custom domain name.

A shorter key covers every name to its left unless a longer key is set. PX:division1 answers both division1.acme.com and west.division1.acme.com. The value is one 0x address. An empty value is treated as unset.

The leftmost label may still carry a mode and a port. Those sit outside the property key.

r-west-8080.division1.acme.com

That hostname looks up PX:west.division1, then connects to port 8080 in mode r.

Run the gateway with on-demand certificates:

diode gateway -httpd_port 80 -httpsd_port 443 -secure -edge_acme -edge_acme_email ops@acme.com -certpath ./fullchain.pem -privpath ./privkey.pem

-edge_acme requests a certificate for the hostname the browser used. Issuance requires:

• the gateway is reachable on port 443
• the zone BNS name resolves (acme for division1.acme.com)
• the hostname has at most three dots

west.division1.acme.com can be issued. west.division1.acme.co.uk cannot. A DNS record for *.acme.com covers one label, such as division1.acme.com. west.division1.acme.com needs its own record, or a record for *.division1.acme.com.