examples

Avalanche SDK Client Examples

This directory contains practical examples demonstrating how to use the @avalanche-sdk/client package to interact with the Avalanche blockchain.

Prerequisites

• Node.js: Version 20 or higher
• npm: Latest version recommended
• TypeScript: Examples are written in TypeScript

Quick Start

Option 1: Using the Latest Released Version

1. Navigate to the examples directory:

   cd client/examples

2. Install the latest SDK version:

   npm install @avalanche-sdk/client@latest

3. Run any example:

   npx tsx <example-file.ts>

Option 2: Using a Local Development Build

1. Build the SDK from source:

   # From the project root
   npm run build:all

2. Create a global symlink:

   npm link

3. Navigate to examples and link to local build:

   cd client/examples
   npm link @avalanche-sdk/client

4. Run any example:

   npx tsx <example-file.ts>

Note: Make sure to create your own .env file by copying the .env.example file and updating the values. You'll also need to modify the config.ts file to point to your .env file path. By default, the examples use the values from .env.example, and the test addresses mentioned in the examples as comments (like 0x76Dd3d7b2f635c2547B861e55aE8A374E587742D and X-fuji19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz) are derived from the private key values in that file.

Available Examples

Basic Examples

• sendAvax.ts - Basic AVAX transfer example

React Web Application Examples

Located in react-show-balance-and-cross-chain-transfers/:

Overview

The React examples demonstrate how to build a modern web application that integrates with the Avalanche blockchain using the SDK. These examples showcase:

• Wallet Integration: Connecting to Core browser extension via EIP-1193 provider
• Balance Display: Real-time P-Chain and C-Chain AVAX balance monitoring
• Cross-Chain Transfers: Seamless AVAX transfers between Platform and Contract chains
• Network Switching: Dynamic switching between Fuji testnet and Mainnet
• Modern UI: Built with Material-UI and React 18, featuring responsive design

Key Features

• Real-time Balance Updates: Automatic balance refresh every 20 seconds
• Chain-Specific Logic: Different handling for P-Chain (Platform) vs C-Chain (Contract)
• Error Handling: Comprehensive error states and user feedback
• Responsive Design: Mobile-friendly interface with adaptive layouts
• Type Safety: Full TypeScript implementation with proper type definitions

Required Polyfills

Due to the Node.js environment assumptions in the Avalanche SDK, several polyfills are required for browser compatibility:

// vite.config.ts
export default defineConfig({
  plugins: [react()],
  define: {
    // Polyfill Node.js globals for browser environment
    global: "globalThis",
    "process.env": {},
  },
  resolve: {
    alias: {
      // Polyfill Node.js modules
      process: "process/browser",
      util: "util",
    },
  },
  optimizeDeps: {
    include: ["process", "util"],
  },
});

Dependencies to install:

npm install process util
npm install --save-dev @types/node

What are Polyfills? Polyfills are code that implements a feature on web browsers that do not support that feature. In this case, some dependencies in the Avalanche SDK was designed for Node.js environments and uses Node.js-specific modules like process and util. Since browsers don't have these modules, we need to provide browser-compatible versions. Learn more about polyfills in the MDN Web Docs and web.dev.

Running the React Examples

1. Navigate to the React examples directory:

   cd react-show-balance-and-cross-chain-transfers

2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

Primary Network Transaction Examples

Located in prepare-primary-network-txns/:

Cross-Chain Transfers

• transfer-avax-from-x-chain-to-p-chain.ts - Transfer AVAX from X-Chain to P-Chain
• transfer-avax-from-p-chain-to-x-chain.ts - Transfer AVAX from P-Chain to X-Chain
• transfer-avax-from-x-chain-to-c-chain.ts - Transfer AVAX from X-Chain to C-Chain
• transfer-avax-from-c-chain-to-x-chain.ts - Transfer AVAX from C-Chain to X-Chain
• transfer-avax-from-p-chain-to-c-chain.ts - Transfer AVAX from P-Chain to C-Chain
• transfer-avax-from-c-chain-to-p-chain.ts - Transfer AVAX from C-Chain to P-Chain

Chain-Specific Examples

• x-chain/ - X-Chain specific operations
• p-chain/ - P-Chain specific operations, including ACP-236 auto-renewed validator transactions
• c-chain/ - C-Chain specific operations

Configuration

Most examples require configuration before running:

1. Network Selection: Examples default to Fuji testnet. Modify the network configuration in each example file to use mainnet or local network.

2. Private Keys: Copy the example environment file in .env and edit with your actual values

3. Addresses: Update recipient addresses to valid Avalanche addresses.

Security Notes

• Never commit your .env file - it contains sensitive private keys
• Use testnet keys for development and testing
• Keep your mainnet private keys secure and offline

Important Notes

• Testnet Usage: Examples are configured for Fuji testnet by default. Use testnet AVAX for experimentation.
• Security: Never commit private keys or sensitive information to version control.
• Node Version: Ensure you're using Node.js version 20 or higher for compatibility.
• Browser Compatibility: React examples require modern browsers with ES2020+ support.

Troubleshooting

Common Issues

1. "Cannot find module" errors:

   • Ensure you've installed dependencies: npm install
   • Check that you're in the correct directory

2. TypeScript compilation errors:

   • Verify Node.js version: node --version
   • Reinstall dependencies: rm -rf node_modules && npm install

3. Network connection issues:

   • Check your internet connection
   • Verify the RPC endpoint is accessible
   • Consider using a different RPC provider

4. React examples not working in browser:

   • Ensure all polyfills are properly configured
   • Check browser console for polyfill-related errors
   • Verify that process and util packages are installed

React-Specific Issues

1. "process is not defined" errors:

   • Ensure polyfills are properly configured in vite.config.ts
   • Check that process package is installed

2. "global is not defined" errors:

   • Verify global: "globalThis" is set in Vite config
   • This is required for Node.js compatibility in browsers

Additional Resources

• Avalanche Network Documentation
• GitHub Repository
• Understanding Polyfills
• Vite Configuration Guide
• React with TypeScript

Contributing

Found an issue or want to add more examples? Please contribute by:

1. Forking the repository
2. Creating a feature branch
3. Adding your example or fix
4. Submitting a pull request

---

Happy building on Avalanche! 🏔️