Prerequisites & Environment

In this guide, you will set up a complete development environment for building applications on Yellow Network.

Goal: Have a working local environment ready for Yellow App development.

---

System Requirements

Requirement	Minimum	Recommended
Node.js	18.x	20.x or later
npm/yarn/pnpm	Latest stable	Latest stable
Operating System	macOS, Linux, Windows	macOS, Linux

---

Required Knowledge

Before building on Yellow Network, you should be comfortable with:

Topic	Why It Matters
JavaScript/TypeScript	SDK and examples are in TypeScript
Async/await patterns	All network operations are asynchronous
Basic Web3 concepts	Wallets, transactions, signatures
ERC-20 tokens	Fund management involves token operations

:::tip New to Web3? If you're new to blockchain development, start with the Ethereum Developer Documentation to understand wallets, transactions, and smart contract basics. :::

---

Step 1: Install Node.js

macOS (using Homebrew)

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@20

# Verify installation
node --version  # Should show v20.x.x
npm --version   # Should show 10.x.x

Linux (Ubuntu/Debian)

# Install Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Windows

Download and run the installer from nodejs.org.

---

Step 2: Install Core Dependencies

Create a new project and install the required packages:

# Create project directory
mkdir yellow-app && cd yellow-app

# Initialize project
npm init -y

# Install core dependencies
npm install @erc7824/nitrolite viem

# Install development dependencies
npm install -D typescript @types/node tsx

Package Overview

Package	Purpose
@erc7824/nitrolite	Yellow Network SDK for state channel operations
viem	Modern Ethereum library for wallet and contract interactions
typescript	Type safety and better developer experience
tsx	Run TypeScript files directly

---

Step 3: Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Update package.json:

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

---

Step 4: Set Up Environment Variables

Create .env for sensitive configuration:

# .env - Never commit this file!

# Your wallet private key (for development only)
PRIVATE_KEY=0x...

# RPC endpoints
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
BASE_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_KEY

# Clearnode WebSocket endpoint
# Production: wss://clearnet.yellow.com/ws
# Sandbox: wss://clearnet-sandbox.yellow.com/ws
CLEARNODE_WS_URL=wss://clearnet-sandbox.yellow.com/ws

Add to .gitignore:

# .gitignore
.env
.env.local
node_modules/
dist/

Install dotenv for loading environment variables:

npm install dotenv

---

Step 5: Wallet Setup

Development Wallet

For development, create a dedicated wallet:

// scripts/create-wallet.ts
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';

const privateKey = generatePrivateKey();
const account = privateKeyToAccount(privateKey);

console.log('New Development Wallet');
console.log('----------------------');
console.log('Address:', account.address);
console.log('Private Key:', privateKey);
console.log('\n⚠️  Save this private key securely and add to .env');

Run it:

npx tsx scripts/create-wallet.ts

Get Test Tokens

Yellow Network Sandbox Faucet (Recommended)

For testing on the Yellow Network Sandbox, you can request test tokens directly to your unified balance:

curl -XPOST https://clearnet-sandbox.yellow.com/faucet/requestTokens \
  -H "Content-Type: application/json" \
  -d '{"userAddress":"<your_wallet_address>"}'

Replace <your_wallet_address> with your actual wallet address.

:::tip No On-Chain Operations Needed Test tokens (ytest.USD) are credited directly to your unified balance on the Sandbox Clearnode. No deposit or channel operations are required—you can start transacting immediately! :::

Testnet Faucets (For On-Chain Testing)

If you need on-chain test tokens for Sepolia or Base Sepolia:

Network	Faucet
Sepolia	sepoliafaucet.com
Base Sepolia	base.org/faucet

:::warning Development Only Never use your main wallet or real funds for development. Always create a separate development wallet with test tokens. :::

---

Step 6: Verify Setup

Create src/index.ts to verify everything works:

import 'dotenv/config';
import { createPublicClient, http } from 'viem';
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

async function main() {
  // Verify environment variables
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) {
    throw new Error('PRIVATE_KEY not set in .env');
  }

  // Create account from private key
  const account = privateKeyToAccount(privateKey as `0x${string}`);
  console.log('✓ Wallet loaded:', account.address);

  // Create public client
  const client = createPublicClient({
    chain: sepolia,
    transport: http(process.env.SEPOLIA_RPC_URL),
  });

  // Check connection
  const blockNumber = await client.getBlockNumber();
  console.log('✓ Connected to Sepolia, block:', blockNumber);

  // Check balance
  const balance = await client.getBalance({ address: account.address });
  console.log('✓ ETH balance:', balance.toString(), 'wei');

  console.log('\n🎉 Environment setup complete!');
}

main().catch(console.error);

Run the verification:

npm run dev

Expected output:

✓ Wallet loaded: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
✓ Connected to Sepolia, block: 12345678
✓ ETH balance: 100000000000000000 wei

🎉 Environment setup complete!

---

Project Structure

Recommended folder structure for Yellow Apps:

yellow-app/
├── src/
│   ├── index.ts          # Entry point
│   ├── config.ts         # Configuration
│   ├── client.ts         # VirtualApp client setup
│   ├── auth.ts           # Authentication logic
│   └── channels/
│       ├── create.ts     # Channel creation
│       ├── transfer.ts   # Transfer operations
│       └── close.ts      # Channel closure
├── scripts/
│   └── create-wallet.ts  # Utility scripts
├── .env                  # Environment variables (git-ignored)
├── .gitignore
├── package.json
└── tsconfig.json

---

Supported Networks

To get the current list of supported chains and contract addresses, query the Clearnode's get_config endpoint:

// Example: Fetch supported chains and contract addresses
const ws = new WebSocket('wss://clearnet-sandbox.yellow.com/ws');

ws.onopen = () => {
  const request = {
    req: [1, 'get_config', {}, Date.now()],
    sig: [] // get_config is a public endpoint, no signature required
  };
  ws.send(JSON.stringify(request));
};

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Supported chains:', response.res[2].chains);
  console.log('Contract addresses:', response.res[2].contracts);
};

:::tip Dynamic Configuration The get_config method returns real-time information about supported chains, contract addresses, and Clearnode capabilities. This ensures you always have the most up-to-date network information. :::

---

Next Steps

Your environment is ready! Continue to:

• Key Terms & Mental Models — Understand the core concepts
• Quickstart — Build your first Yellow App
• State Channels vs L1/L2 — Deep dive into state channels

---

Common Issues

"Module not found" errors

Ensure you have "type": "module" in package.json and are using ESM imports.

"Cannot find module 'viem'"

Run npm install to ensure all dependencies are installed.

RPC rate limiting

Use a dedicated RPC provider (Infura, Alchemy) instead of public endpoints for production.

TypeScript errors with viem

Ensure your tsconfig.json has "moduleResolution": "bundler" or "node16".