NDF Retrieval

This guide covers how to fetch the network definition file, or NDF, either through the command line (CLI) or using the Client API (xxDK).

The xx network team maintains an encoded NDF online, which has a comprehensive list of publicly available gateway addresses and their certificates. The data is base64-encoded (use base64 -D on the file to read). The reader may take this list or use their own methods to find gateway information depending on their trust model (see Vetting Gateways section below).

From this list, a trustworthy gateway should be determined by the reader. To avoid influencing or suggesting which gateways should be trusted, all examples in this guide use a local network. localhost:8440 should be replaced with a trusted gateway address when fetching an NDF off of a live network.

Using the CLI

The getndf CLI command enables you to download the NDF from a network gateway. This does not require a pre-established client connection, but you will need the IP address, port, and an SSL certificate for the gateway:

// Download an SSL certificate using OpenSSL 1.0.1 or newer
// (check your version if you get an error)
openssl s_client -showcerts -connect localhost:8440 < /dev/null 2>&1 | openssl x509 -outform PEM > certfile.pem
// Fetch NDF from a gateway
go run main.go getndf --gwhost localhost:8440 --cert certfile.pem | jq . >ndf.json

If you are trying to connect to one of the public networks, we recommend downloading an NDF directly for different environments by using the --env flag. This will download the NDF directly from a URL hosted by the xx network team:

// Download an NDF using the team environment URL
go run main.go getndf --env mainnet | jq . >ndf.json

Using the xxDK

There are two (2) methods of retrieving an NDF via the xxDK. Neither requires a pre-established client connection.

Downloading from a Gateway

You may download an NDF from a selected gateway using the xxDK via the DownloadNdfFromGateway() function. Below is an example code snippet using that xxDK call:

// Gateway contact information
certPath := "path/to/gateway.crt"
address := "localhost:8440"

// Read certificate from file
cert, err := utils.ReadFile(certPath)
if err != nil {
    jww.FATAL.Panicf("Failed to read file: %+v", err)
}
    
// Download NDF from a target gateway
resp, err := xxdk.DownloadNdfFromGateway(address, cert)
if err != nil {
    jww.FATAL.Panicf("%v", err)
}

Downloading from a URL

You may download an NDF using the xxDK from the URL provided by the xx network team using the DownloadAndVerifySignedNdfWithUrl() function call. The URL contains a signed version of the NDF which requires a certificate to verify that signature. There are several running environments, each with its own URL and certificate. Below is an example code snippet using that xxDK call:

// Network environment parameters.
certificatePath := "path/to/certificate.crt"
ndfUrl := "<insertURL>"
     
// Read certificate
cert, err := ioutil.ReadFile(certificatePath)
if err != nil {
    jww.FATAL.Panicf("Failed to read certificate: %v", err)
}

// Download NDF from URL
ndfJSON, err = xxdk.DownloadAndVerifySignedNdfWithUrl(ndfURL, string(cert))
if err != nil {
    jww.FATAL.Panicf("Failed to download NDF: %+v", err)
}

Vetting Gateways

When downloading an NDF from a gateway, it’s important to ensure that the targeted gateway can be trusted. There are many ways to do this; the team provides a few possible strategies for the reader to develop trust with a gateway. This is not intended to be a comprehensive guide for establishing trust with gateways, but a way to suggest possible avenues.

As an entry point, the team publishes a publicly available list of gateways in the published encoding of the NDF. You can download that, decode it, and select a gateway from the list. However, it is better to have some trust in the gateway as the wrong NDF can be provided by the gateway, connecting you to the wrong network. There are three (3) general methods you can use:

Choose a gateway run by you or an acquaintance. If you know someone who runs a gateway, or you are running a gateway, you can use that information to connect to your gateway to get an NDF.
Use the longest-running gateways. You can find the longest-running gateways by browsing the dashboard and clicking on the node information, or via the wallet by browsing the staked validators.

Use team-run gateways. If you trust the team, you can select the team gateway. The details of the team gateway are:

Name: xx west

Node ID: c6wptSinakErZHrk0SlgGQXExETPYYLB2CwpLNze6FMC

Validator wallet: 6Wb9wqBLi8iBhpnNqqWDVPcqfRQMkqTZWq9cAsALwC7W68h4

Gateway ID: c6wptSinakErZHrk0SlgGQXExETPYYLB2CwpLNze6FMB

Address: 161.35.228.41:22840

Tls_certificate:

NDF Retrieval

Using the CLI​

Using the xxDK​

Downloading from a Gateway​

Downloading from a URL​

Vetting Gateways​

Using the CLI

Using the xxDK

Downloading from a Gateway

Downloading from a URL

Vetting Gateways