Skip to main content

​
Local Development

The xyz localnet command provides a complete local blockchain environment for development and testing.

​
Why Localnet?

BenefitDescription
Fast iterationNo waiting for testnet blocks
Free transactionsNo need for testnet tokens
Full controlReset state anytime
Offline developmentNo network required

​
What’s Included

When you start localnet, you get:
  • Full XYZ Chain node running locally
  • Pre-funded test accounts (alice, bob)
  • All APIs (RPC, REST, gRPC)
  • WASM contracts enabled for smart contracts

​
Architecture

┌─────────────────────────────────────────────────────────┐
│                    xyz localnet                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   xyzd      │  │  Consensus  │  │   Network   │    │
│  │   (app)     │◀─│   (BFT)    │◀─│   (P2P)     │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
│         │                                               │
│         ▼                                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │                   APIs                           │   │
│  ├─────────────┬─────────────┬─────────────────────┤   │
│  │ RPC :26657  │ REST :1317  │ gRPC :9090          │   │
│  └─────────────┴─────────────┴─────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

​
Quick Start

# Start localnet
xyz localnet start

# In another terminal, check it's running
xyz localnet status

# Use test accounts
xyz balance --key alice
xyz balance --key bob

# When done
xyz localnet stop

​
Endpoints

ServiceURLPurpose
RPChttp://localhost:26657Transactions, blocks, consensus
REST APIhttp://localhost:1317Chain state queries
gRPClocalhost:9090Programmatic access

​
Test Accounts

Localnet comes with pre-funded accounts:
NameBalancePurpose
alice1,000,000 XYZPrimary test account
bob500,000 XYZSecondary test account
These accounts are automatically available in your keyring when localnet starts.

​
Data Directory

Localnet stores data in ~/.xyz-localnet/: 
~/.xyz-localnet/
├── config/
│   ├── genesis.json    # Chain genesis
│   ├── config.toml     # Node configuration
│   └── app.toml        # App configuration
├── data/
│   └── ...             # Chain state
└── keyring-test/
    └── ...             # Test account keys

​
Reset State

To start fresh: 
# Stop if running
xyz localnet stop

# Remove data
rm -rf ~/.xyz-localnet

# Start fresh
xyz localnet start

​
Development Workflow

​
1. Start Localnet

xyz localnet start

​
2. Deploy Contract

xyz program deploy artifacts/my_contract.wasm \
  --from alice \
  --label "Test Contract"

​
3. Interact

# Query
xyz program query xyz1contract... '{"get_count":{}}'

# Execute
xyz program execute xyz1contract... '{"increment":{}}' --from alice

​
4. Iterate

Make changes and redeploy: 
xyz program build
xyz program deploy artifacts/my_contract.wasm --from alice --label "Test v2"

​
5. Reset When Needed

xyz localnet stop
rm -rf ~/.xyz-localnet
xyz localnet start

​
Troubleshooting

Another process is using port 26657, 1317, or 9090:
# Find and kill the process
lsof -i :26657
kill -9 <PID>

# Or stop any running localnet
xyz localnet stop
Try resetting:
xyz localnet stop
rm -rf ~/.xyz-localnet
xyz localnet start
Ensure localnet is running:
xyz localnet status
Test accounts are only available when localnet is active.

​
Next Steps