EMCDNS AND NVS


NVS (Name-Value Storage) and DNS support in Emercoin

Please note this document may be subject to change especially around the release of Emercoin version 0.3.0.

Starting with version 0.3.0, Emercoin provides a new service: storing name->value pairs in its blockchain. The inital idea has been borrowed from the NameCoin cryptocurrency. However, where NameCoin is mostly focused on supporting decentralized domain zone *.bit in their extension, Emercoin provides a universal service to store and maintain name->value pairs without imposing narrow specialization. Of course, Emercoin supports distributed alternative DNS service too. Moreover, each Emercoin wallet contains a built-in simple DNS server, supporting the standard RFC1034 UDP DNS protocol.


General comparison

Among the myriad cryptocurrencies only two of them officially support storing additional data in a blockchain. These are, of course, NameCoin and Emercoin. In both cryptocurrencies additional data is organized in same way, by a set of pairs:

  • name - search key (label) for stored data
  • value - data itself
A short comparison of name-subsystem follows (prices in respective coins):

Currency Type MAX_NAME_LENGTH MAX_VALUE_LENGTH Lease time Create Update Delete
NameCoin PoW 255 1023 ~200 days 0.01 0.00 N/A
Emercoin PoS/PoW 512 20*1024 variable* 0.17* 0.12* 0.00
* Price is variable, and computed by formula:
p = sqrt(0.01 * R * y) + s / 128
  Where:
    R = Current Proof-of-work reward, in cents.
    y = Lease time, in years. Available by 1 day fractions.
	The cost of creating a new name is equal to the cost of a 1 year lease.
    s = key_size + value_size, in bytes. Division is integer, so for 
        entries, less than 128 bytes, this price part is zero.

For example, 9/30/2014 PoW reward was 140EMC, or 14000EMC cents (EMc).
If you want to lease name (length 100 bytes) for 1 year, you pay:

p = sqrt(0.01 * 14000 * (1[create new name] + 1[one year lease])) + (floor)(100 / 128) = 17EMc = 0.17EMC.
All fees are "burnt" and become unrecoverable (transaction output is less than input).

Emercoin allocates 20kB for value, enough to fit public keys for most modern cryptographic applications. We consider a cryptocurrency blockchain to be an extremely reliable place to publish and maintain public keys for many cryptographic applications such as SSH/SSL certificates. Like regular payment transactions, stored name->value pairs also get confirmations during block generation, and are virtually immune to being altered in a Man-In-the-Middle attack.

Since the blockchain is a trusted data store protected from unauthorized modification it is a great foundation for the deployment of cryptographic Public Key Infrastructure (PKI), proof-of-ownership timestamps or other distributed services.


Managing names

The blockchain of Emercoin is able to store name->value pairs without any restrictions in the data format. However, for standardization purposes we recommend the following format to store names:

service_abbr:unique_key
For example:
dns:emercoin.com
All DNS records must be in lowercase.

Each name->value pair has its owner. Each owner is specified by the Emercoin payment address stored together with the pair. Only the owner of the payment address is able to modify or delete the pair, or transfer ownership to another address. When a new pair is created, a new payment address for the pair is created in the local wallet.

For service purposes we recommend using the following abbreviations:


Service abbreviationService description
dns*Built-in aggregated DNS record
sshSSH public key
gpgGNU PGP public key
kxRFC2230 public key
sslSSL Certificate
blsBLS digital signature public key
ttsTrusted Timestamp
swiftBank's branch info for SWIFT transfers
dpoDigital Proof of Ownership
magnet**BitTorrent magnet links

* This is a special service abbreviation used by Emercoin built-in DNS server.

** Service to store BitTorrent magnet links, useful to share files. Proposed format:
"name" : "magnet:Emercoin 0.3.2 for Linux - packed as tar.gz, original file from emercoin.com",
"value" : "magnet:?xt=urn:btih:dff183bcac72a628fcac88ac1c85c239b806fd5e&dn=emercoin-0.3.2-linux.tar.gz"

You can find other possible service abbreviations for your applications among recommended DNS record types.

Managing names can be performed by the Emercoin wallet GUI, console commands in debug window, or by JSON API interface. Emercoin's operator set was inspired by NameCoin API, but it is different. Below is the list of the operators and parameters (parameters in square brackets [ ] are optional).


  • name_new <name> <value> <days>
    This operator creates a name->value pair and publishes it into the blockchain. The 3rd parameter <days> specifies lease time in days.
  • name_update <name> <value> <days> [<toaddress>]
    This operator:
    • updates the value for an existing name
    • adds lease days
    • transfers name ownership to another Emercoin address
  • name_delete <name>
    This operator deletes a name->value pait from the blockchain. There is no refund for unused lease time.
  • name_show <name>*
    This operator retrieves a name->value pair and transaction info for specified <name>.
  • name_list [<name>]*
    This operator lists all matching pairs belonging to the current wallet and those that were transferred in the past. If <name> is not specified, then it lists all names.
  • name_scan [<start-name>] [<max-returned>]*
    This operator lists all pairs existing in the blockchain. Parameter <start-name> is to skip all names in the list which are located above the specified name, useful to download the list in chunks.
  • sendtoname <name> <amount> [comment] [comment-to]*
    Send payment to the address associated with the specified <name>. Amount is rounded to cents. <comment> and <comment-to> will be stored in the local wallet, not in the blockchain. For instance, by using this operator you can send a donation to [email protected] project.
  • name_filter [regexp] [<maxage=36000> [from=0] [nb=0] [stat]
    Not implemented yet, returns an empty list.

* parameters and behavior are the same as in NameCoin.

To create a name alias for payment address, just create a pair with a specified unique name and any value. A new associated payment address will be created in your wallet automatically. We recommend writing a text description as the value. All payments to that name will be sent to the appropriate payment address, to which the name is registered.

Example:
Name="[email protected]"
Value="Donation to support participants of [email protected] project from Stanford University"

DNS subsystem

As mentioned above, Emercoin is able to store in its blockchain special name->value pairs containing DNS records. Because of the nature of distributed blockchains these records are completely decentralized and uncensored and cannot be altered, revoked or suspended by any authority. Only the record's owner can modify it or transfer it to another owner. The record's owner is specified by the payment address.

Technically, Emercoin DNS can support virtually any DNS-zone. However, for seamless integration into a standard DNS tree, and to prevent collisions with existing DNS-zones, we currently recommend creating Emercoin DNS records only in the zones: *.emc, *.coin, *.lib, *.bazar.

These DNS records could be easily retrieved from any Emercoin wallet, by abovementioned JSON RPC API, or by standard DNS protocol RFC1034, using built-in DNS server subsystem.

To activate this subsystem you can specify two optional parameters in the emercoin.conf config file, emcdns and emcdnsport:

emcdns=1 # Run DNS server. Default is 0 (don't run)
emcdnsport=NNN # Port for DNS, default is 5335

OpenNIC peering

Emercoin has entered a peering agreement with the OpenNIC community which will allow domains registered in Emercoin's blockchain to be accessible to all users of OpenNIC DNS. Once peering is in place, Emercoin domain zones will be accessible by changing your DNS resolver address to your nearest OpenNIC server. This can be achieved by visiting opennicproject.org and following their guides for setting your DNS resolver. This is the most simple and convenient method to access Emercoin DNS zones.

Integration into a regular DNS tree

To integrate Emercoin DNS server into a regular DNS tree, you can use full-service DNS or caching DNS. The standard Windows DNS-client is unable to perform this work, so you should use an additional DNS proxy server to do it. Below we will show some examples.


Single PC, Acrylic DNS proxy

Running the Emercoin wallet and everything else on a single PC is the most common case. For this we recommend to install the lightweight Acrylic DNS proxy onto your PC. Because of integrating namezones, it will improve performance of your PC by resolving DNS requests more quickly with the local cache, decreasing latencies with browsing or any other Internet activity.

For installation and initial configuration in Windows, see guide at Acrylic website. After installation you should configure Acrylic to integrate Emercoin domain zones. A config file example is available online. To configure, you should forward all requests to Emercoin zones (*.emc, *.coin, *.lib, *.bazar) to the local Emercoin wallet, and all requests to other zones to the default DNS provider. This can be configured in the Acrylic config file as follows:

; Forward to primary (default) DNS server anything but EMC-zones
PrimaryServerHostNameAffinityMask=^*.emc;^*.coin;^*.lib;^*.bazar;*
PrimaryServerAddress=DNS_of_your_provider or any public DNS, for example: 8.8.4.4
PrimaryServerPort=53

; Forward to EMC wallet requests for EMC-zones only
SecondaryServerHostNameAffinityMask=*.emc;*.coin;*.lib;*.bazar
SecondaryServerAddress=127.0.0.1
SecondaryServerPort=5335

Alternately, you can download this AcrylicConfiguration.ini file, pre-configured to use OpenDNS as primary & secondary DNS-provider (for regular DNS-tree), and local Emercoin wallet as the ternary provider, for domain zones *.emc, *.coin, *.lib, *.bazar.
Default path to this file is: C:\Program Files (x86)\Acrylic DNS Proxy\

The Emercoin team also provides Acrylic package for download, already pre-configured for Emercoin DNS.


Single PC, BIND DNS proxy

Instead of installing a DNS proxy, you also have the option to install a full service DNS server. Fortunately, the full DNS server "BIND" is available for Windows, and is free. You can find many tutorials on the internet that show how to install BIND onto Windows. For example, see this manual.

After installation you should tell BIND to forward EMC-zones to the local Emercoin wallet by adding to the BIND configuration file named.conf as follows:

zone "emc" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5335; // Local Emercoin wallet
 };
};
zone "coin" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5335; // Local Emercoin wallet
 };
};
zone "lib" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5335; // Local Emercoin wallet
 };
};
zone "bazar" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5335; // Local Emercoin wallet
 };
};

Local network, BIND DNS proxy

If you have a server in your LAN, it is a good idea to install BIND onto your server, and in the PC network configuration point the primary DNS address to your BIND server. On the server you can run a headless Emercoin wallet to which BIND will forward requests to the appropriate zones. In this case configuration of BIND is exactly the same as above.

Also you can run the Emercoin wallet on any PC of your LAN, instead of on the BIND server. If so, you should change the forwarding address from 127.0.0.1 to the IP address of that PC. Of course that PC should have a static LAN IP.


Local network, DNSMASQ proxy

Modern routers usually contain a built-in proxy DNS in their firmware. Usually this is DNSMASQ. And some firmware like DD-WRT (as well as other WRTs) allow you to configure a built-in DNS proxy. See DD-WRT configuration manual here.

In this case the wallet should be run on a PC with a static IP and DNSMASQ from the router would send DNS requests to that PC. Following are examples of the configuration lines needed to add into dnsmasq.conf. In this example the PC has the LAN IP address 192.168.1.53.

--server=/emc/192.168.1.53#5335
--server=/coin/192.168.1.53#5335
--server=/lib/192.168.1.53#5335
--server=/bazar/192.168.1.53#5335

Public Internet, direct gateway

The ability also exists to make a public gateway from a regular DNS tree into the distributed Emercoin DNS subsystem. In this case, you can lease any public domain or subdomain, and point the NS records for this domain to a machine that is running the Emercoin wallet with an active DNS server on port 53 (see in the next paragraph for how to define the port). Once you do this, all regular NS requests to that domain will be resolved by the DNS server, and answers will be retrieved from the NVS database in the Emercoin wallet.

For example, we have set up a new domain emergate.net (Emercoin Gateway Network). When you click http://emer.coin.emergate.net, your name request is resolved by the Emercoin wallet, and you go directly to emer.coin in the EMC-supported domain zone. Analogously, a link to our EMC<->USD exchange service also works: http://exchange.emc.emergate.net.

Thus, if you register any name with Emercoin DNS, the name would be resolved by any Emercoin DNS gateway - emergate.net, or any other. And your site site.coin will be available through any such gateway, by links such as site.coin.emergate.net, or site.coin.another.com.

To configure a new domain as a public Emercoin DNS gateway, you need to specify DNS servers as authoritative for your zone (domain). For domain emergate.net, we specified two Name Servers (NS), authoritative for this domain with our domain registrar:

Name Server: SEED1.EMERGATE.NET
Name Server: SEED2.EMERGATE.NET
You can check this info using whois.

On each of these nameservers runs an Emercoin wallet with an active DNS server which serves the gateway and local zone for emergate.net. DNS specific config parameters for the file emercoin.conf are as follows:

If you are only running a DNS gateway for your local computer (with Acrylic or BIND) or for your LAN, it is enough to specify just a single parameter in emercoin.conf:

# enable emc dns
emcdns=1
This will activate Emercoin's DNS server and run it on default port 5335, as allowed for DNS forwarding by DNS proxies (acrylic/BIND/dnsmasq/whatever).

To run as a public DNS gateway, you need to specify some additional parameters:

# Gateway suffix. This suffix will be ignored when a request is passed to the internal gateway.
# Requests for other domain suffixes will be ignored.
emcdnssuffix=.emergate.net

# NS Server port 53 is the default NS port and must be used if the server is public and "not forward only".
emcdnsport=53

# Filter for allowed zones. Protection for "cool hackers", who try to lookup any external domains through our server
# or attack someone else by DNS amplification mechanism. Currently, only the four EMC-zones are allowed.
emcdnsallowed=.coin|.emc|.lib|.bazar

# Optional path for a file that contains names in the local gateway's NS zone (like www.emergate.net).
# Must be full path. Example:
emcdnslocalcf=/usr/share/emercoin/emcdnslocal.conf

The local config file (emcdnslocal.conf above) contains pairs in the format "name=value"; an empty name assumes "gateway as is", i.e. the local file for emergate.net is as follows:

# This is local zone config
# For built-in Emercoin DNS

=A=192.241.241.153|TXT=Emercoin site
www=A=192.241.241.153|TXT=Emercoin www-site

The format for these records is explained in the next section.

Create and maintain a DNS record

Emercoin's built-in DNS-server supports the following DNS record types:


Record abbreviationService description
AIP V4 address
AAAAIP V6 address
NSName server record
PTRPointer record
CNAMECanonical name record
MXMail exchange record
TXTFree form text message
SDSubdomains (see below)

SOA, WKS, and SRV records are not supported.

To insert a full DNS record into the Emercoin blockchain, create a pair as follows:

Name="dns:your_name_here"
Value="List of NS-records"

For example:

Name="dns:example.coin"
Value="A=192.168.0.123,127.0.0.1|AAAA=2607:f8b0:4004:806::1001|NS=ns1.google.com|TTL=4001"

In this example the domain example.coin is specified by two A-records (192.168.0.123 and 127.0.0.1), one AAAA-record (2607:f8b0:4004:806::1001) and one NS-record (ns1.google.com). The records are separated by the default separator vertical bar (pipe) "|". If necessary, you can redefine the separator by prefixing the line with "~[NEW_SEPARATOR_CHAR]". For example, if you wish to use "#" as a separator you can assign it as follows:

Value="~#A=192.168.0.123,127.0.0.1#AAAA=2607:f8b0:4004:806::1001#NS=ns1.google.com#TTL=4001"

Note, if you use the whitespace (symbol " ") as a separator, you will not be able use it inside the fields. Therefore, you should select an appropriate symbol as a separator for your records.

As described above, each record can contain multiple values. In the provided example, the A-record contains two values, separated by a comma. You can also redefine the value separator with "~[NEW_SEPARATOR_CHAR]". The following example demonstrates how to redefine the separator two times: "/" as record separator, and "*" as value separators for multiple TXT-records:

~/TXT=~*This is text, Hello!*2nd text/MX=gmail.com:33,mx.microsoft.com:66/CNAME=emc.cc.st/A=192.168.0.100,127.0.0.1"

In this example we've demonstrated the usage of field MX. The value of MX contains a mail exchanger reference, colon and priority. If priority is omitted, the default value is 1. Also, intentionally omitted in the last example is a record for "TTL". The default value for TTL is 24 hours.

In summary:
Only DNS record owners can manage their records: change values, lease times, or delete them. Also, only the owner can transfer ownership to another EMC address. These actions can be performed in the wallet GUI, console command name_update, or by making a similar JSON API request.

Subdomains

A general challenge with distributed DNS is that anyone can allocate any unique name, opening up the possibility for someone to register a subdomain for a domain that they do not own. To remedy this situation, Emercoin DNS has special ways to manage subdomains:

  • A subdomain (SD) record in the DNS parent's NVS value, permits lookup and resolution of the subdomain directly within the Emercoin DNS subsystem e.g. "SD=www,ftp,mx".

  • A nameserver (NS) record in the DNS parent's NVS value, allows reference to external nameserver(s) managed by the domain owner, to provide authoritative lookup and resolution of the subdomain external to Emercoin DNS e.g. "NS=ns.example.com"

Subdomain rules are applied as follows, recursively to all third-level subdomains and deeper:

  1. First, check SD record in the parent's DNS value for reference to the requested subdomain. If reference is found then look up the subdomain within the Emercoin NVS subsystem.
  2. Next, check for nameserver (NS) record in the parent's DNS value. If found, generate reference to external nameserver.
  3. If no resolution results from SD or NS records, return as per parent domain (i.e. ignore subdomain prefix).

NOTE: When utilizing external nameservers, please take care with correct name resolution in those servers, including any gateway-suffixes, e.g. emergate.net.


Example 1 - parent contains SD and NS records

  1. dns:example.coin -> A=1.2.3.4|SD=www,gopher|NS=ns.example.com
  2. dns:www.example.coin -> A=5.6.7.8

In this case, subdomains will resolve as follows:

  • example.coin will be resolved by record [1], and return A=1.2.3.4
  • www.example.coin will be approved by record [1], resolved by record [2] and return A=5.6.7.8
  • gopher.example.coin will be approved by record [1], and not resolved, since NVS does not contain an appropriate DNS record. This will return NXDOMAIN.
  • mail.example.coin will not be approved by record [1], but the NS record will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.

Thus a single record [1] supports flexible hybrid resolving:

  • www is resolved by Emercoin NVS.
  • gopher is blocked.
  • all others are resolved by delegated NS=ns.example.com.

Example 2 - parent contains SD record only

  1. dns:example.coin -> A=1.2.3.4|SD=www,gopher
  2. dns:www.example.coin -> A=5.6.7.8

In this case, subdomains will resolve as follows:

  • example.coin will be resolved by record [1], and return A=1.2.3.4
  • www.example.coin will be approved by record [1], resolved by record [2] and return A=5.6.7.8
  • gopher.example.coin will be approved by record [1], and not resolved, since NVS does not contain an appropriate DNS record. This will return NXDOMAIN.
  • mail.example.coin will not be approved by record [1], and (because of missing NS record) prefix "mail" will be ignored and resolve the same as example.coin.

Example 3 - parent contains NS record only

  1. dns:example.coin -> A=1.2.3.4|NS=ns.example.com
  2. dns:www.example.coin -> A=5.6.7.8

In this case, subdomains will resolve as follows:

  • example.coin will be resolved by record [1], and return A=1.2.3.4
  • www.example.coin will not be approved by record [1], and will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.
  • Record [2] will be ignored, and will not participate in DNS resolution.
  • mail.example.coin will not be approved by record [1], and will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.

Example 4 - parent contains no references to subdomain

  1. dns:example.coin -> "A=1.2.3.4"
  2. dns:mx.example.coin -> "A=5.6.7.8"

In this case, subdomains will resolve as follows:

  • example.coin -> "A=1.2.3.4"
  • mx.example.coin -> "A=1.2.3.4"
  • www.example.coin -> "A=1.2.3.4"
  • upload.ftp.example.coin -> "A=1.2.3.4"

Because record [1] does not contain any SD or NS records, all subdomains will be resolved to the "parent domain" example.coin. Record [2] will be ignored, and will not participate in DNS resolution.

Virtual webhosts (vhosts)

When you run virtual hosts, you will be required to modify your web server's config to correctly distinguish your hostname with as many possible gateway-suffixes as you wish (or without suffix if name resolved by LAN or locally).

This is easy to do by creating a vname-alias with an asterisk "*" as the suffix. The following example shows the appropriate apache web server config for the virtual server exchange.emc. Note the line "ServerAlias".

<VirtualHost *:80>
  ServerAdmin [email protected]
  DocumentRoot "/var/www/exchange.emc/html"
  ServerName emc.cc.st
  ServerAlias exchange.emc*
  ErrorLog  "/var/log/exchange.emc-error_log"
  CustomLog "/var/log/exchange.emc-access_log" common
  ScriptAlias /cgi-bin/ "/usr/local/libexec/cgi-bin/"
</VirtualHost>