This project is under development and started as a proof of concept.

BBSvx is blockchain powered Virtual Reality engine.

Application logic is based on BBS

Integrating blockchain into BBS should permit to :

• Have permanent ontologies
• Have permanently running agents (agents being ontologies)
• Keep consistency of ontologies in distributed environments as agents are interacting with them
• Benefit from blockchain inherent characteristics: Enhanced security, transparency, traceability etc.

This blockchain is supported by a P2P overlay network formed by nodes following SPRAY protocol. This permits to bring up a network where each peer only have a partial view of the whole network, named neighnours. Regularly, each node exchange a part of its neighbours with one of them.

Nodes are exchanging messages following EPTO protocol. This permits to have a consistent ordering of events among the nodes.

To permit side effects to Prolog queries, a leader is elected among the nodes of an ontology.

This tutorial will get you up and running with BBSvx in minutes using Docker Compose, demonstrating the distributed P2P network formation and monitoring capabilities.

• Docker and Docker Compose installed
• Git (to clone the repository)

# Clone and enter the repository
git clone https://github.com/netboz/bbsvx.git
cd bbsvx

# Build the BBSvx Docker image
docker build . -t bbsvx

# Build all required images including graph-visualizer
docker compose build

# Start BBSvx with 4 client nodes
docker compose up --scale bbsvx_client=4

This command starts:

• 1 BBSvx server node (the root/seed node)
• 4 BBSvx client nodes (joining the cluster)
• Grafana for monitoring dashboards
• Graph Visualizer for network topology visualization

Once the containers are running, you can monitor the P2P network formation:

Open http://localhost:3000 in your browser to access Grafana dashboards:

• Username: admin
• Password: admin (default)
• Navigate to the BBSvx SPRAY Dashboard to see:
  • Total connection slopes across the cluster
  • Arc exchange monitoring in real-time
  • Inview/outview connections per node
  • Network topology metrics

Open http://localhost:3400 in your browser to see:

• Interactive network graph showing all nodes and connections
• Real-time updates via WebSocket as nodes join/leave
• Right-click any node to inspect its inview/outview connections
• Visual representation of the SPRAY protocol overlay network

Now let's scale up to 10 client nodes to observe how the SPRAY protocol adapts:

# Scale up to 10 client nodes (keep existing containers running)
docker compose up --scale bbsvx_client=10 -d

Watch the monitoring dashboards as:

1. New nodes join the network automatically
2. SPRAY protocol exchanges redistribute connections
3. Network topology evolves to maintain optimal connectivity
4. Connection slopes adjust to accommodate the larger network

In the Graph Visualizer (http://localhost:3400):

• Watch new nodes appear and connect to existing ones
• Observe how connections redistribute as the network grows
• Right-click nodes to see how inview/outview connections balance

In the Grafana Dashboard (http://localhost:3000):

• Monitor the "Total Connection Slopes" metric increasing
• Watch "Arc Exchange" activity as nodes negotiate connections
• Observe how the network maintains stability despite scaling

The HTTP API is available at http://localhost:8085:

# View SPRAY network topology
curl -X GET http://localhost:8085/spray/nodes \
  -H "Content-Type: application/json" \
  -d '{"namespace": "bbsvx:root"}'

# View incoming connections (inview)
curl -X GET http://localhost:8085/spray/inview \
  -H "Content-Type: application/json" \
  -d '{"namespace": "bbsvx:root"}'

# View outgoing connections (outview)
curl -X GET http://localhost:8085/spray/outview \
  -H "Content-Type: application/json" \
  -d '{"namespace": "bbsvx:root"}'

# Create a new ontology
curl -X PUT http://localhost:8085/ontologies/my_test \
  -H "Content-Type: application/json" \
  -d '{"namespace": "my_test", "type": "local"}'

# Retrieve ontology facts and rules
curl -X GET http://localhost:8085/ontologies/bbsvx:root \
  -H "Content-Type: application/json" \
  -d '{"namespace": "bbsvx:root"}'

# Execute a Prolog goal/query
curl -X PUT http://localhost:8085/ontologies/prove \
  -H "Content-Type: application/json" \
  -d '{"namespace": "my_test", "goal": "your_prolog_query_here"}'

# Stop all containers
docker compose down

# Remove volumes (optional, clears all data)
docker compose down -v

• P2P Network: SPRAY protocol implementation for overlay network formation
• Consensus: EPTO protocol for consistent event ordering
• Ontology Management: Prolog-based knowledge bases using Erlog
• Transaction Processing: Blockchain-style transactions with validation pipeline
• HTTP API: Cowboy-based REST API for external interactions
• ASN.1 Protocol: High-performance binary protocol (102x faster than term encoding)

export BUILD_WITHOUT_QUIC=true
rebar3 compile

# Build release
rebar3 release

# Start development shell
rebar3 shell

# Run tests
rebar3 ct

# Build release
export BUILD_WITHOUT_QUIC=true
rebar3 release

# Start node
_build/default/rel/bbsvx/bin/bbsvx start

# Node operations
_build/default/rel/bbsvx/bin/bbsvx stop
_build/default/rel/bbsvx/bin/bbsvx console
_build/default/rel/bbsvx/bin/bbsvx ping

BBSvx supports intelligent configuration with automatic file location detection:

• BBSVX_CONFIG_FILE=/path/to/config - Environment variable override
• ~/.bbsvx/bbsvx.conf - User space config (recommended for development)
• ./bbsvx.conf - Current directory config
• etc/bbsvx.conf - Release default (production)

• boot = root - Start new cluster (fresh data only)
• boot = join <host> <port> - Join existing cluster
• boot = auto - Automatic detection (restarts only)

# Initialize user config
./bin/bbsvx config init

# Start new cluster
echo "boot = root" >> _build/default/rel/bbsvx/etc/bbsvx.conf
_build/default/rel/bbsvx/bin/bbsvx start

# Join existing cluster
echo "boot = join existing.node.com 2304" >> _build/default/rel/bbsvx/etc/bbsvx.conf
_build/default/rel/bbsvx/bin/bbsvx start

# Environment variables for deployment
export BBSVX_NODE_NAME="[email protected]"
export BBSVX_P2P_PORT=2305
export BBSVX_BOOT="join cluster.internal 2304"
_build/default/rel/bbsvx/bin/bbsvx start

# System status
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli status
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli status verbose

# Configuration management
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli show
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli show network.p2p_port
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli set network.p2p_port 3000

# Ontology management
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli ontology list
_build/default/rel/bbsvx/bin/bbsvx rpc bbsvx_cli ontology create my_namespace

# Build image
docker build . -t bbsvx

# Run with scaling
docker compose up --scale bbsvx_client=1    # Run with 1 client
docker compose up --scale bbsvx_client=N -d # Scale to N clients

• P2P Network: Port 2304 (configurable)
• HTTP API: Port 8085
• Graph Visualizer: Port 3400 (Docker only) - http://localhost:3400
• Grafana Dashboards: Port 3000 - http://localhost:3000

BBSvx provides the following REST API endpoints (default port: 8085):

PUT /ontologies/:namespace
Content-Type: application/json

{
  "namespace": "my_ont",
  "type": "local",           # or "shared" for distributed
  "version": "0.0.1",
  "contact_nodes": []
}

# Response: 201 (created) or 200 (already exists)

GET /ontologies/:namespace
Content-Type: application/json

{"namespace": "my_ont"}

# Response: List of Prolog clauses and facts in JSON format

DELETE /ontologies/:namespace
Content-Type: application/json

{"namespace": "my_ont"}

# Response: 204 (deleted)

PUT /ontologies/prove
Content-Type: application/json

{
  "namespace": "my_ont",
  "goal": "your_prolog_query_here"
}

# Response: {"status": "accepted", "id": "ulid"}

GET /spray/inview
Content-Type: application/json

{"namespace": "my_ont"}

# Response: Array of incoming arcs with source/target node details

GET /spray/outview
Content-Type: application/json

{"namespace": "my_ont"}

# Response: Array of outgoing arcs with source/target node details

GET /spray/nodes
Content-Type: application/json

{"namespace": "my_ont"}

# Response: Node metadata

DELETE /spray/nodes
Content-Type: application/json

{"namespace": "my_ont"}

# Response: {"result": "ok"}

WebSocket: ws://localhost:8085/websocket

- Sends initial ontology state on connection
- Pushes transaction diffs as they occur
- Auto-subscribes to bbsvx:root namespace

Web console available at: http://localhost:8085/console/

# Type checking
rebar3 dialyzer
rebar3 eqwalizer

# Format code
rebar3 erlfmt

BBSvx is built on a distributed architecture with the following key components:

• Application Flow: bbsvx_app → bbsvx_sup → service processes
• Ontology Operations: bbsvx_ont_service ↔ bbsvx_actor_ontology ↔ bbsvx_erlog_db_*
• Network Layer: bbsvx_network_service ↔ bbsvx_actor_spray ↔ connection handlers
• Transaction Flow: HTTP API → bbsvx_ont_service:prove/2 → creates transaction → bbsvx_epto_service:broadcast/2 → bbsvx_actor_ontology

• bbsvx_cowboy_handler_ontology - Ontology CRUD and Prolog query execution
• bbsvx_cowboy_handler_spray - SPRAY protocol debugging (inview/outview inspection)
• bbsvx_cowboy_websocket_handler - Real-time ontology updates via WebSocket
• cowboy_static - Static file serving for web console

# Run Common Test suites
rebar3 ct

# Run EUnit tests
rebar3 eunit

BBSvx uses ASN.1 encoding as the default protocol format:

• Performance: 102x faster than Erlang term encoding
• Size: 2.4x smaller messages
• Interoperability: Standardized format for cross-language compatibility

See LICENSE file for details.