Hero Ledger

A NEAR-compatible blockchain with its own network, validators, and token economy.

• 9 Smart Contracts: SPORE, GLD, USDH tokens, SPOREX exchange, DNS, Credit Vault, Groups, KVS, Hosting
• heroledger CLI: Command-line interface for all operations
• Rhai Scripting: Automation and testing scripts

Quick Start

Prerequisites: make and curl must be installed.

# Ubuntu/Debian
sudo apt-get install make curl

# macOS
xcode-select --install  # includes make
brew install curl       # if needed

Bootstrap (From Nothing)

git clone https://forge.ourworld.tf/geomind_research/hero_ledger.git
cd hero_ledger
make bootstrap

This will:

1. Install system packages (Ubuntu/Debian only)
2. Install Rust and cargo-near
3. Build all contracts and CLI
4. Install binaries to ~/hero/bin
5. Start local chain and deploy contracts

Development Workflow

make setup           # Install dependencies (once)
make build           # Build debug binary (fast)
make install         # Build and install to ~/hero/bin
make test            # Run smoke + full tests

For optimized builds:

make build-release   # Build release binary
make install-release # Install release binary

Available Targets

make help            # Show all targets

# Setup
make setup           # Install system packages, Rust, cargo-near

# Build
make build           # Debug build (contracts + CLI)
make build-release   # Release build (optimized)
make build-contracts # Build WASM contracts only
make check           # Fast syntax check
make fmt             # Format code
make lint            # Run clippy

# Install
make install         # Debug build to ~/hero/bin
make install-release # Release build to ~/hero/bin

# Chain Management
make bootstrap       # Full setup from nothing
make chain-init      # Initialize single-node chain
make chain-destroy   # Destroy local chain and clean up

# Testing
make test            # Run all tests
make test-smoke      # Quick smoke test
make test-full       # Full system test
make test-unit       # Rust unit tests

make clean           # Remove build artifacts

---

CLI Usage

# Account operations
heroledger list                              # List accounts
heroledger <account> info                    # Account details
heroledger <account> send SPORE 100 <to>     # Send tokens

# SPOREX Exchange
heroledger <account> x rates                 # View rates
heroledger <account> x fund SPORE 100        # Deposit
heroledger <account> x withdraw SPORE 50     # Withdraw

# KVS (Key-Value Store)
heroledger kvs namespaces                    # List namespaces
heroledger <account> kvs create myapp.config # Create namespace
heroledger <account> kvs set myapp.config key value

# DNS
heroledger dns available example.hero        # Check availability
heroledger <account> dns register example.hero 12  # Register for 12 months

# Groups
heroledger groups list                       # List groups
heroledger <account> groups create mygroup "Description"

# Credit Vault
heroledger credit spenders                   # List spenders
heroledger <account> credit deposit bucket1 100

Run heroledger --help for full command reference.

---

Smart Contracts

Contract	Address	Purpose
SPORE	my_spore.test.hero	Primary token (10B supply, NEP-141/NEP-148)
GLD	my_gld.test.hero	Digital Gold token
USDH	my_usdh.test.hero	USD stablecoin
SPOREX	sporex.test.hero	Token exchange
DNS	my_dns.test.hero	Domain registration
Credit	my_credit.test.hero	Pull-based payments
Groups	my_groups.test.hero	Group management
KVS	kvs.test.hero	Key-value storage
Hosting	my_hosting.test.hero	Infrastructure registry

---

Rhai Scripting

Automate workflows with Rhai scripts:

near_localnet("http://localhost:3030");
near_accounts_dir("./accounts");

let alice = account("my_test_1");
print(`Balance: ${alice.balance_near()} NEAR`);

token_send()
    .from("my_test_1")
    .to("my_test_2")
    .amount(100)
    .token("spore")
    .execute();

Run scripts:

heroledger my_script.rhai
heroledger rhaitests/smoke/test_smoke.rhai      # 9 smoke tests
heroledger rhaitests/system/test_full_system.rhai  # 35 system tests

See the Rhai scripting module in src/rhai/ for more examples.

---

Testing

make test              # Run smoke + full tests
make test-smoke        # Quick smoke test
make test-full         # Full system test
make test-unit         # Rust unit tests

---

Project Structure

hero_ledger/
├── contracts/           # 9 smart contracts
├── src/                 # SDK and CLI source
│   ├── bin/             # CLI binaries
│   ├── rhai/            # Rhai scripting engine
│   └── ...
├── rhaitests/           # Test scripts
├── examples/            # Rhai and Rust examples
├── docker/              # Docker configuration
└── docs/                # Documentation

---

Docker

For containerized deployments, see docker/README.md.

make docker-build-full   # Build full image with neard
make docker-test-full    # Build and run all tests
make docker-build-cli    # Build CLI-only image

---

Documentation

• docs/SETUP.md - Detailed setup guide
• docs/CLI_REFERENCE.md - Full CLI command reference
• docs/TESTING.md - Testing guide
• docs/DEPLOYMENT.md - Deployment guide
• docs/TROUBLESHOOTING.md - Common issues and solutions
• docs/ARCHITECTURE.md - System design
• docker/README.md - Docker documentation