# Development Environment

**Module 1: Setting Up Your BSV Development Environment**

This module guides you through setting up your development environment for BSV blockchain development. The setup differs depending on whether you're building backend services or frontend dApps.

***

## Universal Prerequisites

**Required for both paradigms:**

* Computer running Windows, macOS, or Linux
* Basic command line knowledge
* Text editor or IDE (VS Code recommended)
* Node.js 18+ and npm

***

## Part 1: Universal Setup (Both Paradigms)

### Step 1: Install Node.js

The BSV TypeScript SDK requires Node.js version 18 or higher.

#### macOS

```bash
# Using Homebrew
brew install node

# Verify installation
node --version  # Should be v18.0.0 or higher
npm --version
```

#### Windows

1. Download installer from [nodejs.org](https://nodejs.org/) (LTS version)
2. Run the installer
3. Verify in Command Prompt:

```cmd
node --version
npm --version
```

#### Linux (Ubuntu/Debian)

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

# Verify installation
node --version
npm --version
```

### Step 2: Install TypeScript

```bash
# Install TypeScript globally
npm install -g typescript

# Verify installation
tsc --version  # Should be 5.0.0 or higher
```

### Step 3: Set Up Your IDE

We recommend **Visual Studio Code** for TypeScript development:

1. Download from [code.visualstudio.com](https://code.visualstudio.com/)
2. Install these essential extensions:
   * **ESLint**: Code quality and linting
   * **Prettier**: Automatic code formatting
   * **TypeScript Import Sorter**: Organize imports
   * **GitLens**: Git integration and history

#### VS Code Settings

Create `.vscode/settings.json` in your project:

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }
}
```

### Step 4: Install BSV SDK

```bash
# Create project directory
mkdir my-bsv-app
cd my-bsv-app

# Initialize npm project
npm init -y

# Install BSV SDK (core dependency)
npm install @bsv/sdk

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

# Install dotenv for environment variables
npm install dotenv
```

### Step 5: Configure TypeScript

Create `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### Step 6: Set Up Git (Recommended)

```bash
# Initialize git repository
git init

# Create .gitignore
cat > .gitignore << 'EOF'
node_modules/
dist/
.env
.env.local
*.log
.DS_Store
.vscode/
.idea/
EOF

# First commit
git add .
git commit -m "Initial BSV project setup"
```

***

## Part 2A: Backend/Service Development Setup

**For custodial applications where you control private keys**

### Backend Project Structure

```bash
# Create backend directories
mkdir -p src/config
mkdir -p src/services
mkdir -p src/models
mkdir -p src/utils
mkdir -p src/api
```

```
my-bsv-backend/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config/
│   │   ├── database.ts       # Database configuration
│   │   └── wallet.ts         # Wallet configuration
│   ├── services/
│   │   ├── wallet.service.ts # Wallet management logic
│   │   └── payment.service.ts# Payment processing
│   ├── models/
│   │   ├── wallet.model.ts   # Wallet data model
│   │   └── transaction.model.ts
│   ├── utils/
│   │   └── crypto.ts         # Cryptographic utilities
│   └── api/
│       └── routes.ts         # API endpoints
├── dist/                     # Compiled output (gitignored)
├── node_modules/             # Dependencies (gitignored)
├── .env                      # Environment variables (gitignored)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

### Install Backend Dependencies

```bash
# Install additional backend dependencies
npm install express dotenv
npm install -D @types/express @types/dotenv
```

### Environment Variables (Backend)

Create `.env` file:

```env
# NEVER COMMIT THIS FILE!

# Network
NETWORK=testnet  # or mainnet

# Database (example with MongoDB)
DATABASE_URL=mongodb://localhost:27017/bsv-app

# API Configuration
PORT=3000
API_SECRET=your-secret-key-here

# Security
ENCRYPTION_KEY=your-encryption-key-here

# Note: Private keys should be stored in secure vault/HSM in production
# For development only:
# MASTER_PRIVATE_KEY_WIF=cVrtH...
```

**⚠️ Security Warning:**

* Never store production private keys in `.env` files
* Use HSM (Hardware Security Module) or key vaults in production
* Always encrypt private keys at rest
* Use strong access controls

### Backend Test File

Create `src/index.ts`:

```typescript
import { PrivateKey, Transaction, P2PKH } from '@bsv/sdk'
import * as dotenv from 'dotenv'

dotenv.config()

async function testBackendSetup() {
  console.log('=== BSV Backend Development Environment Test ===\n')

  // Generate a private key (in production, load from secure storage)
  const privateKey = PrivateKey.fromRandom()
  const publicKey = privateKey.toPublicKey()
  const address = publicKey.toAddress()

  console.log('✅ Private key generated')
  console.log('Private Key (WIF):', privateKey.toWif())
  console.log('Public Key:', publicKey.toString())
  console.log('Address:', address)
  console.log('Network:', process.env.NETWORK || 'testnet')

  // Test transaction creation (won't broadcast without UTXOs)
  const tx = new Transaction()
  console.log('\n✅ Transaction object created')
  console.log('Transaction Version:', tx.version)

  // Test P2PKH template
  const p2pkh = new P2PKH()
  const lockingScript = p2pkh.lock(address)
  console.log('✅ P2PKH locking script created')

  console.log('\n✅ BSV SDK is working correctly!')
  console.log('🚀 Ready for backend development')
  console.log('\n💡 Next: Fund this address with testnet BSV from BSV Desktop wallet')
  console.log('   Download BSV Desktop: https://desktop.bsvb.tech/')
}

testBackendSetup().catch(console.error)

// Run this test: npm run test
```

### Backend NPM Scripts

Update `package.json`:

```json
{
  "name": "my-bsv-backend",
  "version": "1.0.0",
  "scripts": {
    "start": "node dist/index.js",
    "dev": "nodemon --watch src --exec ts-node src/index.ts",
    "build": "tsc",
    "test": "ts-node src/index.ts"
  },
  "dependencies": {
    "@bsv/sdk": "^1.0.0",
    "express": "^4.18.0",
    "dotenv": "^16.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/express": "^4.17.0",
    "@types/dotenv": "^8.2.0",
    "ts-node": "^10.9.0",
    "nodemon": "^3.0.0",
    "typescript": "^5.0.0"
  }
}
```

### Test Backend Setup

```bash
npm run test

# Expected output:
# === BSV Backend Development Environment Test ===
# ✅ Private key generated
# Address: 1A1zP1...
# Network: testnet
# ✅ Transaction object created
# ✅ BSV SDK is working correctly!
# 🚀 Ready for backend development
```

***

## Part 2B: Frontend/dApp Development Setup

**For non-custodial applications using WalletClient**

### Frontend Project Structure (React Example)

```bash
# Create React app with TypeScript
npx create-react-app my-bsv-dapp --template typescript

cd my-bsv-dapp

# Install BSV SDK
npm install @bsv/sdk
```

```
my-bsv-dapp/
├── public/
│   └── index.html
├── src/
│   ├── components/
│   │   ├── WalletConnect.tsx    # Wallet connection UI
│   │   ├── SendPayment.tsx      # Payment component
│   │   └── TransactionList.tsx  # Transaction history
│   ├── services/
│   │   └── wallet.service.ts    # WalletClient wrapper
│   ├── hooks/
│   │   └── useWallet.ts         # React hook for wallet
│   ├── App.tsx                  # Main app component
│   └── index.tsx                # Entry point
├── node_modules/
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

### Install Frontend Dependencies

```bash
# No additional BSV dependencies needed!
# WalletClient is included in @bsv/sdk

# Optional: UI library
npm install @mui/material @emotion/react @emotion/styled
```

### Frontend Test Component

Create `src/components/WalletTest.tsx`:

```typescript
import React, { useState } from 'react'
import { WalletClient } from '@bsv/sdk'

export const WalletTest: React.FC = () => {
  const [wallet, setWallet] = useState<WalletClient | null>(null)
  const [publicKey, setPublicKey] = useState<string>('')
  const [status, setStatus] = useState<string>('Not connected')

  const connectWallet = async () => {
    try {
      setStatus('Connecting...')

      // Initialize WalletClient (auto-detects available wallet substrate)
      const walletClient = new WalletClient('auto')

      // Connect to the wallet substrate
      await walletClient.connectToSubstrate()

      // Get user's identity public key
      const { publicKey: userPubKey } = await walletClient.getPublicKey({
        identityKey: true
      })

      setWallet(walletClient)
      setPublicKey(userPubKey)
      setStatus('Connected')

      console.log('✅ Wallet connected, public key:', userPubKey)
    } catch (error: any) {
      console.error('❌ Connection failed:', error)
      setStatus(`Error: ${error.message}`)
    }
  }

  return (
    <div style={{ padding: '20px' }}>
      <h2>BSV Wallet Connection Test</h2>

      <div>
        <p><strong>Status:</strong> {status}</p>
        {publicKey && (
          <p><strong>Public Key:</strong> {publicKey.substring(0, 20)}...</p>
        )}
      </div>

      {!wallet ? (
        <button onClick={connectWallet}>
          Connect MetaNet Desktop Wallet
        </button>
      ) : (
        <div>
          <p>✅ Wallet connected successfully!</p>
          <p>Your dApp can now request transactions from the user's wallet.</p>
        </div>
      )}

      <div style={{ marginTop: '20px', padding: '10px', background: '#f0f0f0' }}>
        <p><strong>Prerequisites:</strong></p>
        <ul>
          <li>MetaNet Desktop Wallet installed</li>
          <li>Wallet must be unlocked</li>
          <li>Your dApp origin must be authorized</li>
        </ul>
      </div>
    </div>
  )
}
```

### Update App.tsx

```typescript
import React from 'react'
import { WalletTest } from './components/WalletTest'
import './App.css'

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <h1>BSV dApp Development Environment</h1>
        <WalletTest />
      </header>
    </div>
  )
}

export default App
```

### Frontend NPM Scripts

`package.json` (already configured by Create React App):

```json
{
  "name": "my-bsv-dapp",
  "version": "0.1.0",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "dependencies": {
    "@bsv/sdk": "^1.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.0.0"
  }
}
```

### Test Frontend Setup

```bash
npm start

# Browser opens at http://localhost:3000
# Click "Connect MetaNet Desktop Wallet" button
# Wallet popup should appear
# After authorization, should show "✅ Wallet connected successfully!"
```

### MetaNet Desktop Wallet Installation (BSV Desktop)

**Required for frontend development:**

**What is BSV Desktop?** BSV Desktop (formerly MetaNet Desktop Wallet) is a modern wallet designed to make your experience with BSV Blockchain simple, secure, and powerful—whether you're a beginner or an advanced user. It's the standard wallet for BSV application development.

**Download and Setup:**

1. Visit: **<https://desktop.bsvb.tech/>**
2. Download for your OS (Windows, macOS, or Linux)
3. Run the installer and follow the setup wizard
4. Create a new wallet or import existing one
5. Switch to testnet mode for development (Settings → Network → Testnet)

**Getting BSV for Development:**

* **Testnet BSV** (for development): Use the built-in wallet faucet feature or request from [BSV Discord](https://discord.gg/bsv)
* **Mainnet BSV** (for production): [Orange Gateway](https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/get-bsv/orange-gateway) (buy with fiat)

**Key Features for Developers:**

* Multi-network support (mainnet/testnet switching)
* App integration for blockchain applications
* Welcome gift: 99,991 Satoshis to start exploring
* Advanced security with phone-based recovery
* Identity Key and Private Key management for app integration

**Your dApp will connect to this wallet via WalletClient**

**Complete Onboarding Guide:**

* <https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/metanet-desktop-mainnet>

**Documentation:**

* Wallet Toolbox API: <https://fast.brc.dev/>
* BRC Standards: <https://hub.bsvblockchain.org/brc>
* Tech Stack & Resources: <https://hub.bsvblockchain.org/bsv-skills-center>

***

## Part 3: Testing Your Setup

### Backend Test

```bash
cd my-bsv-backend
npm run test
```

**Expected Output:**

```
=== BSV Backend Development Environment Test ===

✅ Private key generated
Address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Network: testnet
✅ Transaction object created
✅ BSV SDK is working correctly!
🚀 Ready for backend development
```

### Frontend Test

```bash
cd my-bsv-dapp
npm start
```

**Expected Behavior:**

1. Browser opens at <http://localhost:3000>
2. Click "Connect MetaNet Desktop Wallet"
3. Wallet popup appears
4. Authorize connection
5. See "✅ Wallet connected successfully!"
6. Public key displayed (truncated for security)

***

## Additional Tools

### Block Explorers

**WhatsOnChain:**

* Mainnet: <https://whatsonchain.com/>
* Testnet: <https://test.whatsonchain.com/>

**Usage:**

* View transactions by TXID
* Check address balances
* Explore blocks and network stats
* Debug transaction issues

### Getting Testnet BSV

Get free testnet BSV for development:

* Use MetaNet Desktop Wallet's built-in faucet feature
* Join [BSV Discord](https://discord.gg/bsv) to request testnet coins from the community
* Use for testing without real funds

### API Documentation

* **BSV SDK Docs**: <https://bsv-blockchain.github.io/ts-sdk/>
* **Wallet Toolbox Reference**: <https://fast.brc.dev/>
* **BRC Standards**: <https://hub.bsvblockchain.org/brc>

***

## Environment Variables Best Practices

### Backend (.env)

```env
# Network Configuration
NETWORK=testnet

# Database
DATABASE_URL=mongodb://localhost:27017/bsv-app

# API
PORT=3000
API_SECRET=your-secret-key-here

# Security (Development only - use HSM in production)
# MASTER_PRIVATE_KEY_WIF=cVrt...
ENCRYPTION_KEY=your-encryption-key-here
```

### Frontend (.env)

```env
# API Endpoint (if you have a backend)
REACT_APP_API_URL=http://localhost:3000

# Network
REACT_APP_NETWORK=testnet

# Note: Frontend has NO private keys
# All signing happens in user's wallet
```

**Security Rules:**

* ✅ Always add `.env` to `.gitignore`
* ✅ Use different `.env` files for dev/prod
* ✅ Never commit private keys
* ✅ Use environment variables for all secrets
* ✅ In backend production, use HSM or key vaults

***

## Troubleshooting

### "Cannot find module '@bsv/sdk'"

```bash
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

### "WalletClient connection failed"

**Checklist:**

* ✅ MetaNet Desktop Wallet installed?
* ✅ Wallet unlocked?
* ✅ Testnet mode if using testnet?
* ✅ dApp origin authorized in wallet?

**Solution:**

```bash
# Check wallet is running
# Check browser console for detailed error
# Verify wallet extension is enabled
```

### TypeScript Errors

```bash
# Update TypeScript
npm install -D typescript@latest

# Regenerate tsconfig.json
npx tsc --init

# Check for type definition issues
npm install -D @types/node
```

### Permission Errors (Linux/macOS)

```bash
# Fix npm permissions
sudo chown -R $USER /usr/local/lib/node_modules
```

### Port Already in Use

```bash
# Backend (port 3000)
lsof -ti:3000 | xargs kill -9

# Frontend (port 3000 for React)
# Change port in package.json or:
PORT=3001 npm start
```

***

## Verification Checklist

### Backend Development Ready

* ✅ Node.js 18+ installed
* ✅ TypeScript 5.0+ installed
* ✅ BSV SDK installed
* ✅ Project structure created
* ✅ Test script runs successfully
* ✅ `.env` file configured
* ✅ Git initialized

### Frontend Development Ready

* ✅ Node.js 18+ installed
* ✅ React project created
* ✅ BSV SDK installed
* ✅ MetaNet Desktop Wallet installed
* ✅ Wallet connection test works
* ✅ Test component renders
* ✅ Git initialized

***

## Next Steps

Now that your environment is ready, continue to:

**For Both Paradigms:**

* [BSV Fundamentals](/bsv-code-academy/beginner-path/beginner/bsv-fundamentals.md) - Learn UTXO model, transactions, scripts

**Then Choose Your Path:**

**Backend Developers:**

* [Managing Wallets Server-Side](/bsv-code-academy/beginner-path/beginner/first-wallet.md) - Server-side wallet management
* [Building Transactions Programmatically](/bsv-code-academy/beginner-path/beginner/first-transaction.md) - Transaction creation

**Frontend Developers:**

* [WalletClient Integration](/bsv-code-academy/beginner-path/beginner/wallet-client-integration.md) - Connect to user wallets
* [Building dApps with WalletClient](/bsv-code-academy/beginner-path/beginner/first-transaction.md) - Request user signatures

***

## Related Resources

### Official Documentation

* [BSV SDK Documentation](https://bsv-blockchain.github.io/ts-sdk/)
* [Wallet Toolbox Documentation](https://fast.brc.dev/)
* [Node.js Documentation](https://nodejs.org/docs)
* [TypeScript Handbook](https://www.typescriptlang.org/docs/)

### Tools

* [VS Code](https://code.visualstudio.com/)
* [WhatsOnChain Explorer](https://whatsonchain.com/)
* [MetaNet Desktop Wallet](https://desktop.bsvb.tech/)
* [BRC Standards](https://hub.bsvblockchain.org/brc)
* [Get BSV - Orange Gateway](https://hub.bsvblockchain.org/demos-and-onboardings/onboardings/onboarding-catalog/get-bsv/orange-gateway)
* [BSV Discord Community](https://discord.gg/bsv) - Get help and testnet coins

### Community

* [BSV Discord](https://discord.gg/bsv)
* [BSV Developers Reddit](https://www.reddit.com/r/bsvdevs/)
* [Stack Overflow (tag: bsv)](https://stackoverflow.com/questions/tagged/bsv)

***

**Your development environment is now ready! Let's learn BSV fundamentals.**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.bsvblockchain.org/bsv-code-academy/beginner-path/beginner/development-environment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.