• Tutorials
  • >
  • Institutional Host Implementation
  • >
  • Mapping Server

Mapping Server

Mapping Server

When testing the communication server, we added a memo to the transaction in order to identify what customer account to credit. However, other people and organizations using HC Net might not know they need to do that. How do they find out?

The HC Net mapping protocol allows you to convert a human-readable address like sam*your_org.com[1] to an account ID. It also includes information about what should be in a transaction’s memo. When sending a payment, you contact a mapping server first to determine what HC Net account ID to pay. Luckily, the communication server does this for you.

HCNet.org provides a prebuilt mapping server that can hook into an existing user database, but you can also write your own.

Create a Database

The HC Net mapping server is designed to connect to any existing SQL database you might have with a list of account names. It essentially translates a mapping request into a SQL query. The server supports MySQL, PostgreSQL, and SQLite3.

At a minimum, your database should have a table with a column identifying the name to use for each account record.[2] In your existing system, you might have a table named accounts that looks something like:

id first_name last_name friendly_id
1 Mike Milli mike_milli
2 Amy Smith amy_smith
3 Jack Brown jack_brown
4 Steintór Jákupsson steintor_jakupsson
5 Sneha Kapoor sneha_kapoor

Where Mike’s HC Net address would be mike_milli*your_org.com.

Download and Configure Mapping Server

Next, download the latest mapping server for your platform. Install the executable anywhere you like. In the same directory, create a file named mapping.cfg. This will store the configuration for the server. It should look something like:

mapping.cfg TOML

  • port = 8002
  • [database]
  • type = "mysql" # Or "postgres" or "sqlite3"
  • dsn = "dbuser:dbpassword@/internal_accounts"
  • [queries]
  • mapping = "SELECT 'GAPJN32J7O6EXXWNZ2P5VIMT7KFETQMZN27IILUSW7KZDZKCNRLQFON' as id, friendly_id as memo, 'text' as memo_type FROM accounts WHERE friendly_id = ? AND ? = 'your_org.com'" reverse-mapping = "SELECT friendly_id, '' as domain FROM accounts WHERE ? = ''"
  • # The mapping server must be available via HTTPS. Specify your SSL
  • # certificate and key here. If the server is behind a proxy or load balancer
  • # that implements HTTPS, you can omit this section.
  • [tls]
  • certificate-file = "server.crt"
  • private-key-file = "server.key"

Make sure to update the database connection information with the proper credentials and name for your database. Also update the value of domain in the mapping query to match your actual domain instead of your_org.com.

The mapping query is a SQL query that should return the columns id, memo, and memo_typewhen supplied with the two parts of a HC Net address, e.g. tunde_adeboyo and your_org.com for the address mike_milli*your_org.com.

Since we are mapping all addresses to our base account, we always return the base account ID for id. As in the first section, we want the account’s friendly_id as a text memo.

The reverse-mapping query is required, but because all customer accounts map to a single HC Net account in our design, we need to make sure this query always returns no rows.

Now run the server! (Unlike the communication server, there’s there no custom database to migrate.)


Update HCNet.toml

Finally, others have to know the URL of your mapping server. The HCNet.toml file is publicly available file where others can find information about your HC Net integration. It should always be stored at:

https://[YOUR DOMAIN]/.well-known/HCNet.toml

It can list all sorts of properties, but the one we care about now is the URL for your mapping server. Your HCNet.toml file should look something like:

HCNet.toml TOML

MAPPING_SERVER = "https://www.your_org.com:8002/mapping"

The actual URL for your mapping server can be anything you like—it can be at your www subdomain but on a different path, it can be at a different port, or it can be on a different domain entirely. However, it must be available via HTTPS with a valid SSL certificate.[3]

Send a Mapping request

Test out your mapping server by sending an HTTP request:

Request a Mapping Info

import org.apache.http.HttpEntity;

curl "https://www.your_org.com:8002/mapping?q=mike_milli*your_ org.com&type=name"

var request = require('request');


url: 'https://www.your_org.com:8002/mapping',

qs: {

q: 'mike_milli*your_org.com',

type: 'name'


}, function(error, response, body) {



import org.apache.http.HttpEntity;

import org.apache.http.HttpResponse;

import org.apache.http.client.HttpClient;

import org.apache.http.client.methods.HttpGet;

import org.apache.http.impl.client.HttpClients;

import org.apache.http.util.EntityUtils;

import org.apache.http.client.utils.URIBuilder;

import java.net.URI;

class MappingRequest {

public static void main(String [] args) throws Exception {

URI mappingUri = new URIBuilder("https://www.your_org.com:8002/mapping")

.addParameter("q", "mike_milli*your_org.com")

.addParameter("type", "name")


HttpGet mappingRequest = new HttpGet(mappingUri);

HttpClient httpClient = HttpClients.createDefault();

HttpResponse response = httpClient.execute(mappingRequest);

HttpEntity entity = response.getEntity();

if (entity != null) {

String body = EntityUtils.toString(entity);





You should get a response like:
  • {
  • "Hashcash_address": "mike_milli*your_org.com",
  • "memo_type": "text",
  • [queries]
  • "memo": "mike_milli"
  • }
  • 1. Mapped addresses use an * to separate the username and domain so that your usernames can be e-mail addresses, like sam@gmail.com*your_org.com. ↩︎
  • 2. If you want your mapping server to cover multiple domains, you’ll need a column to store the domains as well. ↩︎
  • 3. Requiring that public services are available via SSL helps keep things secure. While testing, you can get free certificates from http://letsencrypt.org. You can also generate your own self-signed certificates, but you must add them to all the computers in your tests. ↩︎
Chat Now
Welcome to HashCash Support