feat(client): replace NetworkId with Chain descriptor

.changeset/chain-interface.md

@@ -0,0 +1,47 @@
+---
+"@evolution-sdk/evolution": patch
+"@evolution-sdk/devnet": patch
+---
+
+`createClient` now requires an explicit `chain` field instead of the optional `network?: string` field.
+
+Previously, selecting a network required passing a string identifier and, separately, a `slotConfig` object for slot/time conversions. There was no single source of truth that tied network identity, magic number, and timing parameters together:
+
+```ts
+// Before
+createClient({
+  network: "preprod",
+  slotConfig: { zeroTime: 1655769600000n, zeroSlot: 86400n, slotLength: 1000 },
+  provider: { ... },
+  wallet: { ... }
+})
+```
+
+Now the `chain` field is a rich descriptor that carries all of this together. Three built-in constants are exported from the top-level package:
+
+```ts
+// After
+import { createClient, preprod } from "@evolution-sdk/evolution"
+
+createClient({
+  chain: preprod,
+  provider: { ... },
+  wallet: { ... }
+})
+```
+
+For custom networks — local devnets, private chains, or future forks — use `defineChain`:
+
+```ts
+import { defineChain } from "@evolution-sdk/evolution"
+
+const devnet = defineChain({
+  name: "Devnet",
+  id: 0,
+  networkMagic: 42,
+  slotConfig: { zeroTime: 0n, zeroSlot: 0n, slotLength: 1000 },
+  epochLength: 432000,
+})
+```
+
+The `networkId: number | string` property on client objects is replaced with `chain: Chain`. The `@evolution-sdk/devnet` package adds `getChain(cluster)` and `BOOTSTRAP_CHAIN` for constructing a `Chain` from a running local devnet.

docs/content/docs/clients/architecture.mdx

@@ -32,11 +32,11 @@ interface ReadOnlyWalletConfig {
 ### Backend Transaction Building
 
 ```typescript twoslash
-import { Address, Assets, Transaction, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, Transaction, createClient, mainnet } from "@evolution-sdk/evolution";
 
 // Backend: Create provider client, then attach read-only wallet
 const providerClient = createClient({
-  network: "mainnet",
+  chain: mainnet,
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
@@ -87,15 +87,15 @@ Frontend applications connect to user wallets through CIP-30 but never have prov
 ### Implementation
 
 ```typescript
-import { Address, Assets, Transaction, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, Transaction, createClient, mainnet } from "@evolution-sdk/evolution";
 
 // 1. Connect wallet
 declare const cardano: any;
 const walletApi = await cardano.eternl.enable();
 
 // 2. Create signing-only client
 const client = createClient({
-  network: "mainnet",
+  chain: mainnet,
   wallet: { type: "api", api: walletApi }
 });
 
@@ -193,7 +193,7 @@ export type BuildPaymentResponse = { txCbor: string };
 
 // @filename: frontend.ts
 // ===== Frontend (Browser) =====
-import { Address, Assets, Transaction, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, Transaction, createClient, mainnet } from "@evolution-sdk/evolution";
 import type { BuildPaymentResponse } from "./shared";
 
 declare const cardano: any;
@@ -202,7 +202,7 @@ async function sendPayment(recipientAddress: string, lovelace: bigint) {
   // 1. Connect user wallet
   const walletApi = await cardano.eternl.enable();
   const walletClient = createClient({
-    network: "mainnet",
+    chain: mainnet,
     wallet: { type: "api", api: walletApi }
   });
 
@@ -232,7 +232,7 @@ async function sendPayment(recipientAddress: string, lovelace: bigint) {
 
 // @filename: backend.ts
 // ===== Backend (Server) =====
-import { Address, Assets, Transaction, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, Transaction, createClient, mainnet } from "@evolution-sdk/evolution";
 
 export async function buildPayment(
   userAddressBech32: string,
@@ -244,7 +244,7 @@ export async function buildPayment(
 
   // Create provider client first, then attach read-only wallet
   const providerClient = createClient({
-    network: "mainnet",
+    chain: mainnet,
     provider: {
       type: "blockfrost",
       baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
@@ -302,7 +302,7 @@ User keys never leave their device. Provider API keys never exposed to frontend.
 ```typescript
 // WRONG - Frontend has no provider
 const client = createClient({
-  network: "mainnet",
+  chain: mainnet,
   wallet: { type: "api", api: walletApi }
   // No provider!
 });
@@ -315,7 +315,7 @@ const builder = client.newTx(); // Error: Cannot build without provider
 ```typescript
 // CORRECT - Frontend signs, backend builds
 const client = createClient({
-  network: "mainnet",
+  chain: mainnet,
   wallet: { type: "api", api: walletApi }
 });
 
@@ -328,7 +328,7 @@ const witnessSet = await client.signTx(txCborFromBackend);
 ```typescript
 // WRONG - Backend has no private keys
 const client = createClient({
-  network: "mainnet",
+  chain: mainnet,
   provider: { /* ... */ },
   wallet: {
     type: "read-only",
@@ -344,8 +344,8 @@ await client.sign(); // Error: Cannot sign with read-only wallet
 ```typescript
 // CORRECT - Backend builds, frontend signs
 const client = createClient({
-  network: "mainnet",
-    provider: { /* ... */ },
+  chain: mainnet,
+  provider: { /* ... */ },
   wallet: {
     type: "read-only",
     address: userAddress

docs/content/docs/clients/client-basics.mdx

@@ -7,17 +7,17 @@ description: "Learn the basics of creating and using an Evolution SDK client"
 
 The Evolution SDK client is your primary interface to the Cardano blockchain. It combines wallet management, provider communication, and transaction building into a single, cohesive API. Once configured, the client handles UTxO selection, fee calculation, and signing—letting you focus on your application logic.
 
-Think of the client as your persistent connection: configure it once with your network, provider, and wallet, then use it throughout your application to build and submit transactions. All operations maintain type safety and composability through Effect-TS.
+Think of the client as your persistent connection: configure it once with your chain, provider, and wallet, then use it throughout your application to build and submit transactions. All operations maintain type safety and composability through Effect-TS.
 
 ## Creating a Client
 
-Configure your client with three essential pieces: the network (mainnet/preprod/preview), your blockchain provider, and the wallet for signing:
+Configure your client with three essential pieces: the **chain** (which Cardano network to target), your blockchain provider, and the wallet for signing:
 
 ```ts twoslash
-import { Address, Assets, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
@@ -31,6 +31,38 @@ const client = createClient({
 });
 ```
 
+## Chain Configuration
+
+The `chain` field is a rich descriptor, not just a string identifier. It carries network magic, slot timing parameters, and optional block explorer URLs — everything the SDK needs to interact with a specific Cardano network.
+
+Evolution SDK exports three built-in chain constants:
+
+| Constant | Network | Network Magic |
+|----------|---------|---------------|
+| `mainnet` | Production | `764824073` |
+| `preprod` | Pre-production testnet | `1` |
+| `preview` | Preview testnet | `2` |
+
+```ts twoslash
+import { mainnet, preprod, preview } from "@evolution-sdk/evolution";
+```
+
+For custom networks — local devnets, private chains, or future Cardano forks — use `defineChain`:
+
+```ts twoslash
+import { defineChain } from "@evolution-sdk/evolution";
+
+const devnet = defineChain({
+  name: "Devnet",
+  id: 0,
+  networkMagic: 42,
+  slotConfig: { zeroTime: 0n, zeroSlot: 0n, slotLength: 1000 },
+  epochLength: 432000,
+});
+```
+
+The `slotConfig` is embedded in the chain constant and consumed directly by the transaction builder for slot-to-POSIX time conversions. There is no separate `slotConfig` parameter on `createClient`.
+
 ## The Transaction Workflow
 
 Evolution SDK follows a three-stage pattern: build, sign, submit. Each stage returns a new builder with stage-specific methods, preventing invalid operations (like submitting before signing).
@@ -40,10 +72,10 @@ Evolution SDK follows a three-stage pattern: build, sign, submit. Each stage ret
 Start with `client.newTx()` and chain operations to specify outputs, metadata, or validity ranges:
 
 ```ts twoslash
-import { Address, Assets, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: { type: "blockfrost", baseUrl: "", projectId: "" },
   wallet: { type: "seed", mnemonic: "", accountIndex: 0 }
 });
@@ -63,10 +95,10 @@ const signBuilder = await builder.build();
 Call `.sign()` on the built transaction to create signatures with your wallet:
 
 ```ts twoslash
-import { Address, Assets, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: { type: "blockfrost", baseUrl: "", projectId: "" },
   wallet: { type: "seed", mnemonic: "", accountIndex: 0 }
 });
@@ -83,10 +115,10 @@ const submitBuilder = await signBuilder.sign();
 Finally, `.submit()` broadcasts the signed transaction to the blockchain and returns the transaction hash:
 
 ```ts twoslash
-import { Address, Assets, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: { type: "blockfrost", baseUrl: "", projectId: "" },
   wallet: { type: "seed", mnemonic: "", accountIndex: 0 }
 });
@@ -105,10 +137,10 @@ console.log("Transaction submitted:", txId);
 Here's the complete workflow in a single example—from client creation through transaction submission:
 
 ```ts twoslash
-import { Address, Assets, createClient } from "@evolution-sdk/evolution";
+import { Address, Assets, createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",

docs/content/docs/clients/index.mdx

@@ -30,10 +30,12 @@ Different combinations create different client types with distinct capabilities.
 All clients use `createClient` with different configurations:
 
 ```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
 })
 ```
 

docs/content/docs/clients/providers.mdx

@@ -14,10 +14,10 @@ Choose Blockfrost for quick setup with hosted infrastructure, or Kupmios for sel
 Blockfrost offers hosted infrastructure with a free tier, perfect for development and small-scale applications. Setup takes minutes—just get an API key and connect.
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
@@ -41,10 +41,10 @@ const client = createClient({
 Run your own Cardano node infrastructure for complete control and privacy. Kupmios combines Kupo (UTxO indexing) and Ogmios (node queries) for a fully local setup. Ideal for production applications that need guaranteed uptime and don't want external dependencies.
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, preprod } from "@evolution-sdk/evolution";
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "kupmios",
     kupoUrl: "http://localhost:1442",
@@ -79,11 +79,11 @@ Use Blockfrost for rapid prototyping and development. Switch to Kupmios when you
 The beauty of Evolution SDK's provider abstraction: your transaction code doesn't change. Only the configuration does:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, preprod } from "@evolution-sdk/evolution";
 
 // Start with Blockfrost
 const blockfrostClient = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
@@ -98,7 +98,7 @@ const blockfrostClient = createClient({
 
 // Switch to Kupmios
 const kupmiosClient = createClient({
-  network: "preprod",
+  chain: preprod,
   provider: {
     type: "kupmios",
     kupoUrl: "http://localhost:1442",
@@ -126,7 +126,7 @@ OGMIOS_URL=http://localhost:1337
 Then in your code:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, preprod } from "@evolution-sdk/evolution";
 
 const provider = process.env.BLOCKFROST_API_KEY
   ? {
@@ -141,7 +141,7 @@ const provider = process.env.BLOCKFROST_API_KEY
     };
 
 const client = createClient({
-  network: "preprod",
+  chain: preprod,
   provider,
   wallet: {
     type: "seed",

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

@@ -1,7 +1,7 @@
 import { useCardano } from "@cardano-foundation/cardano-connect-with-wallet"
 import { NetworkType } from "@cardano-foundation/cardano-connect-with-wallet-core"
 import { useState } from "react"
-import { Address, Assets, createClient, TransactionHash } from "@evolution-sdk/evolution"
+import { Address, Assets, createClient, mainnet, preprod, preview, TransactionHash } from "@evolution-sdk/evolution"
 
 export default function TransactionBuilder() {
   const [txHash, setTxHash] = useState<string | null>(null)
@@ -46,8 +46,9 @@ export default function TransactionBuilder() {
         throw new Error("Failed to enable wallet")
       }
 
-      // Determine network ID and provider config
-      const networkId = networkEnv // "preprod", "preview", or "mainnet"
+      // Determine chain from environment variable
+      const chainMap = { mainnet, preprod, preview } as const
+      const chain = chainMap[networkEnv as keyof typeof chainMap] ?? preprod
 
       // Configure Blockfrost provider based on network
       const blockfrostUrls = {
@@ -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 || ""
       }
 
       // Create client with wallet and provider
       const client = createClient({
-        network: networkId,
+        chain,
         provider: providerConfig,
         wallet: { type: "api", api }
       })