Skip to main content

How to Join Testnet 1 Root Ring

The following will detail the necessary steps to join Testnet 1 Orbis Root Ring as a validator. Only the existing and approved validators can operate a Orbis node in the Root Ring.

Hardware Requirements​

Orbis doesn't have any specific requirements from a hardware perspective at the moment, however it is recommended to use a "good enough" datacenter machine.

Orbis can be deployed along side your existing validator hardware as a co-process. Or on a seprate machine entirely.

Minimum hardware requirements:

  • 2-core amd64 CPU (or 2 virtual cores)
  • 4GB RAM
  • 32GB SSD Storage
  • 100Mbps bi-directional internet connection.

Orbis Binary​

You can get the orbisd binary from the releases page of the Orbis repo: https://github.com/sourcenetwork/orbis-go/releases/tag/v0.2.3.

cd $HOME
wget https://github.com/sourcenetwork/orbis-go/releases/download/v0.2.3/orbisd
chmod +x orbisd
sudo mv /usr/bin

From Source​

You can download the code and compile your own binaries if you prefer. However you will need a local installation of the go toolchain at a minimum version of 1.21

cd $HOME
git clone https://github.com/sourcenetwork/orbis-go
cd orbis-go
git checkout v0.2.3
make build
cp ./build/orbisd $GOBIN/orbisd
export PATH=$PATH:$GOBIN

Now you will have the orbisd available in your local system.

Docker​

You can either use the pre-existing docker image hosted on our GitHub, or build your own

Github Container Registry (coming soon)​

docker pull ghcr.io/sourcenetwork/orbis:0.2.3

Build Docker Image from Source​

cd $HOME
git clone https://github.com/sourcenetwork/orbis-go
cd orbis-go
git checkout v0.2.3
docker build -t <name> .

Docker Compose​

TODO

Initialization​

To deploy our orbis node and to join the Root Ring running on SourceHub Testnet 1, generate or use an existing sourcehub keypair, and update your respective configuration.

Orbis will also need access to a running SourceHub Testnet 1 RPC Endpoint, this can either be:

Key Ring​

As for the sourcehub keypair, Orbis needs access to a sourcehubd keyring instance. You already have one running on your validator node, but you can also create a keyring on any node with sourcehubd keys add <keyname>. If you are running both orbisd and sourcehubd on the same machine, then you can share keys between your validator and orbis node.

The keyname you have already, or if you create a new one, must match what you specify in the orbis.yml config, defined below.

By default sourcehubd keys add <keyname> will use the os keyring backend, you may use other key backends supported by the SourceHub keyring utility, but whatever backend you use MUST match what is in your orbis.yml config. To learn more about various backends you can see the documentation available from the sourcehubd keys --help command.

caution

If you start your node and you get an error similar to error: bech32 decode ... then you likely have either used the wrong keyname or keyringBackend.

Faucet​

To be able to properly run the Orbis daemon and join the Root Ring, you need to ensure your account for the key you chose has sufficent number of $OPEN tokens, since initializating the DKG requires transactions on the network that need to be paid for.

As usual, you can go the SourceHub Testnet 1 and use the address of the new key sourcehubd keys show <keyname> --address.

Configuration​

You may have to configure orbis to work in your specific environment or hardware, depending on your storage and networking resources, here is a pretty standard configuration file orbis.yml

grpc:
  # GRPC Endpoint
  grpcURL: "0.0.0.0:8080"
  # Rest API Endpoint (optional)
  restURL: "0.0.0.0:8090"
  # GRPC Request logging (true/false)
  logging: true

logger:
  # Default log level ("fatal", "error", "warn", "info", "debug")
  level: "info"

host:
  # P2P Host Address (required - see below)
  listenAddresses:
    - /ip4/0.0.0.0/tcp/9000
  # P2P Boostrap peers (required - see below)
  bootstrap_peers:
    - /dns4/<SOURCEHUB_BOOTSTRAP_ADDRESS>/tcp/9000/p2p/<SOURCEHUB_BOOTSTRAP_PEERID>

transport:
  # P2P Peer exchange topic (required)
  rendezvous: "orbis-transport"

db:
  # DB data store path, prefixed with $HOME/.orbis
  # So "data" would result in a path $HOME/.orbis/data
  path: "data"

cosmos:
  # Cosmos chain ID
  chainId: sourcehub-testnet1
  # Cosmos keyring key name
  accountName: <keyname>
  # Cosmos keyring backend ('os' is the default when running sourcehubd)
  keyringBackend: os
  # Cosmos address prefix ('source' is for SourceHub)
  addressPrefix: source
  # Transaction fees
  fees: 2000uopen
  # SourceHub data folder where your keyring is defined
  home: ~/.sourcehub
  rpcAddress: <RPC Address>

When starting an Orbis daemon, you can specify the config file path with the --config <path> flag.

Configuration Requirements​

info

required host.listenAddress

You MUST run orbis with a publicly available host.listenAddress. In the above example config this is the

listenAddresses:
  - /ip4/0.0.0.0/tcp/9000

You can specify your own port to listen on, but the host port and bind address must result in a publicly available listener. This is the port that all the orbis nodes communicate their P2P network traffic.

info

required host.bootstrapPeers

You MUST use the host.boostrapPeersaddress provided in the #validator-info channel in the Source Network discord.

 bootstrap_peers:
    - /dns4/<SOURCEHUB_BOOTSTRAP_ADDRESS>/tcp/9000/p2p/<SOURCEHUB_BOOTSTRAP_PEERID>

The GRPC and Rest address/port don't necessarily have to be public, this can match whatever deployment environment you are currently using, however if you want to access these APIs from other machines, you must make the appropriate port and network rules to do so.

Start your node​

Once you have configured your keyring and config file, you can start you node.

orbisd start --config /path/to/orbis.yml
info

When starting your orbis daemon, your configured cosmos.rpcAddress endpoint must be live, since it tries to connect to this node immediatly upon startup. If you have any errors relating to cosmos client then you have either used the wrong rpcAddress or the RPC node isn't online.

SystemD Service (Optional)​

If you wish to use systemd to manage your daemon, you can use the following configuration.

Create the following file: /etc/systemd/system/orbisd.service

[Unit]
Description=Orbis service
After=network-online.target

[Service]
User=<user>
ExecStart=/<path-to>/orbisd start --config <path/to/orbis.yaml>
Restart=no
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

Joining the Root Ring​

The Root Ring is the Orbis deployment maintained by the validators of the SourceHub Testnet. The primary function of nodes maintaining the Root Ring is to create a shared keypair using a Distributed Key Generation (DKG) algorithm.

A Orbis ring is defined by its Manifest which is a configuration that describes all the initial parameters of a ring, such as what DKG algorithm to use, how to authenticate and authorize requests, the threshold number of nodes required for a proxy-encryption, etc. You can think of a ring manifest similar to a network genesis file.

Example Manifest

{
    "n": 3, // total number of initial nodes in the ring
    "t": 2, // threshold number of nodes for a proxy-encryption operation
    "dkg": "rabin", // DKG algorithm
    "pss": "avpss", // Proactive Secret Sharing algorithm
    "pre": "elgamal", // Proxy-Encyption algorithm
    "bulletin": "sourcehub", // bulletin board implementation
    "transport": "p2p", // networking transport
    "authentication": "jws-did", // encryption request authentication
    "authorization": "ACP", // encryption request authorization
    "nodes": [ // PeerIDs and Addresses of the initial nodes
        {"id":"16Uiu2HAm35sSr96x1TJHBTkWdcDH9P8twhTw92iDyq38XvyGzgZN","address":"/ip4/127.0.0.1/tcp/9001"},
        {"id":"16Uiu2HAmAVcM6V1PY8DdvzobyK5QZbwX5z3AA6wCSrCm6xUA79Xn","address":"/ip4/127.0.0.1/tcp/9002"},
        {"id":"16Uiu2HAkzjLLosHcV4LGvLY4vskda5NgMW4qmtfQ2uMbgFAoqghX","address":"/ip4/127.0.0.1/tcp/9003"}
    ],
    "nonce": 0 // nonce to alter the determinisic ring content identifier (CID)
}

Creating the Root Ring Manifest​

To create the Root Ring manifest we need all the initial nodes PeerIDs and P2P Addresses. In fact, the rest of the parameters of the Root Ring manifest will be the same as the example above, with the exception of

  • Number of nodes (n)
  • Threshold number of nodes (t)
  • Initial (nodes)

The root ring manifest cannot be created until all existing validators start their Orbis nodes, and report back with the respective PeerIDs and Addresses.

Once you have a running node, you can get your PeerID and Address with the following command:

orbisd -s <grpc-address:port> transport-service get-host --transport p2p

This will respond back with something like:

{
    "node":{
        "id":"16Uiu2HAm35sSr96x1TJHBTkWdcDH9P8twhTw92iDyq38XvyGzgZN",
        "address":"/ip4/<YOUR_PUBLIC_IP_ADDRESS>/tcp/9001",
        "publicKey":{
            "Type":"Secp256k1",
            "Data":"AnHK2Co3LgeLHo8tMsyfMlp0JXGL3y9yiPOAkQVknfrp"
        }
    }
}
info

Sometimes the address field returns 127.0.0.1 instead of a public address, if so, please replace it with your nodes publicly accessible IP address

Please post this full response in the #validator-general channel, this is all public information, so no security details are being leaked.

Once all the current validators have started their nodes, and posted their host info, we can craft the Root Ring manifest.

Create Root Ring​

info

We now have the assembled manifest.json file needed to start the root ring. You can download the root ring manifest for Testnet1 here

ALL NODES MUST BE UPDATED TO v0.2.3 BEFORE CREATING THE RING To create the root ring, and start the Ditributed Key Generation (DKG) process to create the shared keypair, each node will need download the manifest file here and then run the create-ring command, as shown below.

NOTE You must ensure you have sufficient $OPEN balance for the SourceHub key you are using for your orbis node. You can get tokens from the faucet: https://faucet.source.network/

wget https://raw.githubusercontent.com/sourcenetwork/networks/15ad45d92e6c012150e764db0c9e7f9e1e25c64f/testnet1/orbis-root-ring/manifest.json

orbisd -s <grpc-address:port> ring-service create-ring -f <path-to>/manifest.json

This will initialze the DKG process and you node will start generating its respective DKG Share. This process can't complete unless all nodes are online and syncing. Once completed, the Root Ring will have an initialized DKG, and is ready to start recieving Store and ReEncrypt requests!

If we have reached this step together without errors, then we will have completed the Orbis Root Ring setup!

However, if there are errors experienced along the way, we may need to issue a software update, and restart the process. This is experimental and bleeding edge software, but we hopeful that we can collectively launch the Root Ring without any breaking or blocking issues.

Join Root Ring
Edit this page