How to Add Custom Network on Solana Network

By /
How to Add Custom Network on Solana Network
Visualization: How to Add Custom Network on Solana Network

Understanding and Configuring Custom Solana Networks

The Solana blockchain ecosystem provides a robust environment for decentralized application (dApp) development and deployment. While the Mainnet-Beta serves as the primary production network, developers and users frequently require access to alternative networks for testing, development, or specialized operations. This article delves into the methodologies for adding and configuring custom Solana networks, enabling a flexible and efficient development workflow.

Introduction to Solana Networks

Solana’s architecture supports multiple network environments, each serving distinct purposes. Understanding these environments is crucial before configuring custom connections:

  • Mainnet-Beta: The primary, production-ready network where real-world transactions occur. It is the most decentralized and secure network, handling high transaction volumes.
  • Devnet: A public testnet primarily used by developers for initial dApp testing and prototyping. It provides a stable environment with faucet services to acquire free SOL for testing purposes, mimicking Mainnet-Beta functionality without real economic value.
  • Testnet: Another public testnet, often used for performance testing, stress testing, and experimenting with new Solana features before they are pushed to Mainnet-Beta. It can be less stable than Devnet due to its experimental nature.
  • Local Validator: A private Solana network instance run locally on a developer’s machine. This environment offers complete control, immediate feedback, and isolated testing without relying on public network stability or connectivity. It is ideal for rapid iteration and debugging.
  • Custom RPC Endpoints: These refer to third-party or privately hosted RPC (Remote Procedure Call) nodes that offer access to Solana networks. They can provide enhanced performance, specific data access, or specialized configurations for particular use cases.

The ability to seamlessly switch between or connect to these various networks is fundamental for comprehensive dApp development and operational flexibility.

Prerequisites

Before proceeding with custom network configurations, ensure you have the following installed and configured:

  • Solana Tool Suite: This includes the Solana CLI (Command Line Interface) and essential utilities. Installation instructions are available on the official Solana documentation. Verify installation by running solana --version.
  • Node.js and npm (Optional, for programmatic connections or local validator setup): Necessary if you plan to interact with Solana programmatically using libraries like @solana/web3.js or if you’re running a local validator via a package.
  • Basic Understanding of Blockchain Concepts: Familiarity with RPC, network endpoints, and wallets will aid comprehension.

Method 1: Configuring Custom Networks via Solana CLI

The Solana CLI is the most common tool for interacting with Solana networks, including setting custom endpoints. This method is suitable for connecting to public Devnet, Testnet, or any custom RPC endpoint provided by a third party.

Setting a Public Network (Devnet/Testnet)

To connect your CLI to a standard public network, use the `solana config set` command:

solana config set --url devnet

Or for Testnet:

solana config set --url testnet

To revert to Mainnet-Beta:

solana config set --url mainnet-beta

Connecting to a Custom RPC Endpoint

For custom RPC endpoints, you will need the specific URL of the RPC node. These are typically provided by RPC providers (e.g., Helius, QuickNode, Alchemy) or by private network operators.

solana config set --url <YOUR_CUSTOM_RPC_URL>

Example: If you have a custom RPC endpoint for a test environment:

solana config set --url https://api.mycustomtestnet.com

It’s important to note that a custom RPC URL should ideally support both RPC (HTTP) and WebSocket (WS) protocols for full functionality, though the CLI primarily uses RPC for most commands. Some RPC providers might offer separate URLs for RPC and WS.

Verifying Current Configuration

To check which cluster your Solana CLI is currently configured to connect to, use:

solana config get

This command will display the current RPC URL, WebSocket URL, and your default keypair path.

Method 2: Running a Local Solana Validator

Setting up a local validator creates a truly custom, isolated Solana network on your machine. This is invaluable for rapid development, testing smart contracts (programs) without network latency, and simulating various scenarios without affecting public testnets.

Steps to Set Up a Local Validator

  1. Ensure Solana Tool Suite is Installed:
    The `solana-test-validator` executable is part of the Solana Tool Suite.
  2. Start the Local Validator:
    Open a new terminal window and run:

    solana-test-validator

    This command starts a local validator instance, listening for RPC requests on `http://localhost:8899` and WebSocket requests on `ws://localhost:8900` by default. It also creates a ledger directory to store blockchain state.

    Useful `solana-test-validator` Options:

    • `–reset`: Clears the ledger directory and starts a fresh validator from scratch. Ideal for clean tests.
    • `–url <CLUSTER_URL>`: Forks the local validator from an existing cluster (e.g., `devnet`), allowing you to test against a recent state of that cluster.
    • `–bpf-path <PROGRAM_PATH>`: Loads a BPF (Berkeley Packet Filter) program into the local validator at startup. Useful for quickly deploying and testing your smart contracts.
    • `–ledger <LEDGER_PATH>`: Specifies a custom directory for the ledger.
    • `–clone <ACCOUNT_ADDRESS>`: Clones the state of a specific account from a remote cluster onto your local validator.

    Example with fork from Devnet and pre-loaded program:

    solana-test-validator --url devnet --bpf-path ./target/deploy/my_program.so
  3. Configure CLI to Connect to Local Validator:
    In a separate terminal window, set your CLI to connect to the local validator:

    solana config set --url http://localhost:8899

    Now, any `solana` CLI command executed in this terminal will interact with your local, custom network.

Method 3: Programmatic Connection (e.g., using `@solana/web3.js`)

For dApp developers, connecting to a custom network programmatically is essential. The `@solana/web3.js` library, the official JavaScript SDK for Solana, facilitates this.

Connecting in JavaScript/TypeScript

When initializing a `Connection` object, simply provide the desired RPC endpoint URL.

import { Connection, clusterApiUrl, PublicKey } from '@solana/web3.js';

async function connectToCustomNetwork() {
    // Connect to Devnet (using a helper function for public clusters)
    const devnetConnection = new Connection(clusterApiUrl('devnet'), 'confirmed');
    console.log('Connected to Devnet. Slot:', await devnetConnection.getSlot());

    // Connect to a custom RPC endpoint
    const customRpcUrl = 'https://api.mycustomtestnet.com'; // Replace with your custom RPC URL
    const customConnection = new Connection(customRpcUrl, 'confirmed');
    console.log('Connected to custom RPC. Slot:', await customConnection.getSlot());

    // Connect to a local validator
    const localRpcUrl = 'http://localhost:8899';
    const localConnection = new Connection(localRpcUrl, 'confirmed');
    console.log('Connected to local validator. Slot:', await localConnection.getSlot());

    // Example: Fetching balance from local validator
    const myWallet = new PublicKey('YOUR_WALLET_PUBLIC_KEY'); // Replace with your public key
    const balance = await localConnection.getBalance(myWallet);
    console.log(`Balance on local validator for ${myWallet.toBase58()}: ${balance / 1e9} SOL`);
}

connectToCustomNetwork();

The second parameter to the `Connection` constructor, `’confirmed’`, specifies the commitment level, which dictates how finalized a transaction must be before the RPC node considers it confirmed. Other options include `’processed’` (fastest, least finalized) and `’finalized’` (slowest, most finalized).

Verifying Your Custom Network Connection

After configuring your CLI or dApp to a custom network, it’s crucial to verify the connection.

Using Solana CLI

  • Check Cluster Version:

    solana cluster-version

    This command queries the connected cluster for its software version. A successful response indicates a live connection.

  • Check Balance of an Account:

    solana balance

    This displays the SOL balance of your default keypair on the currently configured cluster. If it’s a local validator, you might need to airdrop some SOL first: `solana airdrop 5`.

  • Check RPC URL:
    As mentioned, `solana config get` confirms the currently used RPC endpoint.

In a dApp

  • Fetch a Recent Blockhash or Slot: As shown in the programmatic example, successfully retrieving a slot number or recent blockhash confirms connectivity.
  • Perform a Test Transaction: Attempt a trivial transaction, like sending 0 SOL to another account (if available), and observe if it’s processed.

Use Cases and Best Practices

  • Development and Testing: Local validators are indispensable for rapid iteration on smart contracts. Devnet and Testnet are excellent for testing dApps with other services and observing real-world network behavior before Mainnet-Beta deployment.
  • Security: When using custom RPC endpoints from third parties, ensure they are reputable and trustworthy. Connecting to unknown or malicious RPCs could expose your transactions or compromise privacy.
  • Performance: Public RPC endpoints can experience rate limiting or congestion. Custom, dedicated RPCs often provide better performance and reliability for production dApps.
  • State Management: Always be aware of which network your CLI, wallet, or dApp is currently connected to. Accidentally deploying to the wrong network or performing actions on Mainnet-Beta when intending to use a testnet can lead to unintended consequences.
  • Faucets: Remember that Devnet and Testnet offer faucet services (e.g., `solana airdrop 1` on Devnet) to obtain free test SOL, which is not possible on Mainnet-Beta.

Conclusion

The ability to add and manage custom networks on Solana is a powerful feature that underpins robust dApp development and flexible operational strategies. Whether utilizing the Solana CLI for quick configuration, orchestrating a local validator for isolated testing, or integrating programmatic connections within dApps, developers have a full spectrum of tools to interact with various Solana environments. By mastering these methods, users can navigate the Solana ecosystem efficiently, ensuring their applications are well-tested, secure, and ready for deployment.

Disclaimer: This content is for educational purposes only. Not financial advice.

Related Posts

Search
Scroll to Top