feat(client): replace NetworkId with Chain descriptor by solidsnakedev · Pull Request #223 · IntersectMBO/evolution-sdk

solidsnakedev · 2026-03-31T23:35:50Z

The network?: string field on createClient carried a string identifier but left slot timing, network magic, and chain identity as separate concerns that callers had to assemble manually. There was no type that encoded all of these together, and the slotConfig top-level parameter was easy to omit or misconfigure.

This replaces network with a required chain: Chain field. Three built-in constants — mainnet, preprod, preview — are exported from the top-level package. Each constant carries the chain name, id, network magic, slot config, and epoch length in one object. A defineChain helper allows custom chains for local devnets and private forks. The networkId property on returned client objects is replaced with chain. The @evolution-sdk/devnet package gains getChain(cluster) and BOOTSTRAP_CHAIN for test setup.

Copilot

Pull request overview

This PR replaces the loosely-typed network (+ separate slotConfig) client configuration with a required chain: Chain descriptor that bundles network identity, network magic, and slot timing parameters into a single object, and updates docs/examples/devnet tooling accordingly.

Changes:

Introduces Chain + defineChain, and exports built-in mainnet, preprod, preview constants from the top-level package.
Updates createClient and related client types to use chain and to source slot timing directly from chain.slotConfig.
Adds devnet helpers (getChain(cluster) and BOOTSTRAP_CHAIN) and migrates several devnet tests/docs/examples to the new API.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/evolution/src/sdk/client/ClientImpl.ts	Reworks `createClient` to require `chain` and wires `chain.slotConfig` into tx building.
packages/evolution/src/sdk/client/Client.ts	Updates public client types to expose `chain` instead of `networkId` where applicable and removes `NetworkId` type.
packages/evolution/src/sdk/client/Chain.ts	Adds the `Chain` model, `defineChain`, and built-in chain constants.
packages/evolution/src/index.ts	Re-exports chain utilities/constants from the package entrypoint.
packages/evolution-devnet/test/TxBuilder.VoteValidators.test.ts	Migrates devnet test setup to use `Cluster.getChain(...)` / `BOOTSTRAP_CHAIN`.
packages/evolution-devnet/test/TxBuilder.Validity.test.ts	Migrates validity-interval devnet tests to `chain` API.
packages/evolution-devnet/test/TxBuilder.SpendScriptRef.test.ts	Migrates script-ref devnet tests to `chain` API.
packages/evolution-devnet/test/TxBuilder.PlutusMint.test.ts	Migrates Plutus minting devnet tests to `chain` API.
packages/evolution-devnet/test/TxBuilder.Metadata.test.ts	Migrates metadata devnet tests to `chain` API.
packages/evolution-devnet/test/TxBuilder.Compose.test.ts	Migrates compose devnet tests to `chain` API.
packages/evolution-devnet/test/TxBuilder.Chain.test.ts	Migrates chainResult devnet tests to `chain` API.
packages/evolution-devnet/test/Client.Devnet.test.ts	Migrates devnet client test to `chain` API.
packages/evolution-devnet/src/Cluster.ts	Adds `getChain(cluster)` and `BOOTSTRAP_CHAIN` to produce `Chain` descriptors for devnet usage.
examples/with-vite-react/src/components/TransactionBuilder.tsx	Updates example app to select a `Chain` constant and pass it to `createClient`.
docs/content/docs/clients/providers.mdx	Updates provider docs snippets to pass `chain: preprod`.
docs/content/docs/clients/index.mdx	Updates overview docs to describe `chain` configuration.
docs/content/docs/clients/client-basics.mdx	Adds chain configuration section and updates examples to use built-in chain constants.
docs/content/docs/clients/architecture.mdx	Updates architecture examples to use `chain: mainnet`.
.changeset/chain-interface.md	Documents the `chain` migration and the devnet chain helpers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T23:41:28Z

packages/evolution/src/sdk/client/ClientImpl.ts

+// Chain only → MinimalClient
+export function createClient(config: { chain: Chain }): MinimalClient

 // Implementation signature - handles all cases (all synchronous now)
-export function createClient(config?: {
-  network?: NetworkId
+export function createClient(config: {
+  chain: Chain
  provider?: ProviderConfig


This change makes createClient require a chain and removes the optional/no-arg overloads, but there are still call sites in the repo using the old { network, slotConfig } shape and/or createClient() with no args (e.g. docs/app/(home)/page.tsx, packages/evolution-devnet/test/TxBuilder.AddSigner.test.ts, TxBuilder.Governance.test.ts, TxBuilder.Mint.test.ts, TxBuilder.NativeScript.test.ts, TxBuilder.Pool.test.ts, TxBuilder.RedeemerBuilder.test.ts, TxBuilder.ScriptStake.test.ts, TxBuilder.Stake.test.ts, TxBuilder.Vote.test.ts, and .specs/client-module-workflow.md). Those need to be migrated (or the old overload kept) or the build/tests/docs will fail.

Copilot · 2026-03-31T23:41:29Z

.changeset/chain-interface.md

+"@evolution-sdk/evolution": patch
+"@evolution-sdk/devnet": patch


This changeset marks the release as a patch, but replacing network?: NetworkId with required chain: Chain (and removing createClient() / default-network behavior) is a breaking public API change. The changeset should be a major bump (or at least follow the repo’s documented semver policy for breaking changes).

Suggested change

"@evolution-sdk/evolution": patch

"@evolution-sdk/devnet": patch

"@evolution-sdk/evolution": major

"@evolution-sdk/devnet": major

Copilot · 2026-03-31T23:41:29Z

examples/with-vite-react/src/components/TransactionBuilder.tsx

@@ -58,13 +59,13 @@ export default function TransactionBuilder() {

      const providerConfig = {
        type: "blockfrost" as const,
-        baseUrl: blockfrostUrls[networkId as keyof typeof blockfrostUrls],
+        baseUrl: blockfrostUrls[networkEnv as keyof typeof blockfrostUrls],
        projectId: import.meta.env.VITE_BLOCKFROST_PROJECT_ID || ""


chain falls back to preprod when networkEnv is not one of the known keys, but providerConfig.baseUrl still indexes blockfrostUrls using networkEnv, which will be undefined in that fallback case. Use the same resolved key used for chain (or derive the URL from chain) so the provider config stays consistent with the chosen chain.

Copilot · 2026-03-31T23:41:29Z

docs/content/docs/clients/index.mdx

 ```typescript
+import { mainnet, preprod, preview, defineChain } from "@evolution-sdk/evolution";
+
 createClient({
-  network: "mainnet" | "preprod" | "preview",
-  provider?: ProviderConfig,  // Optional
-  wallet?: WalletConfig       // Optional
+  chain: mainnet | preprod | preview,  // or a custom chain via defineChain(...)
+  provider?: ProviderConfig,           // Optional
+  wallet?: WalletConfig                // Optional
 })


This code sample calls createClient(...) but doesn’t import it (and also references ProviderConfig/WalletConfig without imports). The snippet should include createClient in the import (and either import the types or make the snippet explicitly schematic) so readers can copy/paste it without errors.

- Update wallet guide MDX files (api-wallet, private-key, seed-phrase) to use chain constants instead of network strings, fixing twoslash build errors (TS2769) - Migrate all 9 devnet test files from `network: 0` to `chain: Cluster.getChain(cluster)` / `Cluster.BOOTSTRAP_CHAIN`, fixing TypeError on `chain.id` - Update Cluster.getSlotConfig JSDoc example - Regenerate module reference docs

- Replace network: "preprod" / "mainnet" / "preview" with chain: preprod / mainnet / preview - Replace network: 0 with chain: Cluster.BOOTSTRAP_CHAIN / Cluster.getChain(cluster) - Add chain constant imports to all twoslash code blocks - Fix BOOTSTRAP_CHAIN epochLength type (number | undefined -> number) - Fix as const on chain references in provider-only-client.mdx - Update migration-from-lucid table and wallets/security guidance 52 docs files + 1 source file updated

solidsnakedev added 5 commits March 31, 2026 17:29

feat(client): replace NetworkId with Chain descriptor

ca54a58

feat(devnet): add getChain and BOOTSTRAP_CHAIN helpers

a25cb01

chore(example): migrate to chain: Chain pattern

342da47

docs(clients): update chain configuration examples

3866c80

release: changeset for chain-interface

c5abca1

Copilot AI review requested due to automatic review settings March 31, 2026 23:35

Copilot started reviewing on behalf of solidsnakedev March 31, 2026 23:36 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

solidsnakedev added 3 commits March 31, 2026 18:23

fix: align blockfrost URL fallback with chain fallback

7422aaa

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(client): replace NetworkId with Chain descriptor#223

feat(client): replace NetworkId with Chain descriptor#223
solidsnakedev wants to merge 8 commits intomainfrom
feat/chain-interface

solidsnakedev commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		"@evolution-sdk/evolution": patch
		"@evolution-sdk/devnet": patch

Conversation

solidsnakedev commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants