Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Networks & ConfigIds · Boson Protocol
Skip to content

Networks & ConfigIds

Boson is deployed on multiple chains, in multiple environments, and the Diamond can be redeployed to a new index when there's a breaking upgrade. Every SDK call, MCP tool call, and widget embed takes a single string that disambiguates all three:

${envName}-${chainId}-${index}

Examples:

  • staging-84532-0 — Base Sepolia testnet, staging environment, index 0.
  • staging-80002-0 — Polygon Amoy testnet.
  • staging-11155111-0 — Sepolia.
  • production-137-0 — Polygon mainnet.
  • production-1-0 — Ethereum mainnet.
  • production-8453-0 — Base mainnet.
  • production-10-0 — Optimism mainnet.
  • production-42161-0 — Arbitrum mainnet.

For the full machine-readable list see Networks → ConfigIds matrix. For deployed contract addresses see Networks → Contract addresses.

Why the index?

When the Diamond is upgraded in a breaking way (rare; protocol-level change), a new deployment is published with a new index. Old index-0 continues to function for legacy exchanges; new offers point to index-1. The configId makes the choice explicit.

If a chain has never been upgraded, its index is always 0 and you can ignore the discriminator.

Discovering ConfigIds at runtime

import { getEnvConfigs } from "@bosonprotocol/common"
const ids = (["local", "testing", "staging", "production"] as const)
  .flatMap((env) => getEnvConfigs(env).map((c) => c.configId))
// or via MCP:
//   get_config_ids → { ids: ["staging-84532-0", ...] }

Switching environments

The recommended pattern is one ConfigId per deployment environment:

const CONFIG_ID = process.env.NODE_ENV === "production"
  ? "production-137-0"
  : "staging-84532-0"

Cross-checking: the same seller/buyer/offer IDs do not exist across environments. An offer with id = 42 on staging is unrelated to id = 42 on production.

Picking a network

A few rules of thumb:

Use caseRecommended
Testingstaging-84532-0 (Base Sepolia) — cheap, fast
Polygon-heavy ecosystemsproduction-137-0
L2-first appsproduction-8453-0 (Base) or production-42161-0 (Arbitrum)
Maximum decentralization perceptionproduction-1-0 (Ethereum mainnet) — most expensive

See the per-chain Contract addresses and Subgraph endpoints for the deployment specifics.

Common footguns

  • Don't hard-code the chain ID. Use the configId; it carries the env and version too.
  • Don't use a production ConfigId in a staging app. The staging dApp and widget host won't load production offers.
  • Use coreSdk.getConfig() to read the config that's actually loaded. This is the safest source of truth for subgraph URL, contract addresses, and supported tokens.

Next