Prerequisites & Setup

Before you explore the tutorials, make sure you’ve set up a working VSL node and initialized your environment.

This guide provides a high-level overview of the setup steps and points you to the official VSL-SDK repository where detailed, up-to-date instructions are maintained.

Requirements

• Docker and Docker Compose installed

• A terminal or shell environment

Choose a Setup Method

There are two supported ways to run a local VSL node for development:

Option 1: Docker-Based Setup (Recommended)

Use Docker Compose to spin up all required services. This includes the VSL core node and explorer using pre-built images.

At a high level, you’ll need to:

1. Visit the vsl-sdk Quick Start guide.

2. Follow the instructions to start the local devnet using:

docker compose -f docker-compose.public.yml pull
docker compose -f docker-compose.public.yml up -d

3. This starts the node with a default master account defined in tests/genesis.json.

Customize the Master Account

If you'd like to use your own master account address and balance:

• Copy the tests/genesis.json file.

• Modify it to your desired address and initial balance.

• Point the Docker Compose file to your custom genesis file (update the path in docker-compose.public.yml).

Option 2: Run the VSL Core Node Manually

If you prefer not to use Docker or want more control, you can run the node directly from your machine using the CLI. This involves launching a server and providing a genesis.json file to configure the initial state.

At a high level, you’ll:

1. Create a genesis.json file with initial accounts and optional token data

2. Start the server manually:

vsl-cli server:launch --db tmp --genesis-file "genesis.json"

Using --db tmp creates a temporary database on your filesystem. While not stored in memory, it behaves like a throwaway instance. The database is automatically deleted when the server shuts down.

For persistent testing or development, replace tmp with a folder path, to store the database on disk.

1. Use the CLI to load your master account and begin interacting with the network

The genesis.json file defines the initial state of your local VSL network, including pre-funded accounts and optional custom tokens.

Here’s an example structure:

{
  "accounts": [
    {
      "id": "0x0101010101010101010101010101010101010101",
      "balance": "300000000000000000000000"
    },
    {
      "id": "0x0202020202020202020202020202020202020202",
      "balance": "0"
    }
  ],
  "tokens": [
    {
      "ticker_symbol": "CUSTOM",
      "creator_id": "0x0101010101010101010101010101010101010101",
      "creator_balance": "50000000000000000000000000"
    }
  ]
}

This is an explanation of the field above:

• accounts: List of accounts to initialize. Each must include:

  • id: the account address (hex string)

  • balance: initial balance in atto-VSL

• tokens (optional): List of custom tokens to initialize.

  • ticker_symbol: token name (e.g., CUSTOM)

  • creator_id: address of the account that will hold the minted tokens

  • creator_balance: how much of the token to mint initially

This lets you spin up a local network that already includes the accounts and tokens you need for testing.

Master Account Setup

No matter which setup you use, you must initialize and load a master account. This account typically funds other accounts and performs admin-level actions in tutorials.

A few things to note:

• You’ll either define this address via the .env file (Docker) or genesis.json (manual).

• You must load its private key into the CLI:

vsl-cli repl --tmp-config
vsl> account:load master -p <your_private_key>
vsl> account:use master

Verify Your Setup

To confirm your node is healthy and ready:

• Test the RPC connection using curl:

curl -X POST http://localhost:44444 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"vsl_getHealth","params":{}}'

• Or alternatively via the CLI:

vsl> health:check

• Check your account in the CLI:

vsl> account:balance

Next Steps

Once your setup is complete, you're ready to follow the tutorials in order:

• Creating Accounts

• Creating Custom Assets

• Submitting and Verifying Claims

Need help? Visit our Discord community for support and discussion.