Adding a Custom Network

Overview

This guide walks you through adding support for a new Polkadot/Substrate network to your inkathon project. You'll learn how to generate types, configure the connection, and deploy contracts to the new chain.

Prerequisites

Working inkathon project
Access to the network's RPC endpoint
Account with funds on the target network (for deployments)

Step-by-Step Guide

Find Network RPC Endpoint

First, you need the WebSocket RPC endpoint for your target network. Common networks:

Network	RPC Endpoint
Polkadot	`wss://rpc.polkadot.io`
Kusama	`wss://kusama-rpc.polkadot.io`
Astar	`wss://rpc.astar.network`
Moonbeam	`wss://wss.api.moonbeam.network`
Pop Network	`wss://rpc1.paseo.popnetwork.xyz`

For other networks, check their documentation or use Polkadot.js Apps.

Generate PAPI Types

Generate TypeScript types for the network using PAPI:

# From the contracts directory
cd contracts

# Add the network (replace with your network details)
bunx papi add -w wss://your-rpc-endpoint.com yournetwork

# Example for Astar
bunx papi add -w wss://rpc.astar.network astar

This creates type definitions in .papi/descriptors/ that enable type-safe interactions.

Configure ReactiveDOT

Add the network configuration to your frontend:

// frontend/src/lib/reactive-dot/config.ts

import { yournetwork } from '@polkadot-api/descriptors'
import { getWsProvider } from 'polkadot-api/ws-provider/web'

export const config = {
  chains: {
    // ... existing chains
    yournetwork: {
      descriptor: yournetwork,
      provider: getWsProvider("wss://your-rpc-endpoint.com"),
    },
  },
  // ... rest of config
}

Add Network Constants

Update the constants file with network-specific information:

// frontend/src/lib/inkathon/constants.ts

export const FAUCET_URLS: { [key: string]: string } = {
  // ... existing faucets
  yournetwork: "https://your-faucet-url.com",
}

Deploy Contracts to New Network

Set up deployment configuration:

Create .env.yournetwork in the contracts directory:

# contracts/.env.yournetwork
ACCOUNT_URI="your seed phrase or //Alice for dev"

⚠️ Security: Never commit .env files with real seed phrases!

Deploy your contracts:

# From contracts directory
CHAIN=yournetwork bun run deploy

This will:

Build contracts if needed
Deploy to the specified network
Export addresses to deployments/<contract>/yournetwork.ts

Update Frontend Deployments

Import the new deployment addresses:

// frontend/src/lib/inkathon/deployments.ts

import { 
  evmAddress as flipperEvmYourNetwork, 
  ss58Address as flipperSs58YourNetwork 
} from 'contracts/deployments/flipper/yournetwork'

export const contractDeployments = {
  flipper: {
    // ... existing deployments
    yournetwork: { 
      evmAddress: flipperEvmYourNetwork, 
      ss58Address: flipperSs58YourNetwork 
    },
  },
}

Test the Integration

Start your frontend: bun run dev
Open the network selector
Choose your new network
Verify contract interactions work

Advanced Configuration

Custom Chain Properties

For chains with non-standard properties:

// frontend/src/lib/reactive-dot/config.ts

yournetwork: {
  descriptor: yournetwork,
  provider: getWsProvider("wss://your-rpc-endpoint.com"),
  // Optional: Custom SS58 prefix
  ss58Format: 42,
  // Optional: Custom token info
  tokenSymbol: "TOKEN",
  tokenDecimals: 18,
}

Multiple Endpoints

For redundancy, you can configure multiple endpoints:

const endpoints = [
  "wss://primary-rpc.example.com",
  "wss://backup-rpc.example.com",
]

yournetwork: {
  descriptor: yournetwork,
  provider: getWsProvider(endpoints[0]),
  // Fallback logic can be implemented
}

Network-Specific Features

Some networks may require special handling:

// Check if network supports contracts
const supportsContracts = (network: string): boolean => {
  const contractNetworks = ['pop', 'astar', 'shiden']
  return contractNetworks.includes(network)
}

File Structure After Adding Network

Troubleshooting

Common Issues

Issue	Solution
PAPI type generation fails	Ensure the RPC endpoint is accessible and supports required APIs
Deployment fails	Check account balance and ensure it has funds for gas
Frontend can't connect	Verify WebSocket URL and check browser console for errors
Types not found	Run `bun run codegen` after adding the network

Verifying Network Support

Check if a network supports ink! contracts:

# Using Polkadot.js Apps
# 1. Connect to your network
# 2. Go to Developer > Chain State
# 3. Look for "contracts" pallet

Example: Adding Astar Network

Here's a complete example for adding Astar:

# 1. Generate types
bunx papi add -w wss://rpc.astar.network astar

# 2. Configure frontend
# Add to config.ts:
# astar: {
#   descriptor: astar,
#   provider: getWsProvider("wss://rpc.astar.network"),
# }

# 3. Deploy contracts
CHAIN=astar bun run deploy

# 4. Update deployments
# Import and export Astar addresses

Next Steps

Add a new contract to your project
Configure environment variables for production
Set up CI/CD pipelines for automated deployments

On this page