Complete Walkthrough: Local Blockchain → Smart Contract → dApp

This walkthrough guides you through connecting all three workspaces to create a complete local development environment. While this documentation assumes you have reviewed the individual workspace guides, we provide key information here for a self-contained experience, with references to more detailed documentation where needed.

Overview

Project Structure

Understanding the workspace structure is crucial for this setup:

• ritoswap
  • local-blockchain
    • .env
    • .env.example
    • package.json
    • config
  • colored-keys
    • .env
    • .env.example
    • hardhat.config.ts
    • package.json
  • dapp
    • .env
    • .env.example
    • package.json
    • prisma
  • ContractAddresses

Step 1: Setting Up Your Local Blockchain

First, we’ll establish the foundation - a local Ethereum PoA blockchain with Blockscout explorer.

Configuration

Navigate to the local-blockchain workspace and set up your environment:

cd local-blockchain
cp .env.example .env

Edit your .env file with these critical settings:

# Network Configuration - THIS MUST MATCH ACROSS ALL WORKSPACES
LOCAL_CHAIN_ID=90999999
BLOCK_TIME=27

# Port Configuration
RPC_PORT=8545
RPC_WS_PORT=8546
BLOCKSCOUT_PORT=4000

# Account Configuration
TEST_ACCOUNT=0xYourWalletAddressHere  # Replace with your wallet address
TEST_ACCOUNT_BALANCE=10000000000000000000000  # 10,000 ETH

Initialize and Launch

# Install dependencies
pnpm install
 
# Initialize the blockchain (creates genesis, keystore, etc.)
pnpm setup-all
 
# Start Geth and Blockscout
pnpm start
 
# Optional: Monitor Geth logs in real-time
pnpm logs:geth

Your local blockchain is now running at:

• RPC Endpoint: http://localhost:8545
• WebSocket: ws://localhost:8546
• Block Explorer: http://localhost:4000

Verify Operation

Test your blockchain connection:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

Step 2: Deploy the Smart Contract

With your blockchain running, deploy the Colored Keys smart contract.

Configure Hardhat

Navigate to the colored-keys workspace:

cd ../colored-keys
cp .env.example .env

Edit your .env file:

# Use YOUR wallet's private key (the one you set as TEST_ACCOUNT)
PRIVATE_KEY=0xYourWalletPrivateKey

# Local blockchain configuration (MUST match local-blockchain settings)
LOCAL_BLOCKCHAIN_RPC=http://localhost:8545
LOCAL_CHAIN_ID=90999999

# Blockscout configuration
BLOCKSCOUT_URL=http://localhost:4000
BLOCKSCOUT_API_URL=http://localhost:4000/api

Deploy Contract

# Install dependencies
pnpm install
 
# Compile the smart contract
pnpm compile
 
# Deploy to local blockchain
pnpm deploy:local-blockchain

The deployment script automatically saves the contract address to ContractAddresses/local_blockchain.json. This file is shared across workspaces.

Verify Deployment

# Check supply and holder status
pnpm check-supply:local-blockchain
 
# Verify on Blockscout (optional)
pnpm verify:local-blockchain

You can also view your deployed contract in Blockscout at http://localhost:4000.

Step 3: Configure and Run the dApp

Now we’ll set up RitoSwap to interact with your deployed contract. The dApp requires extensive infrastructure configuration including database setup, authentication services, API integrations, and various third-party services for full functionality.

Environment Configuration

Navigate to the dapp workspace and configure your environment:

cd ../dapp
cp .env.example .env

Configure your .env file with these essential settings:

# Database (requires PostgreSQL - see full configuration guide)
DATABASE_URL="postgresql://user:password@host:5432/dbname"

# Enable Ritonet (local blockchain) mode
NEXT_PUBLIC_RITONET=true
NEXT_PUBLIC_SEPOLIA=false
NEXT_PUBLIC_ETHEREUM=false

# Ritonet Configuration (MUST match local-blockchain settings)
NEXT_PUBLIC_LOCAL_CHAIN_ID=90999999
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_NAME=RitoNet
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_RPC=http://localhost:8545
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_WSS=ws://localhost:8546
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_EXPLORER_URL=http://localhost:4000
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_EXPLORER_NAME=RitoNet Explorer

# Other required settings (minimal config)
NEXT_PUBLIC_ACTIVATE_REDIS=false
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id
NEXT_PUBLIC_APP_NAME=RitoSwap Local
NEXT_PUBLIC_RANGO_API_KEY=your-rango-key

Initialize and Launch

# Install dependencies
pnpm install
 
# Start the dApp in local blockchain mode
pnpm dev:local-blockchain

The dApp will be available at http://localhost:3000 (or http://0.0.0.0:3000 for network access).

Wallet Configuration

Add Ritonet to Your Wallet

Before using the dApp, configure your wallet to connect to the local blockchain.

In MetaMask or your preferred wallet:

1. Click network dropdown → “Add Network Manually”
2. Enter these details:

Import Your Funded Account

Import the private key for the wallet address you used as TEST_ACCOUNT in the local-blockchain setup. This account has 10,000 ETH for testing.

Using the Complete System

With everything running:

1. Ensure Prerequisites: Local blockchain and Blockscout are running
2. Access the dApp: Navigate to http://localhost:3000
3. Connect Wallet: Select RitoNet network and connect your funded account
4. Mint NFTs: Visit the Mint page to create Colored Keys
5. Monitor Transactions: View all activity in Blockscout at http://localhost:4000

Stopping Services

When finished with development:

# Stop the dApp (Ctrl+C in terminal)
 
# Stop blockchain and explorer
cd ../local-blockchain
pnpm stop

Troubleshooting

Common Issues

“Wrong Network” Errors

• Verify Chain ID (90999999) matches exactly in all three workspaces
• Ensure wallet is switched to RitoNet before connecting
• Clear wallet cache and re-add network if needed

Contract Not Found

• Confirm contract deployment succeeded
• Check ContractAddresses/local_blockchain.json exists
• Verify NEXT_PUBLIC_RITONET=true in dApp .env

No Balance Showing

• Ensure blockchain is running: pnpm status in local-blockchain
• Verify you imported the correct wallet (TEST_ACCOUNT)
• Check that your address was included in genesis allocation

Configuration Issues

• Ensure all required services are configured per the full setup guide
• Verify environment variables are properly set
• Check that all necessary API keys are valid

Getting Help

For detailed information about each component:

Next Steps

Now that your local development environment is running, you can:

• Modify and redeploy the smart contract
• Develop new dApp features with instant feedback
• Test wallet integrations across different devices
• Explore the full token lifecycle: minting, transferring, and burning

Remember to stop all services when not in use to free up system resources.