feat: support custom client for reads (#909)

Author: hugomrdias

docs/package.json

@@ -4,11 +4,43 @@
   "version": "0.0.1",
   "private": true,
   "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
+    "dev": "wireit",
+    "build": "wireit",
     "preview": "astro preview",
     "astro": "astro"
   },
+  "wireit": {
+    "build": {
+      "command": "astro build",
+      "files": [
+        "src/**/*.ts",
+        "tsconfig.json",
+        "astro.config.mjs"
+      ],
+      "output": [
+        "dist/**"
+      ],
+      "dependencies": [
+        "../packages/synapse-core:build",
+        "../packages/synapse-sdk:build",
+        "../packages/synapse-react:build"
+      ]
+    },
+    "dev": {
+      "command": "astro dev",
+      "service": true,
+      "files": [
+        "src/**/*.ts",
+        "tsconfig.json",
+        "astro.config.mjs"
+      ],
+      "dependencies": [
+        "../packages/synapse-core:build",
+        "../packages/synapse-sdk:build",
+        "../packages/synapse-react:build"
+      ]
+    }
+  },
   "dependencies": {
     "@filoz/synapse-core": "workspace:*",
     "@filoz/synapse-react": "workspace:*",

docs/src/components/contract-addresses.astro

@@ -1,8 +1,8 @@
 ---
-import type { Chain } from '@filoz/synapse-core/chains'
+import type { FilecoinChain } from '@filoz/synapse-core/chains'
 
 interface Props {
-  chain: Chain
+  chain: FilecoinChain
 }
 
 const { chain } = Astro.props

docs/src/content/docs/developer-guides/synapse-core.mdx

@@ -47,26 +47,29 @@ All Synapse Core functions accept a viem `Client` as their first argument. Creat
 
 ```ts twoslash
 // @lib: esnext,dom
-import { createPublicClient, createWalletClient, http } from "viem"
+import { createPublicClient, createWalletClient } from "viem"
 import { privateKeyToAccount } from "viem/accounts"
-import { calibration, mainnet } from "@filoz/synapse-core/chains"
+import { calibration } from "@filoz/synapse-core/chains"
+import { getTransport } from "@filoz/synapse-core/client"
 
 // Read-only client for queries
 const publicClient = createPublicClient({
   chain: calibration, // or mainnet
-  transport: http(),
+  transport: getTransport(calibration),
 })
 
 // Wallet client for transactions
 const account = privateKeyToAccount("0x...")
 const walletClient = createWalletClient({
   account,
   chain: calibration, // or mainnet
-  transport: http(),
+  transport: getTransport(calibration),
 })
 ```
 
-The `@filoz/synapse-core/chains` subpath exports chain definitions with all contract addresses pre-configured for Filecoin Mainnet (`mainnet`) and Filecoin testnet (`calibration`) networks.
+The `@filoz/synapse-core/chains` subpath exports chain definitions with all contract addresses pre-configured for Filecoin Mainnet (`mainnet`) and Filecoin testnet (`calibration`) networks. Import the FOC chain type as `FilecoinChain` when you need it in TypeScript.
+
+The `@filoz/synapse-core/client` subpath exports `getTransport` (ranked Filecoin RPC fallbacks), `asClient`, and `toReadClient`. Prefer `getTransport(chain)` over a bare `http()` endpoint when talking to mainnet or Calibration.
 
 ## Pagination
 

docs/src/content/docs/developer-guides/synapse.md

@@ -55,6 +55,15 @@ graph LR
 - **`StorageManager`**, **`StorageContext`**: Storage operation modules
 - **`WarmStorageService`**: Storage coordination and pricing module
 
+`Synapse` exposes `client` (account client for signing and writes) and `readClient` (for queries). When constructing from an existing viem client, you can pass an optional public `readClient`:
+
+```ts
+const synapse = new Synapse({
+  client: walletClient,
+  readClient: publicClient, // optional; derived from client when omitted
+})
+```
+
 ## Payment Operations
 
 Fund your account and manage payments for Filecoin storage services.

examples/cli/src/client.ts

@@ -1,18 +1,11 @@
 import { execSync } from 'node:child_process'
 import { basename, dirname } from 'node:path'
 import * as p from '@clack/prompts'
-import { type Chain, getChain } from '@filoz/synapse-core/chains'
-import {
-  createPublicClient,
-  createWalletClient,
-  type Hex,
-  type HttpTransport,
-  http,
-  type PrivateKeyAccount,
-  type PublicClient,
-  type WalletClient,
-} from 'viem'
-import { privateKeyToAccount } from 'viem/accounts'
+import type { AccountClient, ReadClient } from '@filoz/synapse-core'
+import { type FilecoinChain, getChain } from '@filoz/synapse-core/chains'
+import { getTransport } from '@filoz/synapse-core/client'
+import { createPublicClient, createWalletClient, type Hex } from 'viem'
+import { type Address, privateKeyToAccount } from 'viem/accounts'
 import config from './config.ts'
 
 function privateKeyFromConfig() {
@@ -47,8 +40,9 @@ function privateKeyFromConfig() {
 }
 
 export function privateKeyClient(chainId: number): {
-  client: WalletClient<HttpTransport, Chain, PrivateKeyAccount>
-  chain: Chain
+  client: AccountClient
+  chain: FilecoinChain
+  address: Address
 } {
   const chain = getChain(chainId)
 
@@ -58,21 +52,20 @@ export function privateKeyClient(chainId: number): {
   const client = createWalletClient({
     account,
     chain,
-    transport: http(),
+    transport: getTransport(chain),
   })
   return {
     client,
     chain,
+    address: account.address,
   }
 }
 
-export function publicClient(
-  chainId: number
-): PublicClient<HttpTransport, Chain> {
+export function publicClient(chainId: number): ReadClient {
   const chain = getChain(chainId)
   const publicClient = createPublicClient({
     chain,
-    transport: http(),
+    transport: getTransport(chain),
   })
   return publicClient
 }

examples/cli/src/commands/datasets-create.ts

@@ -31,7 +31,6 @@ export const datasetsCreate: Command = command(
   },
   async (argv) => {
     const { client, chain } = privateKeyClient(argv.flags.chain)
-
     try {
       const provider = argv._.providerId
         ? await getPDPProvider(client, {

examples/cli/src/commands/datasets-terminate.ts

@@ -29,12 +29,11 @@ export const datasetsTerminate: Command = command(
     },
   },
   async (argv) => {
-    const { client, chain } = privateKeyClient(argv.flags.chain)
-
+    const { client, chain, address } = privateKeyClient(argv.flags.chain)
     try {
       const dataSetId = argv._.dataSetId
         ? BigInt(argv._.dataSetId)
-        : await selectDataSet(client, argv.flags)
+        : await selectDataSet(client, address, argv.flags)
       p.log.info(`Terminating data set ${dataSetId}...`)
 
       let endEpoch: bigint

examples/cli/src/commands/pieces-removal.ts

@@ -22,12 +22,12 @@ export const piecesRemoval: Command = command(
     },
   },
   async (argv) => {
-    const { client, chain } = privateKeyClient(argv.flags.chain)
+    const { client, chain, address } = privateKeyClient(argv.flags.chain)
 
     try {
       const dataSetId = argv._.dataSetId
         ? BigInt(argv._.dataSetId)
-        : await selectDataSet(client, argv.flags)
+        : await selectDataSet(client, address, argv.flags)
 
       const dataSet = await getPdpDataSet(client, {
         dataSetId,
@@ -39,7 +39,7 @@ export const piecesRemoval: Command = command(
 
       const pieceId = argv._.pieceId
         ? BigInt(argv._.pieceId)
-        : await selectPiece(client, dataSet, argv.flags)
+        : await selectPiece(client, address, dataSet, argv.flags)
 
       p.log.info(`Removing piece ${pieceId} from data set ${dataSetId}...`)
       const result = await schedulePieceDeletions(client, {

examples/cli/src/commands/pieces.ts

@@ -6,16 +6,11 @@ import { metadataArrayToObject } from '@filoz/synapse-core/utils'
 import { getPdpDataSets, type Piece } from '@filoz/synapse-core/warm-storage'
 import { Synapse } from '@filoz/synapse-sdk'
 import { type Command, command } from 'cleye'
-import { createPublicClient, type Hex, http, stringify } from 'viem'
+import { type Hex, stringify } from 'viem'
 import { readContract, waitForTransactionReceipt } from 'viem/actions'
 import { privateKeyClient } from '../client.ts'
 import { globalFlags } from '../flags.ts'
 
-const publicClient = createPublicClient({
-  chain: calibration,
-  transport: http(),
-})
-
 export const pieces: Command = command(
   {
     name: 'pieces',
@@ -30,16 +25,15 @@ export const pieces: Command = command(
     },
   },
   async (argv) => {
-    const { client } = privateKeyClient(argv.flags.chain)
-
+    const { client, address } = privateKeyClient(argv.flags.chain)
     const spinner = p.spinner()
 
     spinner.start('Fetching data sets...')
     try {
       const dataSets = await Array.fromAsync(
         paginate(({ cursor }) =>
           getPdpDataSets(client, {
-            address: client.account.address,
+            address,
             cursor,
           })
         )
@@ -68,7 +62,7 @@ export const pieces: Command = command(
                   dataSet: dataSets.find(
                     (dataSet) => dataSet.dataSetId === dataSetId
                   )!,
-                  address: client.account.address,
+                  address,
                   cursor,
                 })
               )
@@ -111,7 +105,7 @@ export const pieces: Command = command(
       if (group.action === 'info') {
         // biome-ignore lint/style/noNonNullAssertion: pieceId is guaranteed to be found
         const piece = pieces.find((piece) => piece.id === group.pieceId)!
-        const metadata = await readContract(publicClient, {
+        const metadata = await readContract(client, {
           address: calibration.contracts.fwssView.address,
           abi: calibration.contracts.fwssView.abi,
           functionName: 'getAllPieceMetadata',
@@ -140,7 +134,7 @@ export const pieces: Command = command(
         })
         const txHash = await context.deletePiece({ piece: piece.cid })
         spinner.message('Waiting for transaction to be mined...')
-        await waitForTransactionReceipt(publicClient, { hash: txHash as Hex })
+        await waitForTransactionReceipt(client, { hash: txHash as Hex })
         spinner.stop('Piece deleted')
       } else {
         return

examples/cli/src/commands/upload-dataset.ts

@@ -31,7 +31,9 @@ export const uploadDataset: Command = command(
 
     const filePath = argv._.path
     const provider = argv._.providerId
-      ? await getPDPProvider(client, { providerId: BigInt(argv._.providerId) })
+      ? await getPDPProvider(client, {
+          providerId: BigInt(argv._.providerId),
+        })
       : await selectProvider(client, argv.flags)
 
     if (!provider) {