Skip to content

Installation Instructions

Jump to bottom
Jacob Pretorius edited this page May 8, 2023 · 8 revisions

The bot needs to be hosted somewhere, but you don't need much in terms of resources. You should be able to use a cheap Digital Ocean droplet as long as you have root/admin access and can open up some firewall ports. A static IP/custom domain would be useful, but once again you can use something like DuckDns for a forwarding url.

Hardware Requirements

A server with at least the following:

  • Node 16.17.x
  • MongoDb 6.0.0 Community
  • 512mb of RAM available for the bot
  • (Optional) Azure Application Insights

You can use Windows, Linux or Mac as long as you have Node working and installed.

The default configuration uses the shared XRPL cluster from xrplcluster.com however in the real world you will find this is likely too slow so you may want to run your own Rippled server. That is outside of the scope of this guide, you can read more at install and manage Rippled.

Discord Setup

To add a new application/bot to your project's Discord follow these steps

  1. Sign in to the Discord developer portal
  2. Create a new "Application" by giving it a name and clicking create
  3. Add an image and a description (shown in the About Me section in Discord)
  4. Note the Application ID on the General Information page, we'll need it later
  5. Click on "Bot" in the left navigation and then under "Build-A-Bot" click the "Add Bot" button. Click Yes to confirm
  6. Add an icon and set the bot username
  7. Click the "Reset Token" button, then copy and save the token, we will need it later
  8. Untick the "Public Bot" option, making it private.
  9. Tick the "Server Members Intent" option, as we need it to work with the users on your Discord server
  10. Tick the "Message Content Intent" option, as we need it to work with DM's

You are now ready to add the bot to your Discord server by updating the URL below and visiting it in your browser (you need to have admin access to the Discord server to be able to add bots).

https://discord.com/api/oauth2/authorize?client_id=CHANGE-ME&permissions=545394228336&scope=applications.commands%20bot

Copy the url above and change the CHANGE-ME value to your Application ID we got from step 4 above. Then visit this using your browser. You will have to login to Discord and then choose which server you want to add the bot to.

Discord Setup

You need to setup the roles on your Discord server you want assigned based on holdings and get your admin/mod users Discord IDs so they can use the admin commands this bot has.

The bot can only assign roles "below" itself in the Discord role list, so make sure to put the bot role high up in the list. You also need to make another role for the bot which gives it rights to manage user roles, such as server admin.

You can right click a user in Discord and choose "Copy ID" to get their Discord ID. Do this for all your admins/mods you want using the bot admin commands and keep these ID's for later.

The last bit of information you will need to collect is your Discord server ID. The easiest way to get that is right click on your Discord server and choose "Copy ID" from the drop-down. Keep this for later.

Build and Configuration

This is probably the quickest way to get the bot running, and some of these steps overlap with running it using Docker.

  1. Clone the git repo by downloading the latest release
  2. Extract/unzip it somewhere on your device e.g. /xrplbot
  3. Navigate there using a terminal e.g. cd /xrplbot
  4. Install dependencies npm install
  5. Open src/settings.ts using a text editor of your choice
  6. Change all the values for your configuration marked with replace-me with the values we prepared earlier. Save all changes once done.
  7. In the terminal run npm run start
  8. Verify it is running by visiting http://localhost:5880 (or whatever port you set it to listen to in the settings file)
  9. Verify Discord setup is working by seeing the bot come online in Discord. DM the bot "help" and it should respond with the available commands. If so, you're good to go!

Docker (optional)

A valid Dockerfile comes with the repo, so should you want to host and deploy it using Docker, follow the steps above and then make and host the Docker image.

Be sure not to host/expose your built Docker image publicly if you made value changes in src/settings.ts as other people will be able to see your secrets!

  1. Build the image from the project directory docker build . -t xrpl_discord_bot_image
  2. Run it docker run -p 5880:5880 --name xrpl-discord-bot xrpl_discord_bot_image
  3. If you are building the image and running it on the same machine (suggested), you're done.
  4. If you want to push the built image, securely push it to a private docker registry now. This is more advanced and introduces more room for error, so steps not shown here. Nothing unusual, Push it to the registry, pull it from your server/cluster, run it.

Automated Task Runners

The bot includes task runners that run in the background to, for example, re-scan known user wallets and Discord accounts tracking changes in their holdings.

The default task runners listen on /updateWallets and /updateAccounts

This step needs to be performed on the machine that will be hosting/running your bot.

You can use anything that will automatically send a GET request to these endpoints, although you may want to secure them behind a firewall (or never open up the bots web server port in the first place!) so that they cannot be spammed by users increasing server load.

The easiest way to achieve this is on a Linux based distro is using a cron job on the host server/machine:

  1. Open crontab with crontab -e
  2. Add the following cron jobs
*/20 * * * * /usr/bin/curl -k -s http://127.0.0.1:5880/updateWallets > /dev/null
*/29 * * * * /usr/bin/curl -k -s http://127.0.0.1:5880/updateAccounts > /dev/null
# IF YOU ARE USING FARMING ALSO UNCOMMENT THE NEXT CRON JOB 
# BY REMOVING THE HASH AT THE START
# 0 * * * * /usr/bin/curl -k -s http://127.0.0.1:5880/updateFarmingWallets > /dev/null
  1. Save the changes and exit the crontab file
  2. You should see a message in the terminal that the crontab was updated/saved
  3. Verify it ran by checking the bot console output at the next interval

You can configure how often these are run and fine tine it for your needs and available resources. Do note as mentioned previously, using the share XRPL cluster is slow for /updateWallets and you may have to decrease how often it runs by changing the */20 (every 20 minutes) to something like */45 (every 45 minutes) or similar. Standard crontab so you can use https://crontab.guru/ to help generate it.

XUMM Login Setup

You can optionally enable "login with XUMM" functionality, where users are presented with a QR code they can scan in XUMM to sign in with their wallet when doing the link-wallet process.

To do this you need to register the bot as a new XUMM application at https://apps.xumm.dev

By default, the bot listens on /xummWebhook for web requests from the XUMM servers back to the bot.

From the XUMM developer dashboard (where you also get the API Key and Secret) you need to fill in your bots public /xummWebhook address in their webhook field.

Screenshot 2023-01-18 at 7 46 24 pm

For example if your bot has a forwarded publicly available domain "xrpldiscordproject.com" you need to fill in "https://xrpldiscordproject.com/xummWebhook".

You can also put your bots IP address in directly such as "http://123.123.123.123:5880/xummWebhook", but this is not recommended unless you have a static IP address. You can use something like Ngrok for local testing/debugging.

Clone this wiki locally