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

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.

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

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         # Nitrolite 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);
};

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".