diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88ca679..9e5c931 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ -# Intro +# Thank You! Public contributions to the documentation are welcome. When contributing, please help with consistency and clarity by adhering to the below guidelines. -### Disambiguation -* Strive for brevity and clarity. Avoid jargon and use a professional writing tone. +# Disambiguation +* Strive for brevity and clarity. Avoid jargon and use a professional writing tone. Adhere to standards, such as [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). * When referring to the software `xahaud`, use a lowercase "x" and include the 'd'. When referring to the broader `Xahau Network`, capitalize both terms and,if appropriate, subsequently use the capitalized term "the Network". Use the capitalized `Xahau` or the all caps abbreviation `XAH` when referring to the currency. * Be mindful that this documentation is shared by a global community. Avoid culture-specific jargon or slang. -### Formatting +# Formatting * Relative and absolute linking are both permitted. When changing the directory structure or renaming individual pages, use grep to ensure all links are updated. Header, footer, index page, navigation bar, and links on other pages all need to be updated manually. * The use of second person ("you") is permitted. * Individual webpages may be formatted using Markdown, HTML, CSS, and JavaScript in any combination. To the extent possible, favor style templates and avoid inline CSS. @@ -15,5 +15,5 @@ Public contributions to the documentation are welcome. When contributing, please * Use square brackets inside code snippets to offset user specific information, such as file names and paths. For example: `cd [/path/to/xahaud] && ./xahaud server_info` * Wrap multi-line code examples in three backticks: "```". -### General Guidelines +# General Guidelines * Include meaningful commit messages. diff --git a/astro.config.mjs b/astro.config.mjs index 71b0633..f2f74bb 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -284,7 +284,9 @@ export default defineConfig({ 'docs/infrastructure/installing-xahaud', 'docs/infrastructure/updating-xahaud', 'docs/infrastructure/enabling-validation', + 'docs/infrastructure/identity', 'docs/infrastructure/interacting', + 'docs/infrastructure/advanced-configuration', { label: 'Building Xahau (Dev)', collapsed: true, diff --git a/src/content/docs/docs/index.mdx b/src/content/docs/docs/index.mdx index 1a554e0..594c98f 100644 --- a/src/content/docs/docs/index.mdx +++ b/src/content/docs/docs/index.mdx @@ -22,12 +22,7 @@ It also covers the different ledger objects integral to the network's operation, ### Infrastructure -The Infrastructure section provides detailed instructions for setting up the build environment on both Ubuntu 22.04 and macOS 13.5.2. +Infrastructure is the core of the Xahau Network. Servers running the xahaud software enable users to do things like submit, verify, and query transactions. The documentation in this section provides instructions for installing, updating, configuring, and building xahaud. Concepts, such as attesting to the identity of a given server or running xahaud as a validator, are also discussed. -In the 'Building Xahau' chapter, you will find a step-by-step guide through the process of establishing environmental variables, installing core and Xahaud dependencies, and compiling the software. -This includes the acquisition and setup of essential components like LLVM, Boost, WasmEdge, and Protobuf. The steps explain why certain versions and configurations are needed to ensure compatibility and optimal performance. - -This section ends with cloning the Xahau repository and creating the Xahaud target, setting developers on the path to adding to or deploying the Xahau network. - -**We hope this documentation provides you with the information you need to understand, use, and contribute to Xahau. Happy exploring!** +**We hope this documentation provides you with the information you need to understand, use, and contribute to the Xahau Network. Happy exploring!** diff --git a/src/content/docs/docs/infrastructure/advanced-configuration.mdx b/src/content/docs/docs/infrastructure/advanced-configuration.mdx new file mode 100644 index 0000000..90a862e --- /dev/null +++ b/src/content/docs/docs/infrastructure/advanced-configuration.mdx @@ -0,0 +1,57 @@ +--- +title: Advanced xahaud Configuration +--- +There are numerous configuration options available to xahaud operators. This section will cover some of the more commonly used options, including those required for clustering servers and configuring databases. + +For complete documentation on configuration options, please see the example configuration files in the [xahaud GitHub repository](https://github.com/Xahau/xahaud/tree/dev/cfg). + +## Running Databases in Memory +Users seeking to maximize xahaud performance may choose to run databases in memory, rather than on dedicated storage media. Memory databases are not suited for machines storing history, as the databases are not persistent across xahaud restarts. Likewise, the amount of history stored is contingent on available system memory. Thus, `online_delete` and `advisory_delete` are required in the `xahaud.cfg` to prevent out of memory errors. When using a memory database, it is advisable to disable SWAP, as SWAP writes the contents of memory to disk, thereby potentially defeating the benefits obtained by storing the database in memory. + +To enable the memory database, edit the `xahaud.cfg` file: + +``` +[relational_db] +type=RWDB + +[node_db] +type=RWDB # RWDB is the memory database +online_delete=256 # This value should be low on machines using memory databases. '256' is the minimum value. +advisory_delete=0 # Do not require human intervention to delete history. This is necessary for preventing out of memory errors. +``` + +## Clustering +Clustering allows xahaud operators to configure multiple xahaud servers so that the servers trust one another, thereby reducing workload. Properly clustered servers can share information about malicious or problematic websocket, rpc, and peer connections, while also automatically propagating submitted transactions throughout the cluster. Thus, if a transaction is submitted on a sever with a higher load than the transaction's fee allows for, the transaction will still propagate to other servers in the cluster, thereby increasing the probability that the transaction is included in an upcoming ledger. + +Administrators operating xahaud validators can benefit from clustering, as the cluster provides connectivity for the highly secure validator, thereby eliminating the need for the validator to connect to unknown or untrusted servers. + +Server operators should not cluster their servers with servers outside of their own control. Likewise, clustered servers should have low latency connections, ideally being located in the same data center. + +Generating cluster seeds (public/private keys) is done via the `validation_create` [API method](../../features/http-websocket-apis/admin-api-methods). While the method name includes the term 'validation', this method is not used to [create the keys](../enabling-validation) used to sign validation messages. Instead, it is used to create keys to identify any xahaud server, validating or non-validating. + +To create a cluster: +1. On each xahaud instance that will be included in the cluster, generate a public key and seed: `./xahaud validation_create` +2. Open each server's `xahaud.cfg` file, and add or edit the following sections: + * `[ips_fixed]` - Include the IPv4/6 addresses and peer listening ports (e.g., `10.1.1.2 21337`) for other servers that will be in the cluster. The listening port is defined under the `[port_peer]` stanza in the `xahaud.cfg` file on the server listening for incoming connections. The default listening port for the main Xahau Network is `21337`. + * `[node_seed]` - The output in the `validation_seed` field from the `validation_create` command. This is a private key, and it must be installed on the same server on which it was generated. + * `[cluster_nodes]` - The output from the `validation_public_key` field of the `validation_create` command. This is a public key, and it must be installed on peer servers, not the server on which it was generated. +3. Restart xahaud on each server in the cluster: `systemctl restart xahaud` +4. Backup each server's `xahaud.cfg`. +5. Verify connectivity among clustered peers via the [peers](../../features/http-websocket-apis/admin-api-methods) API method: `./xahaud peers` + +The cluster section of a `xahaud.cfg` file might look like this: +``` +[ips_fixed] +10.1.1.2 21337 # Clustered peer 1 +10.1.1.3 21337 # Clustered peer 2 +10.1.1.4 21337 # Clustered peer 3 + +[cluster_nodes] +n9LzAHaB7ka318dAJWLQD1WkpGR86NyvaCzrtUAt4PuNtDCTCqxn # validation_public_key from clustered peer 1 +n9KWNMsRdQ66jYHLCVgFBAQAzb16DwDioVdXSuV8pTcfEfaHkdvZ # validation_public_key from clustered peer 2 +n9JFK8xUcy9S9TBmCcZKKmY28LEVjTurcpzC5XkXnyAAj1Svytee # validation_public_key from clustered peer 3 + +[node_seed] +sn8QEFTpBM8nydnLD6FjxKN845uRG # Private validation_seed from the local xahaud instance + +``` diff --git a/src/content/docs/docs/infrastructure/enabling-validation.mdx b/src/content/docs/docs/infrastructure/enabling-validation.mdx index 6dd272b..7922ac6 100644 --- a/src/content/docs/docs/infrastructure/enabling-validation.mdx +++ b/src/content/docs/docs/infrastructure/enabling-validation.mdx @@ -1,15 +1,18 @@ --- -title: Enabling Validations in xahaud +title: Enabling Validation in xahaud --- Validators are xahaud nodes that are configured with an additional public/private keypair, which is used to sign each proposed ledger. Thus, validators are the primary mechanism used to achieve consensus regarding the order in which transactions are applied on the Xahau Network. +## Background Considerations +Running a validating xahaud server may seem straight forward, however, there are a number of considerations for production node operators including uptime and security. This following introductory sections provide background on these considerations. + ### Security and Availability When running xahaud as a validator, system security and availability are critical. Validator operators are expected to actively monitor their servers and to respond quickly to outages. Some validator operators choose to host standby machines in diverse data centers, so they can quickly recover from outages. While it is possible to host a reliable validator in one's home, it is unlikely that such a setup could provide sufficient stability and security for the validator to gain broader trust (e.g., inclusion on published UNLs). Similarly, validator operators are strongly discouraged from running software other than xahaud on a machine used as a xahaud validator, since this increases the probability of running out of resources or exposing a security vulnerability. System administrators who require websocket or RPC access to a server are encouraged to run different machines for queries, so resources are not taken away from the critical task of validating ledgers.

The private/public validation keypair should be stored and backed up in a secure, offline environment. Anyone with access to the keys of a trusted validator has potential to harm the network. After installing a validation token into the xahaud.cfg file, it is advised to restrict read access (`chmod 400 xahaud.cfg`) and change ownership of the file to "root" or "xahaud", depending on the type of install (`chown root:root xahaud.cfg`). ### Identity Attestation -To avoid a [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack) and build trust, validating xahaud nodes attest to their identity by cryptographically signing a domain name with their validation keys. This signature is then hosted at the same domain, in a TOML format file. In addition to verifying the identity of a validator, this TOML file can also be used to verify the identity of individual account holders on the Xahau Network, by providing an attestation signed by the private account key instead of the private validation key. The TOML file should be hosted on a web server with TLS encryption enabled at:

https://[your-domain.com]/.well-known/xah-ledger.toml

+To avoid a [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack) and build trust, validating xahaud nodes attest to their identity by cryptographically signing a domain name with their validation keys. This signature is then hosted at the same domain, in a [TOML format file](../identity). In addition to verifying the identity of a validator, this TOML file can also be used to verify the identity of individual account holders on the Xahau Network, by providing an attestation signed by the private account key instead of the private validation key. The TOML file should be hosted on a web server with TLS encryption enabled at:

https://[your-domain.com]/.well-known/xahau.toml

### Peering To maintain a high level of security, xahaud nodes that are configured as validators should only peer with known, trusted peers. Enabling the `peer_private` setting and explicitly defining `ips_fixed` in the xahaud.cfg file will force a server to only connect to defined peers. Operating system and hardware level protections, such as firewalls, provide additional reassurance that the server is only connecting to defined peers. However, this can be a challenge, as validators with too few peers, typically less than about five, are at risk of falling out of sync with the rest of the network. @@ -23,17 +26,23 @@ The Xahau Network utilizes the [Governance Game](../../features/governance-game) 4. A proactive approach to updating and voting for [amendments](../../features/amendments) and fees - This requires taking the time to watch what is in development +## Enabling Validation +Switching a stock xahaud server into a validator is a straight forward process. Essentially, users will generate a public/private keypair, which is then used to generate a token using an ephemeral key derived from the master pair. That token is installed into the `xahaud.cfg` file, thereby instructing xahaud to propose validations to the Network. + ### Building the Validation Keys Tool -At this time, there is not a packaged tool for generating validation keys. Thus, users can either build the tool from scratch or rely on a packaged version provided with rippled (this tool is not packaged with the xahaud binary). The instructions for building the tool are the same as the instructions for building rippled, and they are provided on the [ripple/validator-keys-tool](https://github.com/ripple/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/rippled-examples/blob/master/validator-keys) available on unofficial repositories. +At this time, there is not an official release of the software used for generating validation keys. Thus, users can either build the tool from scratch or rely on a packaged version provided with rippled (this tool is not packaged with the xahaud binary). The instructions for building the tool are the same as the instructions for building rippled, and they are provided on the [ripple/validator-keys-tool](https://github.com/ripple/validator-keys-tool) repository page. There are also some [packaged binaries](https://github.com/jscottbranson/xahau-examples/) available in unofficial repositories. Users seeking to generate keys for production validators should build the tool from scratch on a secure, air-gapped machine. + +While xahaud provides the `validation_create` [Admin API method](../../features/http-websocket-apis/admin-api-methods), this method is NOT capable of generating the necessary validation token or allowing for domain verification. Thus, despite the name, the `validation_create` method is used to create public/private keys to identify a server broadly, for example when [clustering multiple servers](../advanced-configuration). ### Generating and Installing Validation Keys Consider using an offline machine to generate validation keys and a validation token. 1. Navigate to the directory containing the validation keys tool: `cd [/path/to/tool]` 2. Generate a new keypair: `./validator-keys create_keys` -3. The newly generated keypair is stored in `/home/[username]/.ripple/validator-keys.json`. +3. The newly generated keypair is stored in `/home/[username]/[.ripple or .xahaud]/validator-keys.json`. The storage path depends on which version of the validator-keys-tool is used. 4. Ideally, validators should provide identity attestation. To do so, set your domain in the validator-keys.json file: `./validator-keys set_domain [example.com]` - - If you do not wish to provide an identifying domain, generate a validation token without a domain: `./validator-keys create_token --keyfile /home/[username]/.ripple/validator-keys.json` + - If you do not wish to provide an identifying domain, generate a validation token without a domain: `./validator-keys create_token --keyfile /home/[username]/.xahaud/validator-keys.json` 5. Review the output of the previous command. Note the `[validator_token]`, as this will be installed in xahaud.cfg to enable validation. If a domain was set, note the `attestation=""` line, as it will need to be added into the TOML file served at your domain. + - Anytime the tool is used to generate a new `validator_token`, a field, `token_sequence`, is incremented in the `validator-keys.json` file. The Network will ignore validations from any server that has a token generated with a lower sequence number than the highest observed number. For example, if your validation token has sequence number "3" and you generate a new token with sequence number "2", validations from any machine using the new token with the lower sequence number will be ignored. This feature enables server operators to generate a new token, rather than generating new master validation keys, in the event of a security compromise or other incident. 6. Open xahaud.cfg and paste in the `[validation_token]`, then restart the xahaud service. -7. Paste the `attestation=""` into your TOML file to prove the identity of your validator. - +7. Paste the `attestation=""` into your [TOML](../identity) file to prove the identity of your validator. +8. Ensure private validation keys are stored securely, ideally separate from the validator. diff --git a/src/content/docs/docs/infrastructure/identity.mdx b/src/content/docs/docs/infrastructure/identity.mdx new file mode 100644 index 0000000..caa7042 --- /dev/null +++ b/src/content/docs/docs/infrastructure/identity.mdx @@ -0,0 +1,179 @@ +--- +title: Serving a TOML File for Identity Verification +--- +***Identity verification requires two parts. NEVER TRUST TOML FILES OR ON NETWORK VALIDATOR/ACCOUNT ATTESTATIONS ALONE TO CONFIRM IDENTITY, AS ANYONE CAN SET THEM. A website (URL) must claim ownership of the validator/account, and the on-network data must match.*** + +Given that trust is foundational to the Xahau Network, it is ideal for entities operating xahaud validators to take credit for their servers. Identity attestation provides users with assurances that one entity isn't gaining disproportionate control over the trusted (default UNL) validators in the Network. This is is done by publishing two attestations: one from a validating server on the Xahau Network and a second from a web server that serves the identifying domain over TLS. Thus, the validator claims association with the web domain and the web domain claims association with the validator. *Without both of these claims, it is not possible to trust the identity attestation.* + +Similarly, individual Xahau account holders might wish to publish a TOML file attesting that specific accounts on the network are under their control. Account ownership attestations are particularly relevant for enterprises, such as exchanges or financial institutions. As with validators, these attestations require two parts: a web server that claims ownership of a Xahau Network address as well as an on-network account address that claims to be owned by the same domain. Account attestations provide users with confidence that they are routing deposits to the correct address. + +The contents and structure of this file are similar to those used by [Stellar](https://developers.stellar.org/docs/tokens/publishing-asset-info) and the [XRP Ledger](https://xrpl.org/docs/references/xrp-ledger-toml). Since the file can contain custom fields, it is important to allow flexibility when building tools designed to parse the TOML file. + +## Web Server and DNS Configuration +1. The file contents must be in the [TOML format](https://github.com/toml-lang/toml). +2. The TOML file must be served from: `https://[optional-subdomain.your-domain.com]/.well-known/xahau.toml` + * The path `/.well-known/xahau.toml` must not be altered. The path must be all lower case. + * [RFC 5785](https://datatracker.ietf.org/doc/html/rfc5785) contains more information on the "/.well-known/" path. +3. A TLS certificate chaining to a trusted certificate authority must be used to encrypt connections serving the TOML file. +4. DNS Sec is recommended for the domain. +5. Subdomains may be used to serve the file, and identical files may be hosted from multiple subdomains. +6. Content type for the file is `application/toml`. +7. The TOML file must be served with a CORS header: `Access-Control-Allow-Origin: *` +8. Additional headers may be served with the TOML file, if needed. +9. Custom or nonstandard fields may be added to the TOML file, as required by individual users. +10. No field is strictly required in the TOML file. + +### CORS Configuration +Apache: +``` + + Header set Access-Control-Allow-Origin "*" + +``` +Nginx: +``` +location /.well-known/xahau.toml { + add_header 'Access-Control-Allow-Origin' '*'; +} +``` + +### TOML File Contents +TOML files are typically subdivided into sections describing the TOML file itself (metadata), principals (responsible parties), and claimed assets including: validators, non-validating xahaud servers, accounts, and issued currencies. + +#### Example TOML +The below example is intended to illustrate all sections that are commonly included in a Xahau Network TOML file. Individual users may not have all of these sections in their TOML file, and some users may need to include multiple of the same section. For example, if one exchange issues multiple currencies, it would include a `[[CURRENCIES]]` section for each IOU issued on the Network. +``` +[METADATA] +modified = 2025-08-04T14:24:34.123Z +expired = 2025-12-31T14:24:34.123Z + +[ORGANIZATION] +name = "A Company B.V." +website = "https://example.com" +email = "contact@example.com" + +[[PRINCIPALS]] +name = "A. Person" +email = "a_person@example.com" +social_1 = "https://www.linkedin.com/company/incfintech" +x = "@IncFinTech" + +[[VALIDATORS]] +public_key = "nHBixLw8q7XUP5AKceK2aZriN67PPjQW7JJ7hLkJgxvkTTs5go6k" +attestation = "07FA61020CA5E0605BE29D213DCC33F934B631EB6215F52D3E99D8AEA841272E300758B5C03CD2332190307324B4869838B77BAD275B31CF59D13E8FA6A8780B" +owner_country = "US" +server_country = "CA" +network_asn = "398726" +network = "21337" +unl = "https://vl.xahau.org" + +[[SERVERS]] +ws = "wss://" +json_rpc = "https://" +peer = "https://" +network = "21337" + +[[ACCOUNTS]] +address = "rabc..." +network = "21337" +desc = "This wallet is used for client deposits." + +[[CURRENCIES]] +code = "USD" +issuer = "rabc..." +symbol = "$" +network = "21337" +display_decimals = 2 + +[[CURRENCIES]] +code = "EUR" +issuer = "rabc..." +symbol = "€" +network = "21337" +display_decimals = 2 +``` + +#### Metadata +Dates/times in the TOML file should be specified in UTC and include millisecond precision. For example, `2025-08-04T14:24:34.123Z`. Only one metadata section can be included in a TOML file. + + + + +
FieldData TypeDescription
`modified`Date-TimeDate and time when the TOML was most recently modified.
`expires`Date-TimeAfter this date/time, the TOML file will be considered expired and thus invalid.
+ +#### Organization +If an entity rather than an individual is claiming responsibility for the TOML file, that entity should use this section to identify itself. It would be unusual and likely an error for one TOML file to have multiple `[ORGANIZATION]` sections. If multiple sections are needed, ensure an additional set of brackets are added: `[[ORGANIZATION]]`. + + + + + + +
FieldData TypeDescription
`name`StringThe name of organization hosting the TOML file.
`email`StringEmail address for the organization.
`website`StringWebsite for the organization (typically this is the same as the URL where the TOML is hosted).
`social_[x]`StringLink to a social media profile. This field is not standardized at this time. Thus, `x = "@IncFinTech` and `social_1 = https://x.com/IncFinTech` are both valid.
+ +#### Principals +This section is used to identify individual points of contact for the Xahau Network infrastructure and/or accounts. + + + + + + +
FieldData TypeDescription
`name`StringThe name of an individual responsible for overseeing the organizations Xahau Network operations.
`email`StringEmail address for the principal.
`website`StringWebsite for the principal.
`social_[x]`StringLink to a social media profile. This field is not standardized at this time. Thus, `x = "@IncFinTech` and `social_1 = https://x.com/IncFinTech` are both valid.
+ +#### Validators +Validator operators are strongly encouraged to publish an attestation as proof of ownership. Providing geographic and ISP information is important, as it enables trusted (dUNL) list publishers to evaluate the geographic diversity of trusted validators on the network. If too many trusted validators are concentrated in one geographic region or on one network ASN, there is a risk to the broader network. + + + + + + + + + +
FieldData TypeDescription
`public_key`StringThe master public key used to validations.
`attestation`StringDomain attestation generated by the validator-keys tool.
`owner_country`String[ISO-3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code for the entity or person in charge of the server.
`server_country`StringISO-3166-2 country code for the server's physical location.
`network_asn`StringThe Autonomous System Number (ASN) for the Internet Service Provider(s) providing internet connectivity to the server.
`network`StringIdentifies which network (Mainnet, Testnet, etc.) the server participates in.
`unl`StringA URL hosting the list of trusted validators that the validator subscribes to.
+ +#### Servers +Network participants who provide public peering or API access via websocket or RPC can publish details for accessing individual servers. + + + + + + +
FieldData TypeDescription
`ws`StringThe URL for public websocket access. This begins with "ws:// or wss://".
`json_rpc`StringThe URL for public RPC access. This begins with "http:// or https://".
`peer`StringURL other servers can use to peer with the server identified in the TOML.
`network`StringIdentifies which network (Mainnet, Testnet, etc.) the server participates in.
+ +#### Accounts +Entities needing account verification can use this section to claim ownership of a given Xahau Network wallet. + + + + + +
FieldData TypeDescription
`address`StringThe encoded public key (beginning with `r`) identifying a Xahau Network wallet.
`network`StringIdentifies which network (Mainnet, Testnet, etc.) the wallet is used on.
`desc`StringHuman readable description of what the wallet is used for.
+ +#### Currencies +It is possible for multiple wallets to issue currencies with the same currency code. ***Thus, it is critical that users verify the issuing wallet as well as the currency code.*** + + + + + + + +
FieldData TypeDescription
`code`StringThe ticker symbol of the token as three digits or 40 hex characters. This field is case sensitive.
`issuer`StringThe wallet address (beginning with `r`) that issued the currency. The referenced wallet should be present in the `[[ACCOUNTS]]` section of the TOML file.
`symbol`StringThe symbol (e.g., "$") used to identify the currency.
`network`StringIdentifies which network (Mainnet, Testnet, etc.) the currency is issued on.
`display_decimals`IntegerThe number of digits to the right of the decimal point that clients should display when showing quantities of the currency.
+ +## Validator Domain Verification +Hosting the `xahau.toml` file enables domain owners to claim ownership of a validator. However, it is critical that the validator also acknowledge this ownership, so third parties can reliably trust network operators. Since validators form the backbone of forward progress on the Xahau Network, it is important that operators appropriately secure their private validation keys. + +If you are not familiar with the Validator Keys Tool, see the page on [Enabling Validation in xahaud](../enabling-validation). + +Users who have already complete the steps on the Enabling Validation page do not need to repeat them. Simply paste the `attestation = ""` field into the TOML file and ensure the correct `[validator_token]` is installed in the `xahaud.cfg`. + +Users who did not configure a domain when they initially generated a validation token may do so by running `./validator-keys set_domain [example.com]`. Prior to attempting to set the domain, ensure that the master validation key JSON file is stored in the correct path: `/home/[username]/[.ripple or .xahaud]/validator-keys.json`. + +## Wallet Address Verification +Consistent with validator domain verification, verifying ownership of a wallet address on the Xahau Network requires two components: A TOML file served over a TLS encrypted connection (with a properly chained certificate) from the domain claiming ownership and a transaction from the wallet address verifying the ownership claim. To claim ownership of a wallet address: +1. Include the address as an `[[accounts]]` section in the TOML file. +2. Submit an [AccountSet transaction](../../protocol-reference/transactions/transaction-types/accountset) with the `Domain` field specified. diff --git a/src/content/docs/docs/infrastructure/interacting.mdx b/src/content/docs/docs/infrastructure/interacting.mdx index da8bcf8..e1c0037 100644 --- a/src/content/docs/docs/infrastructure/interacting.mdx +++ b/src/content/docs/docs/infrastructure/interacting.mdx @@ -3,7 +3,7 @@ title: Interacting With xahaud Using Websocket and RPC --- The xahaud software provides both websocket and RPC interfaces that can be configured for a variety of use cases, such as submitting transactions or querying ledger history. Some users may choose to place proxy software in front of xahaud to provide encryption, load balancing, or other benefits. It is possible to install TLS certificates in the xahaud.cfg file using parameters such as `ssl_key = [/path/to/key]`. -### Configuring Websocket and RPC Ports +## Configuring Websocket and RPC Ports To enable listening ports, edit the `xahaud.cfg` file. Enabled ports are listed under the `[server]` stanza in the configuration file. Each port listed under the `[server]` section must be further defined via it's own stanza. In addition to configuring websocket or RPC ports, administrators can also configure the port used to listen for incoming peer connections (`port_peer`). On validating servers, it is ideal to remove `port_peer` from the configuration file, to avoid incoming connections. A configuration file with the peer protocol, one websocket port, and one RPC port might look like:



``` diff --git a/src/content/docs/docs/infrastructure/system-requirements.mdx b/src/content/docs/docs/infrastructure/system-requirements.mdx index d61c8fc..8933bc5 100644 --- a/src/content/docs/docs/infrastructure/system-requirements.mdx +++ b/src/content/docs/docs/infrastructure/system-requirements.mdx @@ -3,7 +3,7 @@ title: System Requirements --- Hardware requirements for nodes customized for various tasks (e.g., RPC/WS, hubs, validators, etc.) should be consistent with the specs outlined below. Consider tailoring your individual system based on your intended use case. -### Types of Nodes +## Types of Nodes It is possible to run xahaud in diverse configurations, based on a users needs. Similarly, one xahaud server can be configured for multiple purposes, such as a full history server that is also used for RPC/WS calls. The server's purpose dictates necessary system requirements. Some xahaud configurations might include: 1. Stock server - This term is commonly used to refer to any xahaud node that is not configured as a validator. A stock server generally has very few changes from the default configuration. 2. Full history servers - Are useful for querying historic data. In addition to a large amount of storage space, potentially higher disk IOPS and network bandwidth are needed, depending on the number of users querying the server. @@ -11,7 +11,7 @@ It is possible to run xahaud in diverse configurations, based on a users needs. 4. Hub server - Peering between nodes is critical for relaying messages across the Xahau Network, and a single server can be configured to provide peering for hundreds of peers. However, a large amount of bandwidth can be required (10 Gbit+). 5. [Validating servers](../enabling-validation) - Validators differ from other types of nodes, in that they require an additional cryptographic key to be installed, so they can sign off on the sequence of transactions in a proposed ledger. As availability and security are critical, it is not recommended to use a validator for other functions. -### General Notes +## General Notes * Builds are typically tested on Ubuntu LTS. However, Docker, portable binaries, custom builds, and other install methods allow for diverse operating system support. * Typically one IPv4 and/or IPv6 address is needed for each xahaud instance. Running multiple instances behind one IPv4 address is not recommended. * Machines storing full history must use XFS or similar to avoid limitations with single file size in EXT4 (max. file size of 16TB). If storing less history, EXT4 is sufficient. @@ -19,6 +19,6 @@ It is possible to run xahaud in diverse configurations, based on a users needs. * These system requirements may grow over time. For example, disk space for full history servers is consistently increasing. * As of August 6, 2025 the full history for the Xahau Network is approximately 8TB. -### Recommended Specs for Production xahaud Servers +## Recommended Specs for Production xahaud Servers
MinimumPreferredIdeal
CPU (2.5+ GHz x86_64)8 cores20 cores40+ cores
Memory32GB64GB128GB+
Disk IO (sustained)15k random RW20k random RW30k random RW
Disk Size500GB1TB20TB+
FilesystemXFSXFSXFS
Network IO500Mbit+1Gbit10Gbit
diff --git a/src/content/docs/docs/infrastructure/updating-xahaud.mdx b/src/content/docs/docs/infrastructure/updating-xahaud.mdx index 9caa608..42ff15a 100644 --- a/src/content/docs/docs/infrastructure/updating-xahaud.mdx +++ b/src/content/docs/docs/infrastructure/updating-xahaud.mdx @@ -3,7 +3,7 @@ title: Updating xahaud --- The process for updating xahaud varies depending on the install method used, however, all three methods rely on the releases published at [https://build.xahau.tech](https://build.xahau.tech). When updating a validator, hub, or other 'critical' infrastructure, please check the network health prior to restarting a server to install an update. It is possible to automate the update process using a crontab entry and an update script, however, administrators are discouraged from doing so, as automatic updates may result in restarts at times when the network is unstable. Similarly, human presence allows operators to ensure updates are successful, thereby minimizing downtime. -### Backup +## Backup Users should always keep backups of: 1. The primary configuration file: `xahaud.cfg` - Location varies based on install type. @@ -13,7 +13,7 @@ Users should always keep backups of: - Located in the database directory defined in 'xahaud.cfg'. 4. Validators must keep their validation private key backed up in a secure, offline location. -### Updating Docker Containers +## Updating Docker Containers Updating xahaud inside a Docker container involves replacing the currently running binary with the new version, downloaded from [https://build.xahau.tech](https://build.xahau.tech). This can be accomplished either by replacing the xahaud binary inside the container or by updating the entire container.

To update the xahaud binary inside a running Docker container: @@ -30,7 +30,7 @@ To replace the current Docker image with a new version, without overwriting data 5. Remove the old instance: `docker rm xahaud-[mainnet/testnet]` 6. Start the new instance: `./build && ./up` -### Updating Local Installations +## Updating Local Installations To update a locally installed version of xahaud, simply replace the current binary with a new binary: 1. Download the new binary from: [https://build.xahau.tech](https://build.xahau.tech) 2. Mark the new binary executable: `chmod +x [/path/to/download]` @@ -41,7 +41,7 @@ To update a locally installed version of xahaud, simply replace the current bina

A [script](https://gist.githubusercontent.com/WietseWind/9480a4fc95e904e54524406005c8c963/raw/2b200fdc2e5b471ae4f6625674aff1765d63e744/update.sh) that automates the above steps is available. -### Updating Binary Files +## Updating Binary Files Updating the xahaud binary files is essentially the same as the original install instructions: 1. Remove the currently running version: `rm [/path/to/xahaud]` 2. Download the new version: [https://build.xahau.tech](https://build.xahau.tech) diff --git a/src/content/docs/docs/protocol-reference/transactions/transaction-types/accountset.mdx b/src/content/docs/docs/protocol-reference/transactions/transaction-types/accountset.mdx index c39d6c5..0a8a926 100644 --- a/src/content/docs/docs/protocol-reference/transactions/transaction-types/accountset.mdx +++ b/src/content/docs/docs/protocol-reference/transactions/transaction-types/accountset.mdx @@ -42,7 +42,7 @@ To remove the `Domain` field from an account, send an AccountSet with the Domain You can put any domain in your account's `Domain` field. To prove that an account and domain belong to the same person or business, you need a "two-way link": * Accounts you own should have a domain you own in the `Domain` field. -* At that domain, host an xah-ledger.toml file listing accounts you own, and optionally other information about how you use Xahau. +* At that domain, host a [xahau.toml](../../../infrastructure/identity) file listing accounts you own, and optionally other information about how you use Xahau. ### AccountSet Flags