Networks

A Network is a mostly-flat data object describing one chain: its slug, display name, chain id, RPC endpoint, native currency, and virtual machine ("evm" or "svm"). Every workspace opens with a set of built-in networks already loaded, and you can add your own, override a built-in's RPC URL, or drop the ones you added. Both the class and its collection live behind the main entry:

import { Workspace, Network } from "wative-core";

The Network class

Constructor

The primary form takes a single NetworkInit object:

const monad = new Network({
  slug: "monad-testnet",
  name: "Monad Testnet",
  chainId: 10143,
  rpcUrl: "https://testnet-rpc.monad.xyz",
  nativeCurrency: { name: "Monad", symbol: "MON", decimals: 18 },
  vm: "evm",
});

A positional overload also exists — new Network(name, chainId, rpcUrl, nativeCurrency?, color?) — which derives the slug from name and infers vm from the chain id. The object form is preferred because every field is explicit.

NetworkInit

The read-only network.symbol getter is a shortcut for network.nativeCurrency.symbol.

The workspace.networks collection

workspace.networks is a read-only array of Network (the NetworkCollection interface) with lookup and mutation helpers. Numeric and slug indexing both work, and a workspace-defined network overrides a built-in of the same slug.

ws.networks.length;                     // 14 at a fresh open
ws.networks[0];                         // first Network in the array
ws.networks["bnbchain"];                // by slug (proxy indexing)
ws.networks.map((n) => n.slug);         // ordinary array methods

bySlug and byChainId

Both return the matching Network, or null when nothing matches.

ws.networks.bySlug("ethereum").chainId;        // 1
ws.networks.bySlug("arbitrum-sepolia").vm;     // "evm"
ws.networks.byChainId(8453).slug;              // "base"
ws.networks.bySlug("does-not-exist");          // null

add / update / drop

Adding a slug that is already registered rejects with PARAMETER_ERROR:

await ws.networks.add(monad);
ws.networks.length;                          // 15
ws.networks.bySlug("monad-testnet").chainId; // 10143

await ws.networks.add(monad);
// rejects → WativeError { code: "PARAMETER_ERROR" }

update() replaces the existing entry in place — the common use is overriding a built-in's RPC URL with your own provider. Build a fresh Network by spreading the existing one and pass it to update(); the collection length is unchanged because the slug already existed:

const eth = ws.networks.bySlug("ethereum");
const customEth = new Network({
  ...eth,
  rpcUrl: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
});
await ws.networks.update(customEth);

ws.networks.bySlug("ethereum").rpcUrl;
// "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
ws.networks.length; // 14 — replaced, not appended

The built-in guard

Networks you added can be dropped; the built-ins that ship with the workspace cannot:

await ws.networks.drop(custom);
ws.networks.bySlug("my-net"); // null

const eth = ws.networks.bySlug("ethereum");
await ws.networks.drop(eth);
// rejects → WativeError { code: "UNSUPPORTED_OP" }

A built-in's RPC URL is still fully editable through update() — the guard is only on removing it.

account.setDefaultNetwork

Each account carries a default network. account.defaultNetwork reads the resolved slug (a Slug); account.setDefaultNetwork(value) sets it and persists, returning a Promise<void>. The argument is a NetworkLike — Network | ChainId | string — so a slug, a numeric chain id, a hex chain id string, or a Network instance all resolve to the same network:

const acc = await ws.accounts.create("Desk", "wsp-pwd", MNEMONIC);

await acc.setDefaultNetwork("base");            // slug
acc.defaultNetwork;                             // "base"

await acc.setDefaultNetwork(8453);              // chain id → "base"
await acc.setDefaultNetwork("0xa");             // hex chain id → "optimism"
await acc.setDefaultNetwork(Network.Arbitrum);  // Network instance
acc.defaultNetwork;                             // "arbitrum"

The choice survives a lock and reopen. An unresolvable value rejects with UNSUPPORTED_NETWORK:

await acc.setDefaultNetwork("does-not-exist");
// rejects → WativeError { code: "UNSUPPORTED_NETWORK" }
await acc.setDefaultNetwork(99999999);
// rejects → WativeError { code: "UNSUPPORTED_NETWORK" }

NetworkLike string resolution also honors a few common aliases before slug lookup, so "mainnet"/"eth" map to ethereum, "bsc"/"binance" to bnbchain, "op" to optimism, and "sol" to solana.

rpcUrl validation

rpcUrl is trimmed before it is stored. An empty string is a supported "no RPC configured" state; the RPC client raises its own coded error if you try to use it. A non-empty value must be a valid URL with an allowed scheme, and hosts that resolve to link-local or cloud-metadata addresses are refused. All failures throw a WativeError with code PARAMETER_ERROR.

Error codes

Related