Post

Home Domain

By XDBChain 5 min read

Introduction

The HOME_DOMAIN in the XDBChain blockchain provides a linkage between on-chain entities like nodes or validators and their off-chain web identity. By offering this link, the XDBChain network promotes transparency, trustworthiness, and easier identification of network participants.

Definition

HOME_DOMAIN: A domain associated with an entity on the XDBChain network, providing a means to verify the authenticity, identity, and additional information about that entity.

Usage

There are multiple contexts in which HOME_DOMAIN appears:

  1. NODE_HOME_DOMAIN: Represents the home domain of the node itself.
  2. [[HOME_DOMAINS]]: Specifies domains of known organizations or entities.
  3. Validators’ HOME_DOMAIN: Included in the [[VALIDATORS]] section, this ties a validator to a specific domain.

Configuration Examples

1

NODE_HOME_DOMAIN="livenet.mycompany.com"

This example sets the node’s home domain as “livenet.mycompany.com”.

1
2
3

[[HOME_DOMAINS]]
HOME_DOMAIN="livenet.mycompany.com"
QUALITY="MEDIUM"

This sets the known home domain “livenet.mycompany.com” with a quality ranking of “MEDIUM”.

In order to make obvious that XDBChain Network Node belongs to the domain following steps are required.

  1. Create file stellar.toml

  2. Create account for the keypair specified in config file of your node. For this, you need to make a transaction of type ‘Create account’ with destinaton

being public key of your node keypair and at list minimum ammount needed to be on the account balance (20XDB for new account. See minimum balance). As each transaction results in fee, fund enough to be able to accomplish next step.

  1. Make a transaction of type ‘Set options’ and set option ‘home_domain’ to the domain, where your stellar.toml file is located. For example ‘mycompany.com’

You may use Laboratory to build and submit transactions to the network.

Benefits

  • Trust & Verification: Users can visit the domain to verify information about the node or validator.
  • Quality Indication: The QUALITY tag, associated with [[HOME_DOMAINS]], provides a gauge of trustworthiness or reliability.

Retrieving Information from HOME_DOMAIN

Developers might want to fetch information hosted on a node’s home domain, such as a .toml file:

1
2
3
4
5
6
7
8

const fetch = require('node-fetch');

async function fetchHomeDomainInfo(domain) {
  const response = await fetch(`https://${domain}/.well-known/stellar.toml`);
  return response.text();
}

fetchHomeDomainInfo('livenet.mycompany.com').then(console.log);

Best Practices

  • Always serve information files, like stellar.toml, over HTTPS to ensure data integrity.
  • Regularly update information associated with the domain to reflect any changes in node policies, validator details, or network configurations.
  • Ensure the QUALITY tag truly reflects the reliability and reputation of the domain.

Example

Suppose we already have an account on XDBChain Livenet Network with private key SBUUJM5Q72XFGWF2SXHKJYTH5PBYQVHAWCPFRWB5AXNKGSBC4WM27CMZ and public key GDZDT2AZ65PALRS5COUBRRXPPESU3VB3PTP3BGRQSFI6JTCD6SKWMGWW and domain https://example.xdbchain.com. We started three validator nodes.

Node Configs

Node in Ireland

Config file of the first node (public key GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD and url https://ireland.example.xdbchain.com) contains following line:

1
2
3
4
5
6
7
8
9

# ...
NODE_SEED="SAVFRRS7BGFGVDJEZBDNSXNLP7S7XJEXRDXKDFA4ARQCXVF4H4ZC4MSL self"
[[HOME_DOMAINS]]
HOME_DOMAIN="example.xdbchain.com"
QUALITY="HIGH"
[HISTORY.local]
get="curl -sf https://example.xdbchain.com/livenet/germany/{0} -o {1}"
put="aws s3 cp {0} s3://livenet-mycompany-s3bucket/livenet/germany/{1}"
# ...

Node in France

Second node (public key GDSKRPNLL3HA7CUURJOEZJNJY43TGPTGMERKU7B4MJH2QDYIGULHFS62 and url https://france.example.xdbchain.com)

1
2
3
4
5
6
7
8
9

# ...
NODE_SEED="SARSCNPJ3ER7MMKMTDYFNE2DKZTRX7I5M6RJ6BSGFHMSJ5OC6VMPHIAZ self"
[[HOME_DOMAINS]]
HOME_DOMAIN="example.xdbchain.com"
QUALITY="HIGH"
[HISTORY.local]
get="curl -sf https://example.xdbchain.com/livenet/france/{0} -o {1}"
put="aws s3 cp {0} s3://livenet-mycompany-s3bucket/france/2/{1}"
# ...

Node in Germany

Third node (public key GAOWJ3P2OQGK56Y6V7UIQEPVOGOWFKOI5JJ5AGNNVRPC6BZLNUFDCANFand url https://germany.example.xdbchain.com)

1
2
3
4
5
6
7
8
9

# ...
NODE_SEED="SD2BKLRQ4ZMVWBBN3J4MSBESLGOZI7BQGUZCMUHZES3SUAKT77PK6SFN self"
[[HOME_DOMAINS]]
HOME_DOMAIN="example.xdbchain.com"
QUALITY="HIGH"
[HISTORY.local]
get="curl -sf https://example.xdbchain.com/livenet/3/{0} -o {1}"
put="aws s3 cp {0} s3://livenet-mycompany-s3bucket/livenet/3/{1}"
# ...

stellar.toml

After we ran our validator nodes, we need to upload stellar.toml to out domain at path <domain>./well-known/stellar.toml

In our case, home domain is example.xdbchain.com, so the stellar.toml file should be located at URL https://example.xdbchain.com/.well-known/stellar.toml command.

1

curl https://example.xdbchain.com/.well-known/stellar.toml

will result in the following content of the stellar.toml file

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

    VERSION="2.0.0"

    NETWORK_PASSPHRASE="LiveNet Global XDBChain Network ; February 2021"
    HORIZON_URL="https://horizon.example.xdbchain.com/"
    ACCOUNTS=[
        "GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD",
        "GDSKRPNLL3HA7CUURJOEZJNJY43TGPTGMERKU7B4MJH2QDYIGULHFS62",
        "GAOWJ3P2OQGK56Y6V7UIQEPVOGOWFKOI5JJ5AGNNVRPC6BZLNUFDCANF"
        ]

    [DOCUMENTATION]
    ORG_NAME="XDBChain Example"
    ORG_URL="https://example.xdbchain.com"

    [[VALIDATORS]]
    ALIAS="example-xdbchain-irl"
    DISPLAY_NAME="XDBChain Example Ireland"
    HOST="ireland.example.xdbchain.com:11625"
    PUBLIC_KEY="GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD"
    HISTORY="https://history.example.xdbchain.com/livenet/ireland/"


    [[VALIDATORS]]
    ALIAS="example-xdbchain-fra"
    DISPLAY_NAME="XDBChain Example France"
    HOST="france.example.xdbchain.com:11625"
    PUBLIC_KEY="GDSKRPNLL3HA7CUURJOEZJNJY43TGPTGMERKU7B4MJH2QDYIGULHFS62"
    HISTORY="https://history.example.xdbchain.com/livenet/france/"

    [[VALIDATORS]]
    ALIAS="example-xdbchain-deu"
    DISPLAY_NAME="XDBChain Example Germany"
    HOST="germany.example.xdbchain.com:11625"
    PUBLIC_KEY="GAOWJ3P2OQGK56Y6V7UIQEPVOGOWFKOI5JJ5AGNNVRPC6BZLNUFDCANF"
    HISTORY="https://history.example.xdbchain.com/livenet/germany/"

Transactions

Node Account

For each on our validator node (GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD, GDSKRPNLL3HA7CUURJOEZJNJY43TGPTGMERKU7B4MJH2QDYIGULHFS62, GAOWJ3P2OQGK56Y6V7UIQEPVOGOWFKOI5JJ5AGNNVRPC6BZLNUFDCANF) we need to create an account (fund them) and set option home_domain for that account.

First, we create account for each of our node, by making an transaction of type Create Account from our existing account, GDZDT2AZ65PALRS5COUBRRXPPESU3VB3PTP3BGRQSFI6JTCD6SKWMGWW.

Create Account Transaction

To do this, we create and submit transaction at XDBChain Laboratory.

Transaction Type: Transaction

Source Account: GDZDT2AZ65PALRS5COUBRRXPPESU3VB3PTP3BGRQSFI6JTCD6SKWMGWW

Transaction Sequence Number: 4658068126171137 (web get this number by pressing Fetch next sequence number for account starting with "GDZDT2AZ65")

Base Fee: 100 nibbs

Memo: None

Time Bounds: (optional) 1624563492 (Press Set to 5 minutes from now button)

Operation Type: Create Account

Destination: GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD

Strating Balance: 1000XDB (20XDB is the minimal ammount for Create Account operation).

Then we press Sign in Transaction Signer button.

Add Signer: SBUUJM5Q72XFGWF2SXHKJYTH5PBYQVHAWCPFRWB5AXNKGSBC4WM27CMZ (out existing account private key)

Press Submit in Transaction Submitter and then Submit Transaction button. If transaction succeeds, we created an account for our first validating node. We need to do this also for our second and third validating node.

Set Options ‘home_domain’ Transaction

Then we need to set home domain on that account, by making an transaction of type Set options at XDBChain Laboratory

Source Account: GBV3UQVVG5TSO6KYHGNDGK4HAEUW7F5VGJSOZD27OFGRKYBHWIHDZDJD (our first validating node public key)

Transaction Sequence Number …

Base Fee …

Memo …

Time Bounds …

Operation Type: Set Options

Home Domain: example.xdbchain.com

Press Sign in Transaction Signer

Add Signer: SAVFRRS7BGFGVDJEZBDNSXNLP7S7XJEXRDXKDFA4ARQCXVF4H4ZC4MSL (our first validating node private key)

Than submit transaction to the XDBChain Livenet Network. Do this to the rest of the nodes of your domain.

Walkthroughs
home domain
This post is licensed under CC BY 4.0 by the author.