Network, RPC, Staking, and Bridging

Overview

The StarkZap accepts configuration through a single options object. You can use network presets for simplicity, or provide explicit RPC URLs and chain IDs for custom setups.

New to blockchain? An RPC (Remote Procedure Call) is like an API endpoint for the blockchain—it’s how your app communicates with the network. A network is like an environment (production, staging, development). See the Glossary for more web2-friendly explanations.

Network

The simplest way to configure the SDK is using network presets. Think of networks like environments:

mainnet = Production (real money, real transactions)
sepolia = Staging/Testnet (fake money for testing)
devnet = Local development (your own test blockchain)

import { StarkZap } from "starkzap";

// Mainnet
const sdk = new StarkZap({ network: "mainnet" });

// Sepolia testnet
const sdk = new StarkZap({ network: "sepolia" });

// Local devnet (starknet-devnet-rs)
const sdk = new StarkZap({ network: "devnet" });

Available Presets

Preset	Chain ID	RPC	Explorer
`mainnet`	`SN_MAIN`	`https://api.cartridge.gg/x/starknet/mainnet`	`https://voyager.online`
`sepolia`	`SN_SEPOLIA`	`https://api.cartridge.gg/x/starknet/sepolia`	`https://sepolia.voyager.online`
`devnet`	`SN_SEPOLIA`	`http://localhost:5050`	—

Using Network Objects

You can also pass a custom NetworkPreset object:

import { StarkZap, networks } from "starkzap";

const sdk = new StarkZap({ network: networks.mainnet });

RPC

If you run your own blockchain node or use a different RPC provider (like using a different API endpoint):

An RPC provider is like choosing which API server to use. Just like you might use AWS, Google Cloud, or your own servers, you can use different RPC providers to connect to the blockchain.

import { StarkZap, ChainId } from "starkzap";

const sdk = new StarkZap({
  rpcUrl: "https://starknet-mainnet.infura.io/v3/YOUR_KEY",
  chainId: ChainId.MAINNET,
});

rpcUrl and chainId override values from network if both are provided.

Staking

Enable staking functionality to let users earn passive income by staking their tokens. When configured, users can:

💰 Stake tokens in validator pools and earn rewards over time (like earning interest on a savings account)
📈 Grow their holdings as rewards accumulate automatically
🔄 Manage their positions by adding more tokens, claiming rewards, or exiting pools
🏦 Support network security while earning passive income

Staking works out of the box using chain-aware staking contract presets:

import { StarkZap } from "starkzap";

const sdk = new StarkZap({
  network: "mainnet",
});

If needed, you can override the default preset:

import { StarkZap, fromAddress } from "starkzap";

const sdk = new StarkZap({
  network: "mainnet",
  staking: {
    contract: fromAddress(
      "0x00ca1702e64c81d9a07b86bd2c540188d92a2c73cf5cc0e508d949015e7e84a7"
    ),
  },
});

Ready to implement staking? See the Staking & Delegation Guide for complete instructions on how users can stake tokens, claim rewards, and manage their positions.

Bridging

Configure optional cross-chain bridge settings when depositing assets from Ethereum or Solana into Starknet.

import { StarkZap } from "starkzap";

const sdk = new StarkZap({
  network: "mainnet",
  bridging: {
    ethereumRpcUrl: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
    solanaRpcUrl: "https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY",
    layerZeroApiKey: "YOUR_LAYERZERO_API_KEY", // for OFT routes
  },
});

ethereumRpcUrl: Custom Ethereum RPC for bridge fee/balance operations
solanaRpcUrl: Custom Solana RPC (falls back to cluster URL if omitted)
layerZeroApiKey: Required for OFT/OFT-migrated routes

OFT routes require bridging.layerZeroApiKey and are supported on mainnet bridge routes only.

For the full deposit flow (getBridgingTokens, external wallet adapters, fee estimate, deposit), see the Bridging Guide.

Complete Configuration Example

Here’s an example with all optional features configured:

Using Network Preset

import { StarkZap, fromAddress } from "starkzap";

const sdk = new StarkZap({
  // Network configuration
  network: "mainnet",
  
  // Optional: override staking contract preset
  staking: {
    contract: fromAddress(
      "0x00ca1702e64c81d9a07b86bd2c540188d92a2c73cf5cc0e508d949015e7e84a7"
    ),
  },
  bridging: {
    ethereumRpcUrl: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
    layerZeroApiKey: "YOUR_LAYERZERO_API_KEY",
  },
});

Using Custom RPC

import { StarkZap, ChainId, fromAddress } from "starkzap";

const sdk = new StarkZap({
  // Custom RPC configuration
  rpcUrl: "https://starknet-mainnet.infura.io/v3/YOUR_KEY",
  chainId: ChainId.MAINNET,
  
  // Optional: override staking contract preset
  staking: {
    contract: fromAddress(
      "0x00ca1702e64c81d9a07b86bd2c540188d92a2c73cf5cc0e508d949015e7e84a7"
    ),
  },
  bridging: {
    solanaRpcUrl: "https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY",
  },
});

For paymaster configuration, see the Paymasters Guide for detailed setup instructions for AVNU Paymaster or Cartridge’s built-in paymaster.

Configuration Type Reference

interface SDKConfig {
  // Network (choose one)
  network?: NetworkName | NetworkPreset;
  rpcUrl?: string;
  chainId?: ChainId;
  
  // Optional features
  paymaster?: PaymasterOptions; // { nodeUrl?: string; default?: boolean; headers?: object }
  explorer?: ExplorerConfig;
  staking?: StakingConfig;
  bridging?: BridgingConfig;
}

interface StakingConfig {
  contract: Address; // optional override
}

interface BridgingConfig {
  layerZeroApiKey?: string;
  ethereumRpcUrl?: string;
  solanaRpcUrl?: string;
}

For paymaster configuration details, see the Paymasters Guide.

Next Steps

Set up Paymasters for gasless transactions
Enable Staking & Delegation so users can earn passive income
Configure Bridging for Ethereum/Solana deposits into Starknet
Learn about Connecting Wallets with different signers
Configure Account Presets for your use case

Getting Started

Configuration

Using LLMs

Modules

Integrations

Examples

Reference

Overview

Available Presets

Using Network Objects

Complete Configuration Example

Using Network Preset

Using Custom RPC

Configuration Type Reference

Next Steps

​Overview

​Available Presets

​Using Network Objects

​Complete Configuration Example

​Using Network Preset

​Using Custom RPC

​Configuration Type Reference

​Next Steps

Overview

Available Presets

Using Network Objects

Complete Configuration Example

Using Network Preset

Using Custom RPC

Configuration Type Reference

Next Steps