Hero Ledger: Complete Blockchain Ecosystem

A comprehensive blockchain implementation featuring:

• 8 Smart Contracts: SPORE, GLD, USDH tokens, SPOREX exchange, DNS system, Credit Vault, Groups, and KVS
• heroledger CLI: Pure Rust command-line interface for all operations
• Rhai Scripting: User-friendly scripting language for automation and testing
• Local Development: Complete setup with neard for local blockchain development

🚀 Project Status

Phase	Status	Description
✅ Phase 1	Complete	Core implementation, 101 tests passing
✅ Phase 2	Complete	Security audit, all critical issues fixed
✅ Phase 2.5	Complete	2-of-3 multisig for SPORE governance
🟡 Phase 3	Ready	Testnet deployment
⏳ Phase 4	Pending	Mainnet deployment

• Current State: Ready for testnet deployment
• Security Audit: docs/SECURITY_AUDIT.md - All critical issues resolved
• Roadmap: docs/ROADMAP.md
• Setup Guide: docs/SETUP.md

---

Quick Start

Choose your deployment method:

Method	Best For	Requirements
Download Release	Quick deployment	None
Build from Source	Development, customization	Rust, cargo-near
Docker CLI	Containerized deployment	Docker
Docker Full	Local blockchain node	Docker

---

Option 1: Download Release Binary

Download the heroledger CLI for managing NEAR accounts and interacting with HERO Ledger:

# Download heroledger binary
curl -L https://forge.ourworld.tf/geomind_research/hero_ledger/releases/download/latest/heroledger-linux-x64 -o heroledger
chmod +x heroledger

# List available accounts
./heroledger list

# Run Rhai scripts for automation
./heroledger scripts/examples/

Available Binaries:

Platform	Binary
Linux x64	heroledger-linux-x64
Linux ARM64	heroledger-linux-arm64
macOS x64	heroledger-darwin-x64
macOS ARM64	heroledger-darwin-arm64

---

Option 2: Build from Source

Clone and build everything directly (no Docker needed):

# Clone the repo
git clone https://forge.ourworld.tf/geomind_research/hero_ledger.git
cd hero_ledger

# Install prerequisites (NEAR CLI, screen)
./scripts/deploy/install.sh

# Build contracts and CLI
./scripts/deploy/build.sh

# Start local neard and deploy contracts
./scripts/deploy/setup.sh

# Verify
./target/release/heroledger list

See docs/SETUP.md for detailed developer setup.

---

Option 3: Docker CLI (Lightweight)

Lightweight container with heroledger CLI only (~500MB). Connects to public NEAR RPC.

# Pull the CLI image
docker pull forge.ourworld.tf/geomind_research/hero_ledger_cli:latest

# Or build from source
git clone https://forge.ourworld.tf/geomind_research/hero_ledger.git
cd hero_ledger
docker build -t hero_ledger_cli:latest -f docker/Dockerfile.cli .

# Run heroledger commands
docker run --rm hero_ledger_cli:latest heroledger list
docker run --rm hero_ledger_cli:latest heroledger --help

# Run scripts with mounted accounts
docker run --rm \
  -v $(pwd)/accounts:/app/accounts \
  hero_ledger_cli:latest \
  heroledger scripts/examples/

Best for: Contract deployment, account management, CI/CD pipelines

---

Option 4: Docker Full (with neard)

Complete setup with local NEAR blockchain node (~3-5GB). Includes neard for local development.

# Build from source (takes 30-40 minutes)
git clone https://forge.ourworld.tf/geomind_research/hero_ledger.git
cd hero_ledger
docker build -t hero_ledger_full:latest -f docker/Dockerfile.full .

Running the Container:

# Option A: Run in background with port mapping
docker run -d --name hero_ledger_node -p 3030:3030 hero_ledger_full

# Option B: Run with docker-compose
docker compose -f docker/docker-compose.yml up -d

Testing the CLI (inside container):

# Show CLI help
docker exec hero_ledger_node heroledger --help

# List available accounts
docker exec hero_ledger_node heroledger list

# Check node status (RPC endpoint)
curl http://localhost:3030/status | jq '.sync_info.latest_block_height'

Full CLI Help Output:

heroledger - NEAR Account Management Tool

USAGE:
  heroledger <account> send <token> <amount> <to_account>  # Send tokens
  heroledger <account> info                                 # Account info
  heroledger list                                           # List accounts
  heroledger <script.rhai>                                  # Run Rhai script

SPOREX EXCHANGE (x):
  heroledger <account> x fund/withdraw/position/rates

KVS KEY-VALUE STORE (kvs):
  heroledger kvs get/list/namespaces/info
  heroledger <account> kvs create/set/delete

DNS (dns):
  heroledger dns lookup/available/price/tlds
  heroledger <account> dns register/set/transfer

CREDIT VAULT (credit):
  heroledger credit spenders/bucket
  heroledger <account> credit deposit/withdraw/spend

GROUPS (groups):
  heroledger groups list/info
  heroledger <account> groups create/member/admin

Stopping & Cleanup:

# Stop container
docker stop hero_ledger_node

# Remove container
docker rm hero_ledger_node

# Or with docker-compose
docker compose -f docker/docker-compose.yml down

Best for: Local development, validators, RPC nodes, private networks

Image Comparison:

Feature	hero_ledger_cli	hero_ledger_full
Size	~500MB	~3-5GB
Build time	~5 min	~30-40 min
heroledger CLI	✓	✓
Rhai scripts	✓	✓
neard node	✗	✓
Local blockchain	✗	✓

See docker/README.md for full Docker documentation.

---

Testing

After setup, verify everything works:

1. Quick Verification (Docker Full):

# Start container
docker run -d --name hero_ledger_node -p 3030:3030 hero_ledger_full

# Wait for neard to initialize (10-15 seconds)
sleep 15

# Test CLI help
docker exec hero_ledger_node heroledger --help

# Test account listing
docker exec hero_ledger_node heroledger list

# Test neard RPC
curl -s http://localhost:3030/status | jq '.sync_info'

# Cleanup
docker rm -f hero_ledger_node

2. Rhai Script Tests (when accounts are set up):

# Quick health check (9 tests)
heroledger scripts/tests/test_smoke.rhai

# Comprehensive system tests (31+ tests)
heroledger scripts/tests/test_full_system.rhai

Test	What it validates
test_smoke.rhai	All 8 contracts + all 3 tokens deployed and responding
test_full_system.rhai	Complete system: multisig, transfers, rate limits, KVS, groups

Reset & Node Management

# Clear blockchain data and recreate accounts
./scripts/deploy/setup.sh --reset

# Stop local neard node
screen -X -S neard quit

# Check node status and list accounts
heroledger list

# View neard logs
tail -f ~/.near/neard.log

Deployment Commands

# Local deployment
./scripts/deploy/setup.sh                   # Deploy to local neard
./scripts/deploy/setup.sh --reset           # Reset + deploy fresh

# Testnet deployment
./scripts/deploy/setup_testnet.sh           # Deploy to NEAR testnet

For detailed deployment instructions, see docs/DEPLOYMENT.md.

---

Architecture Overview

System Components

hero_ledger/
├── Smart Contracts (8)
│   ├── Token Contracts: SPORE, GLD, USDH (NEP-141 standard)
│   ├── Exchange: SPOREX (internal trading)
│   ├── DNS: Domain registration with auctions
│   ├── Credit: Pull-based payment system
│   ├── Groups: Hierarchical group management
│   └── KVS: Key-value store with namespaces
├── CLI: heroledger (Pure Rust, ~200KB binary)
├── Rhai Integration: User-friendly scripting engine
└── Setup Tools: Local blockchain orchestration

Network Configuration

• Local Development: http://localhost:3030 (neard)
• Testnet: https://rpc.testnet.near.org
• Mainnet: https://rpc.mainnet.near.org (ready for mainnet)

---

Installation Options

Option 1: Pre-built Binaries (Recommended)

See Quick Start above for downloading and using pre-built binaries.

Option 2: Build from Source (Developers)

For developers who want to modify the code or build from source, see docs/SETUP.md.

This includes:

• Building heroledger CLI from source
• Building neard from source
• Building and deploying smart contracts
• Running the full test suite (101 Rust unit tests)

---

heroledger CLI Usage

Account Management

# List all accounts
heroledger list

# Show account details (NEAR balance, public key, etc.)
heroledger <account> info

# Send tokens between accounts
heroledger <from> send SPORE 100 <to>
heroledger <from> send SPORE 50.5 <to>    # Supports decimals
heroledger <from> send GLD 10.25 <to>

# Check individual token balances
heroledger <account> balance SPORE
heroledger <account> balance GLD

SPOREX Exchange

# View exchange state
heroledger <account> x rates                 # Exchange rates for all tokens
heroledger <account> x position              # Your position (SPORE, USDH, GLD)
heroledger <account> x admins                # List admins

# Trading operations
heroledger <account> x fund SPORE 100        # Deposit SPORE to exchange
heroledger <account> x fund USDH 50.5        # Deposit USDH (supports decimals)
heroledger <account> x withdraw SPORE 25     # Withdraw SPORE

# Admin operations (exchange owner only)
heroledger <admin> x rate USDH 100           # Set rate: 1 USDH = 100 SPORE
heroledger <admin> x admin add <account>     # Add admin
heroledger <admin> x admin remove <account>  # Remove admin

KVS (Key-Value Store)

# Read operations (no account needed)
heroledger kvs get <namespace> <key>         # Get a value
heroledger kvs list <namespace> [prefix]     # List keys (with optional prefix filter)
heroledger kvs namespaces [prefix]           # List all namespaces
heroledger kvs info <namespace>              # Get namespace metadata
heroledger kvs writers <namespace>           # List authorized writers
heroledger kvs admins <namespace>            # List admins

# Write operations (requires account)
heroledger <account> kvs create <namespace>  # Create namespace (you become admin)
heroledger <account> kvs set <ns> <key> <val> # Set a key-value pair
heroledger <account> kvs delete <ns> <key>   # Soft-delete (mark as deleted)

# Admin operations (namespace admin only)
heroledger <admin> kvs writer add <ns> <acct>    # Grant write access
heroledger <admin> kvs writer remove <ns> <acct> # Revoke write access
heroledger <admin> kvs admin add <ns> <acct>     # Transfer admin role
heroledger <admin> kvs admin remove <ns> <acct>  # Remove admin

DNS System

# Query operations (no account needed)
heroledger dns lookup <domain>               # Resolve domain to records (A, AAAA, CNAME, etc.)
heroledger dns available <domain>            # Check if domain is available
heroledger dns price <domain>                # Get registration price in GLD
heroledger dns info <domain>                 # Get owner, expiry, record count
heroledger dns tlds                          # List available TLDs (.hero, .near, .web3)

# Registration (requires GLD tokens)
heroledger <account> dns register <domain> <months>  # Register for N months
heroledger <account> dns renew <domain> <months>     # Extend registration

# Management (domain owner only)
heroledger <account> dns set <domain> <json>         # Set all DNS records
# Example: heroledger my_test_1 dns set example.hero '{"A":"192.0.2.1","TXT":"v=spf1 ~all"}'
heroledger <account> dns transfer <domain> <to>      # Transfer ownership

# Auctions (for premium/short domains)
heroledger <account> dns auction start <domain>      # Start auction
heroledger <account> dns auction bid <domain>        # Place a bid
heroledger <account> dns auction claim <domain>      # Claim won auction

Credit Vault

# View operations (no account needed)
heroledger credit bucket <owner> <bucket_id>        # Get bucket info
heroledger credit balance <owner> <bucket_id>       # Get remaining balance
heroledger credit spenders                          # List authorized spenders

# Owner operations (bucket owner only)
heroledger <account> credit deposit <bucket_id> <amount>    # Deposit GLD to bucket
heroledger <account> credit withdraw <bucket_id> <amount>   # Withdraw GLD
heroledger <account> credit spender add <account>           # Authorize spender
heroledger <account> credit spender remove <account>        # Revoke spender

# Spender operations (authorized spender only)
heroledger <spender> credit spend <owner> <bucket> <amount> <desc>  # Spend from bucket

Groups

# Query operations (no account needed)
heroledger groups list                               # List all groups
heroledger groups info <group_name>                  # Get group metadata
heroledger groups members <group_name>               # List all members
heroledger groups admins <group_name>                # List admins

# Creation & deletion (requires account)
heroledger <account> groups create <name> <desc>     # Create group (you become admin)
heroledger <account> groups delete <name>            # Delete group (must be empty)

# Member management (admin only)
heroledger <admin> groups member add <group> <member> <role>  # Add member
heroledger <admin> groups member remove <group> <member>      # Remove member
heroledger <admin> groups role <group> <member> <role>        # Change role

# Admin management
heroledger <admin> groups admin add <group> <account>    # Grant admin rights
heroledger <admin> groups admin remove <group> <account> # Revoke admin

---

Rhai Scripting

Automate complex workflows with Rhai, an embedded scripting language integrated with NEAR operations.

Why Rhai?

• User-friendly: Clear, readable syntax similar to JavaScript
• Powerful: Full support for loops, functions, error handling
• Safe: Runs in a sandboxed environment
• Fast: Compiled to bytecode, executes efficiently

Basic Example

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

// Load account
let alice = account("my_test_1");
print(`Alice balance: ${alice.balance_near()} NEAR`);

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

print("Transfer complete!");

Available Rhai Modules

Module	Purpose
account	Account management, loading, creation
token	Token transfers and balance queries
contract	Smart contract interaction (view & call)
sporex	SPOREX exchange operations
dns	Domain registration and management
credit	Credit vault operations
groups	Group management operations
kvs	Key-value store operations
admin	Administrative ecosystem setup

Running Scripts

# Run a single script
heroledger my_script.rhai

# Run all scripts in a directory (alphabetically)
heroledger scripts/

# With specific account
heroledger my_test_1 my_script.rhai

Examples

See crates/rhai-near/examples/ for complete examples:

examples/
├── accounts/
│   ├── account_ops.rhai          # Account loading and info
│   ├── admin_setup.rhai          # Admin ecosystem setup
│   └── contract_call.rhai        # Contract interaction
├── credit/
│   ├── approvals.rhai            # Approval workflows
│   ├── create_bucket.rhai        # Create credit buckets
│   ├── fund_and_spend.rhai       # Funding and spending
│   └── manage_spenders.rhai      # Manage spenders
├── dns/
│   ├── auction_premium.rhai      # Domain auctions
│   ├── manage_records.rhai       # DNS record management
│   ├── register_domain.rhai      # Domain registration
│   └── renew_domain.rhai         # Domain renewal
├── groups/
│   └── groups.rhai               # Group operations
├── kvs/
│   └── test_kvs.rhai             # Key-value store
├── sporex/
│   └── sporex_swap.rhai          # Exchange trading
└── tokens/
    ├── spore_multisig.rhai       # SPORE 2-of-3 multisig governance
    └── token_transfer.rhai       # Token distribution

---

Smart Contracts

Token Contracts (NEP-141 Standard)

Token	Symbol	Decimals	Address	Purpose
SPORE	SPORE	18	my_spore.test.near	Primary utility token (10B supply, 2-of-3 multisig governance)
GLD	GLD	18	my_gld.test.near	Digital Gold for premium services
USDH	USDH	18	my_usdh.test.near	USD stablecoin

All tokens use 18 decimal places for maximum precision.

SPOREX Exchange

Address: my_sporex.test.near

Features:

• Internal token trading (SPORE ↔ USDH ↔ GLD)
• Configurable exchange rates
• User positions (balances per token)
• Admin rate management

Pricing Formula: 1 USDH = N SPORE (admin-configurable)

DNS System

Address: my_dns.test.near Payment Token: GLD

Features:

• Domain registration under TLDs (.hero, .near, .web3)
• Dynamic pricing based on domain length
• On-chain DNS records (A, AAAA, CNAME, MX, TXT)
• Premium domain auctions
• Domain renewal and transfer

Pricing (GLD per month):

• 10+ chars: 0.1 GLD
• 5 chars: 5 GLD
• 4 chars: 10 GLD (auction required)
• 3 chars: 25 GLD (auction required)
• 2 chars: 100 GLD (auction required)
• 1 char: 500 GLD (auction required)

Credit Vault

Address: my_credit.test.near

Features:

• Per-account credit buckets
• Pull-based spending authorization
• Transaction descriptions for auditing
• Granular spender management

Use Cases:

• API consumption tracking
• Service subscription management
• Expense authorization workflows

Groups

Address: my_groups.test.near

Features:

• Hierarchical group structure
• Nested membership (groups within groups)
• Role-based access (Viewer, Contributor, Member, Coordinator)
• Group admins and coordinators
• DNS name association

Roles (in order of privilege):

Role	Description
Viewer	Read-only access
Contributor	Can contribute content
Member	Standard member
Coordinator	Can manage members (not other coordinators)

KVS (Key-Value Store)

Address: my_kvs.test.near

Features:

• Namespace isolation
• Granular access control (admins, writers)
• Efficient key-value storage
• Prefix-based queries

Use Cases:

• Application configuration
• User metadata storage
• Feature flags
• Audit logs

---

Account Management

Default Accounts (15 total)

Admin Account (1)

• my_admin_x.test.near - System administrator

Token Contracts (3)

• my_spore.test.near - SPORE token (multisig: 2/3)
• my_gld.test.near - GLD token
• my_usdh.test.near - USDH token

System Contracts (5)

• my_sporex.test.near - SPOREX exchange
• my_dns.test.near - DNS system
• my_credit.test.near - Credit Vault
• my_groups.test.near - Groups
• my_kvs.test.near - Key-value store

Signers (3 for multisig)

• my_sig_1.test.near - Multisig signer 1
• my_sig_2.test.near - Multisig signer 2
• my_sig_3.test.near - Multisig signer 3

Test Accounts (3)

• my_test_1.test.near - User account 1
• my_test_2.test.near - User account 2
• my_test_3.test.near - User account 3

Account Storage

All account credentials stored in accounts/ directory:

accounts/
├── my_spore/
│   ├── credentials.json    # Full credentials (account ID, keys)
│   ├── public_key.txt      # Public key only
│   └── private_key.txt     # Private key only
├── my_test_1/
│   ├── credentials.json
│   ├── public_key.txt
│   └── private_key.txt
└── ...

Account Security

Important: Private keys are stored locally only for development. In production:

• Use hardware wallets
• Use NEAR Wallet browser extension
• Never commit private keys to version control
• Use .gitignore for /accounts/ directory

---

Development

Node Management

# Start neard in screen session
cargo run -p setup -- node

# Stop neard
cargo run -p setup -- stop-node

# Check neard status
cargo run -p setup -- node-status

# View neard logs
cargo run -p setup -- attach-node
# Press Ctrl+a then d to detach

Building Contracts

# Build all contracts
./scripts/deploy/build.sh

# Build individual contract
cargo near build --manifest-path contracts/spore/Cargo.toml

# Build with optimizations
CARGO_PROFILE_RELEASE_OPT_LEVEL=z cargo near build

Running Tests

# Run unit tests
cargo test --lib

# Run integration tests
cargo test --test integration_tests

# Run with verbose output
cargo test -- --nocapture

# Run specific test
cargo test test_name

---

Testing

Quick Reference: See Quick Start > Testing for the simplest way to verify your installation.

Test Strategy

HERO Near uses a three-tier testing approach:

Tier	Command	Purpose	Time
1. Rust Tests	cargo test --all	100 unit & integration tests	~1 min
2. Smoke Tests	heroledger scripts/tests/test_smoke.rhai	9 contract deployment tests	~1 min
3. Full E2E	heroledger scripts/tests/test_cli_full.rhai	20 CLI end-to-end tests	~2 min

Tier 1: Rust Unit & Integration Tests

cargo test --all runs 100 tests across all packages:

Package	Tests	What's tested
dns	12	Pricing, validation, domain parsing, record creation
groups	14	Group CRUD, roles, hierarchy, DNS, linking
rhai-near	59	Engine, context, script parsing, all Rhai examples
setup	9	RPC formatting, node/mcp managers, account docs
sporex	2	Exchange rates, precision
spore/gld/usdh	3	Token supply tests
kvs	1	Name validation

# Run ALL Rust tests (recommended)
cargo test --all

# Run with verbose output
cargo test --all -- --nocapture

# Run specific package tests only
cargo test -p dns
cargo test -p groups

# Run specific test
cargo test context::tests

Tier 2: Contract Smoke Tests

Validates all 8 contracts are deployed and responsive:

heroledger scripts/tests/test_smoke.rhai

Tests: SPORE, GLD, USDH tokens, SPOREX exchange, DNS, Credit, Groups, KVS

Tier 3: Full End-to-End Tests

Comprehensive CLI test suite with 30+ test cases:

heroledger scripts/tests/test_cli_full.rhai

Tests include:

• Account management (list, info, balances)
• Token operations (transfers, balance checks)
• KVS (create namespace, set/get values)
• SPOREX (fund, rates, positions)
• DNS (register, lookup, records)
• Groups (create, add members)
• Credit (buckets, spenders)

Test Coverage

Current coverage (January 2026):

• ✅ 100/100 Rust tests passing (cargo test --all)
  • 59 rhai-near tests (unit + integration + script validation)
  • 12 DNS contract tests
  • 14 Groups contract tests
  • 9 setup/CLI tests
  • 6 token/exchange tests (spore, gld, usdh, sporex, kvs)
• ✅ 9/9 smoke tests passing (scripts/tests/test_smoke.rhai)
• ✅ 20/20 CLI tests passing (scripts/tests/test_cli_full.rhai)
• ✅ 15+ Rhai example scripts

Adding New Tests

Create test file at tests/your_test.rs:

#[test]
fn test_feature() {
    let engine = create_engine();
    engine.run("near_testnet();").unwrap();
    // Your test here
}

---

Troubleshooting

Setup Issues

Problem: neard fails to start

# Check if port 3030 is available
lsof -i :3030

# Kill existing process
pkill -f neard

# Try setup again
./scripts/deploy/setup.sh

Problem: Cargo dependencies won't resolve

# Clear cargo cache
cargo clean

# Update dependencies
cargo update

# Try building again
cargo build

Problem: Script execution fails

# Verify network is running
curl http://localhost:3030/status

# Check account directory exists
ls -la accounts/

# Verify account credentials
cat accounts/my_test_1/credentials.json

Runtime Issues

Problem: "Account not found"

• Verify account exists: heroledger list
• Check credentials file: cat accounts/<account>/credentials.json
• Ensure network is running: curl http://localhost:3030/status

Problem: "Insufficient balance"

• Check account balance: heroledger <account> info
• Send NEAR from another account: heroledger my_test_1 send my_test_2 100

Problem: "Contract not found"

• Verify deployment: Check my_dns.test.near, etc.
• Re-deploy contracts: ./scripts/deploy/setup.sh

Testing Issues

Problem: Tests fail with "context not initialized"

• Ensure near_localnet() called before using context
• Check test has proper setup

Problem: Rhai script syntax error

• Check script has semicolons after statements
• Verify variable assignments: let x = value;
• Use print() for debugging

Problem: Scripts fail with permission denied

• Make scripts executable: chmod +x ./scripts/deploy/*.sh

---

Project Structure

The project is organized into three main directories:

Main Directories

hero_ledger/
├── contracts/              # Smart contracts (8 total) - See contracts/README.md
├── setup/                  # CLI tool and deployment - See setup/README.md
├── sdk/                    # Rust SDK for integration - See sdk/instructions.md
├── crates/rhai-near/       # Rhai scripting engine
├── scripts/                # Deployment and test scripts
├── docs/                   # Documentation
└── accounts/               # Account credentials (15 accounts)

Full Structure

hero_ledger/
├── README.md                 # This file
├── Makefile                  # Optional convenience wrapper (see Makefile Reference)
├── Cargo.toml                # Workspace manifest
├── Cargo.lock                # Dependency lock file
├── .gitignore                # Git ignore rules
├── .mcp.json                 # MCP server configuration
│
├── contracts/                # Smart contracts (8 total)
│   ├── README.md            # Smart contract documentation
│   ├── spore/               # SPORE token (2-of-3 multisig)
│   ├── gld/                 # GLD token
│   ├── usdh/                # USDH token
│   ├── sporex/              # SPOREX exchange (10% rate limit)
│   ├── dns/                 # DNS system (auctions, records)
│   ├── credit/              # Credit Vault (buckets)
│   ├── groups/              # Groups (hierarchy, SPEC.md)
│   └── kvs/                 # Key-value store (SPECIFICATION.md)
│
├── setup/                    # Setup and CLI tools
│   ├── README.md            # Setup package documentation
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs          # Setup orchestrator
│       ├── lib.rs           # Library exports
│       ├── accounts.rs      # Account management
│       ├── blockchain.rs    # Blockchain operations
│       ├── cmd.rs           # CLI commands
│       ├── config.rs        # Configuration types
│       ├── display.rs       # Output formatting
│       ├── mcp.rs           # MCP server integration
│       ├── node_deploy.rs   # neard management
│       ├── rpc.rs           # RPC client utilities
│       ├── setup.rs         # Setup orchestration
│       ├── bin/
│       │   └── heroledger.rs  # CLI entry point
│       ├── credit/          # Credit contract deployment
│       ├── dns/             # DNS contract deployment
│       ├── groups/          # Groups contract deployment
│       ├── kvs/             # KVS contract deployment
│       └── sporex/          # SPOREX contract deployment
│
├── sdk/                      # Rust SDK for Hero Ledger
│   ├── instructions.md      # SDK build instructions and usage
│   └── (SDK implementation - TBD)
│
├── crates/
│   └── rhai-near/           # Rhai scripting engine
│       ├── Cargo.toml
│       ├── README.md
│       ├── SPEC.md          # Complete API specification
│       ├── src/
│       │   ├── lib.rs       # Main library
│       │   ├── context.rs   # Execution context
│       │   ├── error.rs     # Error types
│       │   ├── rpc.rs       # RPC utilities
│       │   ├── account/     # Account module
│       │   ├── admin/       # Admin module
│       │   ├── contract/    # Contract interaction
│       │   ├── credit/      # Credit module
│       │   ├── dns/         # DNS module
│       │   ├── groups/      # Groups module
│       │   ├── kvs/         # KVS module
│       │   ├── sporex/      # SPOREX module
│       │   └── token/       # Token module
│       ├── examples/        # 15+ example scripts
│       │   ├── accounts/    # Account operations
│       │   ├── credit/      # Credit examples
│       │   ├── dns/         # DNS examples
│       │   ├── groups/      # Groups examples
│       │   ├── kvs/         # KVS examples
│       │   ├── sporex/      # Exchange examples
│       │   └── tokens/      # Token examples
│       └── tests/
│           ├── integration_tests.rs
│           └── rhai_scripts_test.rs
│
├── scripts/                  # Deployment scripts and tests
│   ├── README.md
│   ├── deploy/              # Deployment scripts
│   │   ├── README.md
│   │   ├── install.sh       # Install dependencies
│   │   ├── setup.sh         # Local deployment
│   │   ├── setup_testnet.sh # Testnet deployment
│   │   └── build.sh         # Build CLI binary
│   ├── tests/               # Rhai test suites
│   │   ├── README.md
│   │   ├── test_smoke.rhai          # Quick deployment check
│   │   ├── test_cli_full.rhai       # CLI operations test
│   │   ├── test_full_system.rhai    # Comprehensive system test
│   │   ├── test_groups_api.rhai     # Groups API tests
│   │   └── test_kvs.rhai            # KVS tests
│   └── examples/            # Rhai tutorials
│       ├── README.md
│       ├── DNS_RHAI_QUICK_START.md
│       ├── 01_setup.rhai
│       ├── 02_accounts.rhai
│       └── dns_*.rhai       # DNS examples
│
├── accounts/                 # Account credentials (15 accounts)
│   ├── my_admin_x/          # Admin account
│   ├── my_spore/            # SPORE token
│   ├── my_gld/              # GLD token
│   ├── my_usdh/             # USDH token
│   ├── my_sporex/           # SPOREX exchange
│   ├── my_dns/              # DNS system
│   ├── my_credit/           # Credit Vault
│   ├── my_groups/           # Groups
│   ├── my_kvs/              # Key-value store
│   ├── my_sig_1/            # Multisig signer 1
│   ├── my_sig_2/            # Multisig signer 2
│   ├── my_sig_3/            # Multisig signer 3
│   ├── my_test_1/           # Test account 1
│   ├── my_test_2/           # Test account 2
│   └── my_test_3/           # Test account 3
│
└── docs/                     # Documentation
    ├── ARCHITECTURE.md      # System architecture
    ├── DEPLOYMENT.md        # Deployment guide
    ├── MULTISIG_DESIGN.md   # Multisig specification
    ├── ROADMAP.md           # Project roadmap
    ├── SECURITY_AUDIT.md    # Security findings
    ├── SETUP.md             # Setup guide
    └── RELEASE.md           # Release process

---

Makefile Reference (Optional)

For users who prefer make, a Makefile is provided as a convenience wrapper around the shell scripts:

Task	Make Command	Script Equivalent
Install dependencies	make install	./scripts/deploy/install.sh
Build contracts	make build	./scripts/deploy/build.sh
Deploy to local	make deploy-local	./scripts/deploy/setup.sh
Deploy fresh	make deploy-local-fresh	./scripts/deploy/setup.sh --reset
Deploy to testnet	make deploy-testnet	./scripts/deploy/setup_testnet.sh
Run all tests	make test	heroledger scripts/tests/test_smoke.rhai && heroledger scripts/tests/test_full_system.rhai
Run smoke test	make test-smoke	heroledger scripts/tests/test_smoke.rhai
Run full test	make test-full	heroledger scripts/tests/test_full_system.rhai
Run Rust tests	make test-unit	cargo test --all
Check status	make status	heroledger list
View logs	make logs	tail -f ~/.near/neard.log
Stop node	make stop	screen -X -S neard quit
Show help	make help	N/A

# Quick start with make (requires make installed)
make quick-start    # Equivalent to: install.sh + setup.sh --install-neard + build.sh

---

Key Features

• ✅ 8 Smart Contracts - Complete DeFi ecosystem
• ✅ Pure Rust CLI - No shell dependencies (~200KB binary)
• ✅ Rhai Scripting - User-friendly automation
• ✅ Local Development - Complete neard setup
• ✅ Multisig Support - 2/3 threshold for SPORE token
• ✅ Type Safety - All amounts use u128 (no floating point)
• ✅ Access Control - Role-based and owner-based permissions
• ✅ Comprehensive Docs - README, SETUP, SPEC, examples

---

Validation & Safety

All operations validate:

• ✅ Amounts: Non-negative, non-zero, maximum 18 decimals
• ✅ Accounts: Exist on-chain before operations
• ✅ Balances: Sufficient funds before transfers
• ✅ Permissions: Correct admin/owner for privileged ops
• ✅ Contracts: Deployed and responding

---

Documentation

Core Documentation

• SETUP.md - Detailed setup and installation guide
• TESTING.md - Testing guide and pre-release tests
• ARCHITECTURE.md - System architecture and design
• DEPLOYMENT.md - Deployment guide for various environments

Release & Operations

• RELEASE_PROCESS.md - Quick reference for creating releases
• RELEASE.md - Binary release guide (git tags, automated workflow)
• PACKAGES.md - Container package publishing (Docker registry)
• DOCKER.md - Docker container usage and examples
• Docker README - Docker image deployment

Development

• ROADMAP.md - Project roadmap and future plans
• MULTISIG_DESIGN.md - Multisig specification
• SECURITY_AUDIT.md - Security findings and best practices

---

License

This project is part of the HERO ecosystem.

---

Support

For issues, questions, or contributions:

1. Check existing documentation (see Documentation section above)
2. Review example scripts in scripts/examples/
3. Check test cases in scripts/tests/
4. Open an issue on the repository

---

Last Updated: 2026-01-03 Rhai Integration: v0.1.0 NEAR SDK: v5.24.0