How to register .bit domains

Using a software wallet with the name management tab is the easiest way to register keys on the blockchain. Alternatively, you can register your key/value pair using the implemented console of the wallet. Also an external command line interface may be used. Please note that you can only create a limited amount of name transactions at a time, else you'll get an error notification of unconfirmed wallet funds. To increase the possible numbers of transactions per block, please activate the option "spend unconfirmed change outputs" in your wallet settings. Depending on the height of your funds and the numbers of your used receiving addresses you may issue up to 25 transactions per block until your transaction will be rejected. In case of rejection, your wallet balance will be displayed as zero: Please don't panic, your balance will be displayed again with the next block!

Technically, blockchain domain records are a type of Non-Fungible Tokens (NFTs). Each record on the blockchain is defined by a unique key, in the case of a .bit domain, the namespace d/ followed by the (second-level) domain name. Furthermore, it's assigned to a unique Namecoin address, no matter, if the record is expired or not. For cryptographic verification of the ownership of a domain, please see the corresponding section Verifying Ownership.

New name operation

For registering manually you need to create a new name operation at first. To do this, please open the console (in most of the wallets: ➞ Window, ➞ Console ) and enter the command for each name, where the prefix d/ defines the .bit domain namespace:

name_new "d/yourname"

Please don't close the console after the name_new operation, at least note the output from that operation, which contains the transaction ID (TxID) of 64 alphanumeric characters and a second shorter string of 40 alphanumeric characters, which is a random string, also called salt. These values will be needed in the next step when registering over the console or an command line interface.

Domain specifications

The .bit TLD is assigned to the d/ namespace and has been Namecoin's default TLD. However, additional namespaces have been introduced so that Namecoin offers a total of 50 TLDs (see section Namespaces). Please note that Namecoin has adopted ICANN's 63-character limitation for domain names (excluding the .bit TDL etc.). Therefore our browser add-ons will ignore domain records exceeding this limitation. However, Internationalized Domain Names (IDNs), e.g. with diacritics such as ä, ö and ü or Chinese and Russian characters, are possible, but have to be converted into the corresponding Punycode at first, which needs to be taken for the domain record on the blockchain. Additionally, you may secure the original name as well, but any browser will convert it automatically to Punycode anyway when trying to resolve the domain. For the conversion, even for creating emoji domains, you may take our IDN/Punycode converter. Uppercase names will be converted to lowercase:

The standard ICANN domain specifications apply for the letter case of the domain records as ell. Since every browser automatically converts the domain to lowercase, combinations with uppercase letters are technically possible, but just useless. So for case-sensitive languages, valid records contain only lowercase letters.

First update operation

After a necessarily hard coded time buffer of at least 12 blocks (about two hours), the first update operation needs to be generated, providing the value of the newly registered key. Using the name management tab, your wallet will wait automatically for 12 blocks until sending the first update.

The separation of the encrypted new name operation and the clear text first update was introduced to prevent domain grabbers from trying to register the same domain at the same block once you broadcasted your transaction publicly to the miner's memory pool. Sometimes it takes more than one block to distribute a transaction to the entire peer-to-peer network. From time to time even parallel trees of the blockchain are mined until one tree gets discarded as so-called orphan blocks. The longest blockchain tree ever discarded appeared on the Bitcoin parent chain on July 4, 2015, and contained seven orphaned blocks.

The time buffer of 12 blocks ensures that your previous new name operation got broadcasted with at least six confirmations of the correct blocks across the global p2p networks of the native chain as well as of the parent chain, even if some orphan blocks have been discarded in the meantime. Furthermore, the time buffer ensures that also your subsequent first update operation, which might get affected from network delays and truncated blockchain trees as well, gets a time lead of at least six blocks against a potential new name transaction of a domain grabber issued at the time of your first update operation.

Server IP address

The command for the first update should provide a JSON string containing your server IP (here as placeholder 1.2.3.4), which will be valid for all sub-domains as well. Please note that all quotes within the JSON value have to be masked with the backslash \ so that they will be interpreted as part of the value to be added:

name_firstupdate "d/yourname" salt TxID "{\"ip\":\"1.2.3.4\"}"

This command leads to the following value on-chain, which would have to be taken without backslashes as well, if you add this value via the implemented name management tab of the software wallets:

{"ip":"1.2.3.4"}

Separate sub-domain records are not used on the blockchain. The additional and optional "map" value defines a separate IP for your sub-domains, which may be in the easiest case a wildcard entry:

name_firstupdate "d/yourname" salt TxID "{\"ip\":\"1.2.3.4\","map":{\"*\":{\"ip\":\"1.2.3.5\"}}}"

If you use the name management tab of your wallet, you only need to enter the JSON value itself with the additional sub-domain entry, and again without backslashes:

{"ip":"1.2.3.4","map":{"*":{"ip":"1.2.3.5"}}}

When creating the JSON values, it doesn't matter for our browser add-ons whether you write the value with space after the colon or not. So your value might look as well:

{"ip": "1.2.3.4"}

Name Server

Instead of using an IP address, you can define a name server that resolves your server's IP. However, please note that .bit website owners are encouraged not to choose this option, as our browser add-ons require an additional external lookup to resolve your IP, which takes an additional significant loading time. Escaping the double quotes with the backslash, the command looks like this:

name_firstupdate "d/yourname" salt TxID "{\"ns\": [\"ns0.yourserver.com\", \"ns1.yourserver.com\"]}"

Using the name management tab just take the value:

{"ns": ["ns0.yourserver.com", "ns1.yourserver.com"]}

If you don't have the domain name of your name-server you can take the name-server's IP address instead:

name_firstupdate "d/yourname" salt TxID "{\"ns\":\"1.2.3.4\"}"

Using the name management tab your value is just:

{"ns":"1.2.3.4"}

Again a space after the colon doesn't matter.

Forward to Alias

Instead of defining the server's IP address or a name server, you can also create an alias record to which the web request will be forwarded. This is primarily designed to be used with an ICANN domain such as .com, .net and .org as target domain. The regular DNS of your Internet Service Provider (or in case your customized DNS system settings) is then taken for DNS resolution. A call to the blockchain domain is forwarded to the server hosting the target domain. The blockchain domain name needs to be configured as website binding on the target server, otherwise the 404 error “The requested resource was not found” will be thrown. The firstupdate command looks like:

name_firstupdate "d/yourname" salt TxID "{\"alias\": \"yourwebsite.com\"}"

Using the name management tab the value is just:

{"alias":"yourwebsite.com"}

Like before a space after the colon can be used as desired. Please note that our browser add-ons only resolve one consecutive redirect to another Namecoin blockchain domain, otherwise a misconfiguration might result in an indefinite loop of redirects.

Redirect to external URL

While the target domain for a domain forwarding described above is written without HTTP-prefix to the blockchain, also a classical redirect to any external ressource may be configurerd. It is thus possible to point your domain name resp. ID record directly to your social media profile, blog etc. No explicit DNS configuration is needed. In comparison to the forwarding described above, the redirect to external won't request the blockchain domain at the target server. Instead, the browser tab will be reloaded with the target URL by our add-on. The redirect to an external URL is being identified by its HTTP/HTTPS prefix. A name update of the example domain elonmusk.btc for a redirect to the connected Twitter profile will look like:

name_update "b/elonmusk" "{\"alias\": \"https://twitter.com/elonmusk\"}"

Again, the value to be added via the name management tab is just:

{"alias":"https://twitter.com/elonmusk"}

Domain delegation

If you have to update your key/value pair regularly or you want to give a third party the possibility to modify the IP settings without touching the main record itself, you can create a domain delegation as shown in the steps before:

name_new "dd/yourname"

name_firstupdate "d/yourname" salt TxID "{\"import\":\"dd/yourname\"}"

Therefore you need to create an additional record on the blockchain with the key dd/yourname, which can be updated through the normal update operations defining the IP settings. The data from the delegated record is then being imported.

Name updates

As records on the Namecoin blockchain expire after 36,000 blocks you need to renew your names in time. It is strongly recommended to renew at least 500 blocks before expiration, which is around three days. In case of any unexpected circumstances, e.g. missing funds, you have time to react! If you're not using the name management tab your update command is quite simple:

name_update "d/yourname", "{Your JSON-value}"

Please make sure to mask the double quotes of your JSON value with the backslash again when using this command. Using the name management tab just double click the name, modify the value if needed, and press enter or the ok button.

Transfer names

To transfer a record to another wallet, e.g. if you have sold a domain or NFT, you can use the right-click menu of the Electrum wallet or the name tab Core version 0.13.99. Alternatively, you can use the following command in the implemented console of Core v. 0.13.99:

name_update "d/yourname", "{Your JSON-value}" "your destination address"

If you are using Core wallet v. 0.19 and above, the destination address needs to be specified within a JSON object enclosed in curly brackets. The quotes inside this object have to be escaped with the backslash, otherwise they would be considered data separators of the command itself and not of the JSON object. For UFT-8 entries that contain special characters such as ℕ or others, the UTF-8 declaration is required, so the whole command for the implemented console is:

name_update "d/yourname" "{Your JSON-value}" "{\"nameEncoding\": \"utf8\", \"valueEncoding\": \"utf8\", \"destAddress\": \"your destination address\"}"

Command line interface and CURL

Please note when using an external command line interface like Microsoft Windows CMD, you need to set up the Remote Procedure Call (RPC) at first when starting the software wallet. The wallet has to be started over the command line interface as well with the commands:

c:
cd C:\Program Files\Namecoin
namecoin-qt -server -rpcuser=YourUsername -rpcpassword=YourPassword -rpcport=8336 -rpcallowip=127.0.0.1

Your wallet will now accept RPC connections from your local host. If you want to connect from another computer within your network, additionally or alternatively, specify the internal IP like:

-rpcallowip=192.168.0.3

If you want to search or register entries with special characters like ℕ or emoticons with Core Wallet v. 0.19 and above, you need to start the wallet in UTF-8 mode as following:

c:
cd C:\Program Files\Namecoin
namecoin-qt -server -nameencoding=utf8 -valueencoding=utf8 -rpcuser=YourUsername -rpcpassword=YourPassword -rpcport=8336 -rpcallowip=127.0.0.1

The Core wallet v. 0.13.99 doesn't need or even provide this UTF-8 start option at all.

If you want to use the wallet as a blockchain explorer to search for TxIDs or historical values, you need to add the corresponding start parameters -namehistory and -txindex. Please note that switching to this mode requires downloading and re-indexing the entire blockchain, which will take several hours. Since during this time the wallet will be unusable, you should do this only once and then keep the startup process:

c:
cd C:\Program Files\Namecoin
namecoin-qt -server -namehistory -txindex -rpcuser=YourUsername -rpcpassword=YourPassword -rpcport=8336 -rpcallowip=127.0.0.1

Together with the UTF-8 start option for Core wallet v. 0.19 and higher the start parameters are:

c:
cd C:\Program Files\Namecoin
namecoin-qt -server -namehistory -txindex -nameencoding=utf8 -valueencoding=utf8 -rpcuser=YourUsername -rpcpassword=YourPassword -rpcport=8336 -rpcallowip=127.0.0.1

You can save these commands with Notepad as a batch file with the file extension .bat in order to start your wallet with one click. Please note further, that all quotes used within the data-value have to be escaped with backslash, else those quotes would be recognized as command line separators and your command would cause an parsing error. Your command e.g. for the new name operation using CURL will look like:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"name_new\",\"params\":[\"d/yourname\"]}" -H 'content-type:text/plain;' 127.0.0.1:8336

The console will show the result, containing the TxID and the random string, which are needed for the following first update operation:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"name_firstupdate\",\"params\":[\"d/yourname\",\"salt\", \"TxID\",\"YourValue\"]}" -H 'content-type:text/plain;' 127.0.0.1:8336

It is strongly recommended to submit the first update after you got already 12 confirmations for the new name operation, otherwise your wallet will be locked for these 12 blocks, making it inoperable for about two hours.

If you have encrypted your wallet, what is strongly recommended, you might unlock your wallet as well to avoid confirmation pop-ups when registering and renewing your names with the following additional CURL command:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"walletpassphrase\",\"params\":[\"YourWalletPassword\", 36000]}" -H 'content-type:text/plain;' 127.0.0.1:8336

This unlocks your wallet for ten hours (36,000 seconds), which is also helpful when using just the name management tab.

Searching for names

Searching for names on the blockchain can be done with our Basic Namecoin Explorer, or via the implemented console of the software wallet. Namecoin Core version 0.13.99 provides the name_filter command. Requesting e.g. the Namecoin domain bitcoin.bit looks like:

name_filter d/bitcoin 36000 0 10

Here, only active domains are queried (registered or renewed a maximum of 36000 blocks ago, maxage = 36000), starting with the first result (from = 0), with 10 results to be displayed (nb = 10). The corresponding command via CURL would be:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"name_filter\",\"params\":[\"d/bitcoin\", 36000, 0, 10]}" 127.0.0.1:8336

To show the next 10 results the command would be:

name_filter d/bitcoin 36000 10 10

Again only active domains are queried (maxage = 36000), starting with the eleventh result (from = 10), with 10 results to be displayed (nb = 10). The corresponding command via CURL would be:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"name_filter\",\"params\":[\"d/bitcoin\", 36000, 10, 10]}" 127.0.0.1:8336

To show expired records as well, the actual block height would have to be taken for the maxage parameter. You can just take value 1000000 to include all blocks ever mined:

name_filter d/b 1000000 0 10

The corresponding command via CURL would be:

curl --user YourUsername:YourPassword --data-binary "{\"jsonrpc\":\"1.0\",\"id\":\"curltest\",\"method\":\"name_filter\",\"params\":[\"d/b\", 1000000, 0, 10]}" 127.0.0.1:8336

Bech32 addresse​s will be shown as <nonstandard> in this version. The corresponding command for Namecoin Core v. 0.19 and above is name_scan, the request for showing 10 results would look like:

name_scan d/bitcoin 10

For the name_scan command optional parameters are available. Those options need to be formatted as JSON object in curly brackets, while the double quotes inside that object have to be escaped with the backslash. The request in the implemented console for showing 10 results of active domains only (with minConf=1 and maxConf=36000) would look like:

name_scan d/bitcoin 10 "{\"nameEncoding\": \"utf8\", \"valueEncoding\": \"utf8\", \"minConf\": 1, \"maxConf\": 36000, \"prefix\": \"d/\"}"

To show expired domains only, the minConf parameter is set to 36000, which would show also entries with 0 blocks to go available for registrations:

name_scan d/bitcoin 10 "{\"nameEncoding\": \"utf8\", \"valueEncoding\": \"utf8\", \"minConf\": 36000, \"prefix\": \"d/\"}"

Type help in all versions to get the available commands. If you are using the Electrum light wallet, the implemented console is a Python console. Your request has to be formatted as the call of a Python function, e.g. name_show("d/bitcoin"), type help() to get all commands.