Welcome! This guide will get you up and running with rivellum in under 5 minutes.

Prerequisites

• Rust 1.75+ (install)
• Node.js 18+ (install)
• Make (optional, but recommended)

Quick Start (3 Steps)

1. Clone and Build

git clone https://github.com/rivellum/rivellum.git
cd rivellum
cargo build --release

This builds the rivellum-node binary in ./target/release/.

2. Start the Sandbox

In terminal #1:

# With Make
make sandbox

# Or directly
./target/release/rivellum-node sandbox

You should see:

╔════════════════════════════════════════════════════════════╗
║     rivellum SANDBOX - LOCAL DEVELOPMENT ENVIRONMENT      ║
╚════════════════════════════════════════════════════════════╝

💰 Faucet Account (for testing):
   Address:     0x19e7e376e7c213b7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7
   Balance:     1,000,000,000,000
   Private Key: 0x1111111111111111111111111111111111111111111111111111111111111111

╔════════════════════════════════════════════════════════════╗
║                  SANDBOX IS RUNNING                        ║
╠════════════════════════════════════════════════════════════╣
║ RPC Endpoint:    http://127.0.0.1:8080                       ║
║ Explorer URL:    http://localhost:3000 (if running)        ║
╚════════════════════════════════════════════════════════════╝

What just happened?

• Created a temporary blockchain in .rivellum-sandbox/
• Pre-funded a faucet account with 1 trillion units
• Started an RPC server on port 8080
• Ready to accept transactions!

3. Run a Demo

In terminal #2:

# Run the private payments demo
make demo-payments

# Or manually
cd examples/payments
npm install
npm start

You'll see the demo:

1. Connect to the sandbox
2. Create two accounts (Alice & Bob)
3. Fund Alice from the faucet
4. Send an encrypted transfer from Alice to Bob
5. Verify balances updated

What's Next?

Option A: Explore the Demos

Private Payments Demo (examples/payments/):

• Shows encrypted transfers
• Demonstrates SDK usage
• Includes balance queries

cd examples/payments
npm start

Smart Contract Demo (examples/contract-call/):

• Deploys a HelloWorld contract
• Calls contract methods
• Analyzes gas consumption

cd examples/contract-call
npm start

Option B: Use the Wallet CLI

The wallet CLI provides secure, profile-based key management:

# Build the wallet
cargo build --release -p natos-wallet

# Create a dev profile (for testing)
./target/release/natos-wallet create --name dev --dev

# Check balance
./target/release/natos-wallet balance dev --node http://127.0.0.1:8080

# Send transfer
./target/release/natos-wallet send \
  --from dev \
  --to <recipient_address> \
  --amount 10000 \
  --node http://127.0.0.1:8080

Profile Features:

• Secure AES-256-GCM encryption (production mode)
• Weak encryption for testing (dev mode with --dev flag)
• Named profiles for easy management
• Auto-nonce detection

See Wallet Guide for full documentation.

Option C: Build Your Own dApp

Create a new project:

mkdir my-rivellum-app
cd my-rivellum-app
npm init -y
npm install node-fetch

Simple RPC client:

import fetch from 'node-fetch';

const RPC_URL = 'http://127.0.0.1:8080';

async function getBalance(address) {
  const response = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'stro_getBalance',
      params: [address],
    }),
  });
  
  const data = await response.json();
  return data.result;
}

// Check faucet
const balance = await getBalance('0x19e7e376e7c213b7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7');
console.log(`Faucet balance: ${balance}`);

Understanding the Sandbox

What is it?

The sandbox is a single-node, local blockchain designed for rapid development:

• ✅ Zero configuration - Just run one command
• ✅ Known credentials - Faucet with public private key
• ✅ Fast iterations - No network delays
• ✅ Easy reset - Wipe and restart anytime
• ✅ Full RPC API - Same as production nodes

Data Storage

All sandbox data lives in .rivellum-sandbox/:

.rivellum-sandbox/
├── state.db/           # Account state (sled database)
├── ledger.log          # Transaction log
├── arrival.log         # Photon Committee log
├── security.log        # Security events
└── committee.key       # Encryption key (dev-only)

Reset the sandbox:

make sandbox-reset
# Or
./target/release/rivellum-node sandbox --reset

This deletes .rivellum-sandbox/ and starts fresh.

Faucet Account

The sandbox includes a pre-funded faucet:

⚠️ WARNING: This private key is publicly known. NEVER use it in production!

Use this account to:

• Fund new test accounts
• Deploy contracts
• Test transactions

RPC API

The sandbox exposes a JSON-RPC API on http://127.0.0.1:8080:

Core Methods

Get chain ID:

curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"stro_getChainId","params":[]}'

Get state root:

curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"stro_getStateRoot","params":[]}'

Get balance:

curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"stro_getBalance","params":["0x19e7e376e7c213b7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7"]}'

Submit intent (transaction):

curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"stro_submitIntent",
    "params":[{
      "type":"Transfer",
      "from":"0x19e7...",
      "to":"0xabcd...",
      "amount":1000,
      "nonce":1234567890,
      "chain_id":"rivellum-sandbox-1",
      "signature":"0x...",
      "timestamp_ms":1234567890000
    }]
  }'

Full API Reference

See RPC_API.md for complete documentation.

Advanced Features

Custom Port

Run sandbox on a different port:

./target/release/rivellum-node sandbox --port 9000

PoUW Mode

Enable Proof-of-Useful-Work:

./target/release/rivellum-node sandbox --with-pouw

This starts a local PoUW worker that will process work intents.

Metrics

Sandbox exposes Prometheus metrics:

curl http://127.0.0.1:8080/metrics

Useful for monitoring:

• Intent throughput
• State tree depth
• Gas consumption
• RPC request latency

Troubleshooting

Sandbox won't start

Error: "Address already in use"

Another process is using port 8080. Either:

• Stop the other process
• Use a custom port: --port 8081

Error: "Failed to create directory"

Check permissions:

chmod +w .

RPC not responding

Verify sandbox is running:

curl http://127.0.0.1:8080/health
# Should return: {"status":"ok"}

Demo fails

Make sure Node.js dependencies are installed:

cd examples/payments
npm install

Check that sandbox is running in another terminal.

Common Workflows

1. Feature Development Cycle

# Start sandbox
make sandbox

# Make code changes
vim crates/rivellum-execution/src/lib.rs

# Rebuild and restart
# (Ctrl+C to stop sandbox)
cargo build --release
make sandbox-reset

2. Testing Transactions

# Terminal 1: Sandbox
make sandbox

# Terminal 2: Submit intents
cd examples/payments
node index.js

# Terminal 3: Monitor logs
tail -f .rivellum-sandbox/ledger.log

3. Contract Development

# Write your contract
cd my-contract
cargo build --target wasm32-unknown-unknown --release

# Test deployment
cd ../examples/contract-call
# Edit index.js to use your bytecode
npm start

Next Steps

• Read the whitepaper: WHITEPAPER.md
• Architecture guide: ARCHITECTURE.md
• Contract development: CONTRACTS.md
• Join the community: Discord

Quick Reference

Makefile Commands

make help              # Show all commands
make sandbox           # Start sandbox
make sandbox-reset     # Reset and restart
make demo-payments     # Run payments demo
make demo-contract     # Run contract demo
make install-demos     # Install demo dependencies
make quickstart        # Full setup (build + install)

Sandbox Flags

--reset                # Wipe previous data
--port <PORT>          # Custom RPC port (default: 8080)
--with-pouw            # Enable PoUW worker

Important Addresses

Note: Alice, Bob, and Charlie are pre-funded in genesis but private keys are examples.

File Locations

• Node binary: ./target/release/rivellum-node
• Wallet binary: ./target/release/natos-wallet
• Sandbox data: ./.rivellum-sandbox/
• Payment demo: ./examples/payments/
• Contract demo: ./examples/contract-call/

Happy building! 🚀

If you run into issues, check the FAQ or ask in Discord.