User Guide

Installation & Start

Install VS1984

# install vs1984 in ubuntu 24.04
 sudo dpkg -i vs1984.deb

 # uninstall vs1984 in ubuntu 24.04
 sudo apt purge vs1984

 # run in the terminal
 vs1984

Install and Start the Background Service

Install the VS1984 background service

# install vs1984 service in ubuntu 24.04

 systemctl --user daemon-reload

 systemctl --user enable --now vs1984d.service

Show Current Version

Display the running version of VS1984:

# input:
 cmd version
 # output:
 SDK: xbc version: 0.9.25 build: 20251127025427

Exit VS1984 Properly

Although VS1984 is a command-line tool, it must be exited gracefully through its own command:

cmd exit

Files & Directory Overview

• After installation:

# installation path: /usr/local/vs1984
 ├── cnf             # configuration directory <must keep>
 ├── .dat            # local data directory
 ├── .DFT_Exp_Table  # steganography connection image cache
 ├── .id             # node id file <must keep>
 ├── .bt             # node bt seed files
 ├── .ai             # node ai vector storage
 ├── .cache          # Merkle-Patricia tree cache
 ├── .scbc           # SCBC blockchain storage
 ├── tasks           # ongoing task cache
 └── .tmp            # temporary cache files

Command-line Startup Options

• -p

# specify <port> to start the service
  vs1984 -p <port>
 # if -p 0 is used, VS1984 will randomly pick a port between 15000 and 65000

• -s

# connect to a node
 vs1984 -s <node ip>:<port>

• -i

# connect via node id
 vs1984 -i <node id>

• -a

# connect using an image with connection info
 vs1984 -a <node connect info image>

• -u

# automatically enable router UPnP
 vs1984 -u

• -c

# load custom configuration file
 vs1984 -c <config_file_path>

• example

# Example:
 vs1984 -u -p 36984 -s :36983 -i A7HNzh7r2b6cKwXVdNShNLoKk+arm06pBT78TY6SyHK1
 # run vs1984, port 36984, connect to node which port is 36983,id is A7HNzh7r2b6cKwXVdNShNLoKk+arm06pBT78TY6SyHK1

Configuration

A default config file exists under the cnf directory (config.xbc). You may modify VS1984’s behavior there or use -c to load a custom config.

# Example:
 {
   "neighbors": 10,
   "share": {"max": 20},
   "whitelist": ["node A id", "node B id"],
   "tls": {"cert": "./cnf/self.crt", "pkey": "./cnf/self.key", "pass": "111"},
   "app": "-u -p 0 -a ./will_connect_img",
   "routes": "./cnf/routes.json",
   "guard": "static",
   "env": "MTg1MzU3OTk3MUF1aDdzQmVweFJ4ZWdWMzFYUnlzNlV0ekttUWxGZ0xselpadXloN3Mvc1E0TUVVQ0lRQ2NEM0ZNZFVHclZWVjZ3NmhDdUlOZjFHMUNkSHpEMFpjU1hxWkwwbVlDWlFJZ1ZLN1FKN2t0VjlhdFNTTkhVRjNDZnJVRlVzazRBam54V0VYdUg1K2pBcmc9"
 }
 # neighbors           max neighbor connections allowed
 # share: {"max": 20}  max shared routing info count
 # whitelist           node whitelist
 # blacklist           node blacklist
 # tls                 certificate paths
 # app                 startup parameters for client
 # routes              bootstrap node list
 # guard               keep guard id & cert unchanged if static
 # env                 software env param

Start the VS1984 BT Background Service

# Add the following to the VS1984 configuration:
 "bt": {"startup": true, "config": "vshome/cnf/bt.conf", "bt_path" : "."}
 # config: BT configuration file
 # bt_path: The VS1984 BT executable file

Start the VS1984 RAG Background Service

# Add the following to the VS1984 configuration:
 "rag": {"provider": true, "model": "models/model.gguf", "rag_path" : "."}
 # provider: Starts as the rag content service
 # model: Local LLM model path
 # rag_path: The VS1984 rag executable file

Accessing the VS1984 background service using the xmd tool

# Add the following to the VS1984 configuration:

 "daemon": {"startup": true, "token": <user_token>},

 # Start the xmd tool locally and connect to the local VS1984 service

 xmd -t <user_token>

Connect to Another Node

cmd connect <node_ip>:<node_port> <node_id>

Disconnect from a Node

cmd disconnect <node_id>

List Routing Table

# list all routing entries
 cmd ids all
 # list neighbor routes
 cmd ids
 # list non-neighbor hints
 cmd ids hint

View Node Details

cmd id <node_id>

Set Node Nickname

cmd id set <node_id> <nickname>

Delete Node Nickname

cmd id del <node_id>

Create Your Own Certificate

This command generates an anti-MITM certificate using a local proof-of-work computation. This usually takes 1–2 minutes.

cmd cert <cert_private_key_pass>

View Your Own Node Info

cmd self

Export Your Connection Info into an Image

Image resolution must be at least 1024 x 1024.

cmd img <image_path>

Connect to a Node via Image

cmd connect <node_connection_image>

Send P2P Encrypted Message (to any node)

cmd chat <node id> <message>

Broadcast Message to Neighbors

cmd broadcast <message>

Show VS1984 Working Directory

cmd work

Add Local File

cmd add <local_file>
 # ex: cmd add ll.jpg
 # File copied to local node successfully!

List Local Files

cmd ls file
 # NODE: <self node id>
 # FILE: ll.jpg

Generate Download Link for a File

Create a download link for node A:

cmd mk <self node id> <file name> <node A id>
 # the resource url is rsx://QXduK01XanBy...

Download File via Link

Download a file shared specifically to you. Otherwise decryption will fail.

cmd get <rsx url>

Anonymous On-chain Publishing

Publish data anonymously to the blockchain:

cmd kk '<msg>'
 # note: wrap with '', SDK callers do not need ''
 # ex: cmd kk '{"topic":"wonder woman","url":"magnet:?xt=urn:btih:JMZCWVEMYLX5LBXEP3VPHF7NN4KNG3TG","tokens":"100000","type":"video","intro":"Diana of Themyscira, also known by her superhero title Wonder Woman","tag":"superhero"}'

Transfer Tokens

(Future versions will integrate stablecoin vault and bridge services)

cmd tr <to node id> <amount>

Withdraw

(Depends on stablecoin vault and bridge services)

coming soon

View Ledger Balance

# view your own balance
 cmd bl self
 # view another node's balance
 cmd bl <node id>

View Current Tasks

# list tasks
 cmd task list
 # sync tasks
 cmd task sync
 # clear all tasks
 cmd task clean

BT Commands

Operate BT functions using these commands

# Add a file to seed

 cmd bt seed <file_path>

 # Download a BT file via magnet

 cmd bt magnet <magnet_url>

 # Check BT download status

 cmd bt status <infohash>

Encrypting/Decrypting a String

Use this command to encrypt/decrypt a string.

# Encrypt a string

 cmd secret encrypt <node_id> <to_secret_string>

 # Decrypt a string

 cmd secret decrypt <node_id> <from_secret_string>

File Encryption/Decryption

Use this command to encrypt/decrypt a file.

# Encrypt a file using a key as the encryption seed

 cmd file encrypt <key> <file_path>

 # Decrypt a file

 cmd file decrypt <key> <file_path>

View Single On-chain Message

cmd mid <mid>

Voice Call Between Neighbors

# Node A requests voice call with Node B
 node A : cmd call req <node B id>
 # Node B accepts the request
 node B : cmd call ans <node A id>
 # WebRTC connection auto-negotiated

 # end the call
 node A : cmd call end <node B id>
 node B : cmd call end <node A id>

View a Node’s On-chain Information

# view your own info
 cmd bc self
 # view info of a node’s real id
 cmd bc <node real id>

Redownload a Block

# cmd block <block number>

View Blacklist

# cmd blacklist

Regenerate Guard ID and delete TLS Certificate

This command regenerates the Guard ID and TLS certificate. Before doing so, ensure that the "guard" option in the configuration file is not configured as "static".

# cmd new id