Cardano Testnet Node Toolkit 🤠

A simple Cardano node toolkit, interact with Cardano nodes running in docker or connect via socket file.

Allowing the user to run multiple dockerised nodes, with different versions and across networks.

Docker node version choices: 10.5.3, 10.5.1

Prerequisites

Docker

Install docker desktop for your operating system.

• https://docs.docker.com/engine/install

If you are using Apple silicon (M1, M2, M3 processor) make sure you have Rosetta enabled via Docker desktop settings.

Mac Specific Prerequisites

1. xcode tools.

xcode-select --install

2. Rosetta.

softwareupdate --install-rosetta

Windows Specific Prerequisites

Windows Subsystem for Linux.

How to Install WSL on Windows

Setup Guide

1. Clone this repository

You may want to make a nice folder/directory for this first.

Clone into current directory.

git clone https://github.com/Ryun1/testnet-docker-node.git

2. Open testnet-docker-node from within Visual Studio Code

Open Visual Studio Code and then go File > Open Folder selecting testnet-docker-node folder.

3. Open a terminal in Visual Studio Code

Open a terminal inside of VSCode.

4. Update script permissions

Inside the terminal console, give scripts execute file permissions.

Windows users will have to run this first, to access the wsl environment.

wsl

Run the following command.

chmod +x ./start-node.sh ./stop-nodes.sh ./scripts/*

Note: Make sure your terminal shows the correct directory testnet-docker-node.

Basic Usage

Note: Before any usage ensure you have docker desktop open and running.

Start node

We have a start script which:

• pulls the latest testnet node configs
• pulls the Cardano node docker image
• builds and runs the Cardano node image
• pushes the node logs to the terminal

In your terminal execute:

./start-node.sh

Then choose which network to work on.

If you want to stop the logs (but the node is still running) you can press control + c.

This should look something like:

Note: The first time you do this the node will take a long time to synchronize to the network.

Check node is running

1. Open a new terminal

Press the plus at the top right of your terminal window.

And then click on the new terminal.

2. Query tip of node

Run the node query tip script.

Windows users will have to run this first, to access the wsl environment.

wsl

In your second terminal execute:

./scripts/query/tip.sh

For a fully synced node the terminal should return, with syncProgress of 100.00.

{
    "block": 1185368,
    "epoch": 277,
    "era": "Conway",
    "hash": "13d654899faabb50522f7f608e8d627acaaa8206347c913b0e74754538754eb5",
    "slot": 24011698,
    "slotInEpoch": 78898,
    "slotsToEpochEnd": 7502,
    "syncProgress": "100.00"
}

For a un-fully synced node the terminal should return, with syncProgress of less than 100.00. You will have to wait till fully synced node before being able to interact with the network.

{
    "block": 14646,
    "epoch": 3,
    "era": "Babbage",
    "hash": "d72cb1cfb7f7eb9d457d48c0d3e165170565eb371f8f5c7cb3d6d212be97c797",
    "slot": 292713,
    "slotInEpoch": 33513,
    "slotsToEpochEnd": 52887,
    "syncProgress": "1.22"
}

Stop node

This script will stop your Cardano node, remember to run this when you are done using your node.

In your second terminal execute:

./stop-nodes.sh

Doing Stuff

Now you have a node you can actually ✨do fun stuff✨

Setup keys and get tAda

1. Generate keys, addresses and a DRep ID

We have a script that:

• randomly generates a set of payment, stake and DRep keys
• from keys, creates addresses and a DRep ID

In a terminal execute:

./scripts/generate-keys.sh

This will create you a keys directory with some fun things inside, looks like this:

2. Get some tAda

Get yourself some test ada, so you can pay for transaction fees.

Open your new address from ./keys/payment.addr.

Go to the Testnet faucet and request some tAda sent to your new address.

Run Scripts

Check out the scripts folder and see what you'd like to do.

I will give an example of what you could do.

Make sure you have a node running for these.

Become a DRep, delegate to self and vote

1. Register as a DRep

./scripts/drep/register.sh

2. Register your stake key (needed before delegating)

./scripts/stake/key-register.sh

3. Delegate your tAda's voting rights to yourself

./scripts/drep/delegate-to-self.sh

Using Multiple Nodes and External Nodes

This toolkit supports connecting to multiple Cardano nodes simultaneously - both Docker containers and external nodes running outside of Docker. You can run scripts against different networks and nodes at the same time.

External Node Configuration

External nodes use environment variables CARDANO_NODE_SOCKET_PATH and CARDANO_NODE_NETWORK_ID. You can check these through the start-node.sh script, which will prompt you for the values and confirm them before use.

Important: Only one external node connection is supported at a time. For multiple external nodes, switch environment variables between script executions.

Multiple Docker Containers

When multiple Docker containers are running, the toolkit will:

• Automatically select the only container if only one is running
• Prompt you to choose if multiple containers are running (interactive mode)
• Use the first container if running non-interactively (no TTY)

Requirements

• Local cardano-cli: When using external node mode, you must have cardano-cli installed locally and available in your PATH
• Network restriction: Mainnet connections via external sockets are not allowed for security reasons. Only testnet networks (preprod, preview, sanchonet) are supported
• Socket file: The socket file must be accessible and the node must be running