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/lhumina_code/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

make sure HEROLEDGER_VAULT_SECRET is set

# 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

---

Dioxus app see examples/dioxus-gateway Webassembly client access to the gateway

---

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