feat!: change params to options object and remove withIpni (#601)

Author: hugomrdias

docs/src/content/docs/developer-guides/migration-guide.md

@@ -9,36 +9,129 @@ If you are coming from an earlier version of any of the Synapse packages, you wi
 
 ---
 
-## `@filoz/synapse-sdk` 0.37.0
+## 0.37.0
 
-<!-- Check out the [changelog](/changelog-sdk/version/0-37-0/) for more information. -->
+`synapse-sdk` moved to a viem-first API, removed deprecated modules/methods, and standardized method signatures around options objects plus `bigint` identifiers.
 
-The main entrypoint `@filoz/synapse-sdk` no longer export all the other modules, from this version onwards it will only export the `Synapse` class, constants and types. Check [reference](/reference/filoz/synapse-sdk/synapse/toc/) for the current exports.
+### Action: Migrate from `ethers` setup to `viem` setup
 
-### Action: Change `import` statements
+```ts
+// before
+import { Synapse } from '@filoz/synapse-sdk'
+
+const synapse = await Synapse.create({
+  privateKey: PRIVATE_KEY,
+  rpcURL: 'https://api.calibration.node.glif.io/rpc/v1'
+})
+
+// after
+import { calibration } from '@filoz/synapse-sdk'
+import { privateKeyToAccount } from 'viem/accounts'
+import { http } from 'viem'
+import { Synapse } from '@filoz/synapse-sdk'
+
+const synapse = Synapse.create({
+  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
+  chain: calibration, // optional
+  transport: http() // optional
+})
+```
+
+### Action: Remove deprecated SDK module imports
+
+The following subpath exports were removed from `@filoz/synapse-sdk`:
+
+- `@filoz/synapse-sdk/pdp`
+- `@filoz/synapse-sdk/subgraph`
+- `@filoz/synapse-sdk/telemetry`
 
 ```ts
-// before 
-import { 
-  PaymentService, 
-  PDPAuthHelper, 
-  PDPServer, 
-  PDPVerifier,
-  SessionKey,
-  StorageContext,
-  StorageManager,
-  WarmStorageService
-} from '@filoz/synapse-sdk'
-
-// after 
-import { PaymentService } from '@filoz/synapse-sdk/payments'
+// before
 import { PDPAuthHelper, PDPServer, PDPVerifier } from '@filoz/synapse-sdk/pdp'
-import { SessionKey } from '@filoz/synapse-sdk/session'
-import { StorageContext, StorageManager } from '@filoz/synapse-sdk/manager'
+import { SubgraphService } from '@filoz/synapse-sdk/subgraph'
+import { getGlobalTelemetry } from '@filoz/synapse-sdk/telemetry'
+
+// after
+import { Synapse } from '@filoz/synapse-sdk'
+import { PaymentsService } from '@filoz/synapse-sdk/payments'
+import { SPRegistryService } from '@filoz/synapse-sdk/sp-registry'
+import { StorageContext, StorageManager } from '@filoz/synapse-sdk/storage'
 import { WarmStorageService } from '@filoz/synapse-sdk/warm-storage'
+```
+
+### Action: Convert positional parameters to object parameters
 
+Most service methods now take an options object. IDs are now `bigint` in the public API.
+
+```ts
+// before
+await synapse.storage.download(pieceCid, { withCDN: true })
+await synapse.payments.allowance(spender)
+await synapse.payments.settle(12, 5000)
+await synapse.providers.getProvider(1)
+
+// after
+await synapse.storage.download({ pieceCid, withCDN: true })
+await synapse.payments.allowance({ spender })
+await synapse.payments.settle({ railId: 12n, untilEpoch: 5000n })
+await synapse.providers.getProvider({ providerId: 1n })
 ```
 
+This change applies broadly across:
+
+- `PaymentsService`
+- `WarmStorageService`
+- `SPRegistryService`
+- retrievers and storage download APIs
+
+### Action: Replace removed deprecated methods
+
+Deprecated methods that were previously shimmed were removed from `Synapse`.
+
+```ts
+// before
+const storage = await synapse.createStorage({ providerId: 1 })
+const data = await synapse.download(pieceCid)
+const info = await synapse.getStorageInfo()
+
+// after
+const context = await synapse.storage.createContext({ providerId: 1n })
+const data = await synapse.storage.download({ pieceCid })
+const info = await synapse.storage.getStorageInfo()
+```
+
+### Action: Update dataset and callback assumptions
+
+```ts
+// before
+if (dataSet.currentPieceCount > 0) {
+  // ...
+}
+
+callbacks: {
+  onPieceAdded: () => {},
+  onPieceConfirmed: () => {}
+}
+
+// after
+if (dataSet.activePieceCount > 0n) {
+  // ...
+}
+
+callbacks: {
+  onPiecesAdded: (txHash, pieces) => {},
+  onPiecesConfirmed: (dataSetId, pieces) => {}
+}
+```
+
+### Migration checklist for this range
+
+1. Replace `ethers`-based initialization (`privateKey`/`provider`/`signer`) with viem (`account` + `transport` + `chain`).
+2. Remove imports from `@filoz/synapse-sdk/pdp`, `@filoz/synapse-sdk/subgraph`, and `@filoz/synapse-sdk/telemetry`.
+3. Migrate method calls to options-object style and switch numeric IDs to `bigint`.
+4. Replace removed deprecated methods (`synapse.createStorage`, `synapse.download`, `synapse.getStorageInfo`) with `synapse.storage.*`.
+5. Update dataset field usage (`currentPieceCount` -> `activePieceCount`) and callback names (`onPieceAdded`/`onPieceConfirmed` -> plural callbacks).
+
 ## 0.24.0+
 
 ### Terminology Update

docs/src/content/docs/developer-guides/payments/payment-operations.mdx

@@ -49,7 +49,7 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 import { TOKENS } from "@filoz/synapse-sdk";
 
 const amount = parseUnits("100");
-const hash = await synapse.payments.depositWithPermit(amount);
+const hash = await synapse.payments.depositWithPermit({ amount });
 await synapse.client.waitForTransactionReceipt({ hash });
 ```
 
@@ -63,7 +63,7 @@ If you cannot use permit-based deposits, you can use the traditional two-transac
 await usdfc.approve(paymentAddress, depositAmount);
 
 // 2. Deposit
-await synapse.payments.deposit(depositAmount);
+await synapse.payments.deposit({ amount });
 ```
 
 This requires two transactions and higher gas costs. Use `depositWithPermit` instead.
@@ -101,7 +101,7 @@ import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 // ---cut---
 const info = await synapse.payments.accountInfo();
-await synapse.payments.withdraw(info.availableFunds);
+await synapse.payments.withdraw({ amount: info.availableFunds });
 ```
 
 ## Approving Operators
@@ -134,12 +134,7 @@ const rateAllowance = monthlyPricePerTiB / TIME_CONSTANTS.EPOCHS_PER_MONTH;
 const lockupAllowance = monthlyPricePerTiB * months;
 const maxLockupPeriod = TIME_CONSTANTS.EPOCHS_PER_MONTH;
 
-await synapse.payments.approveService(
-  calibration.contracts.fwss.address,
-  rateAllowance,
-  lockupAllowance,
-  maxLockupPeriod
-);
+await synapse.payments.approveService();
 ```
 
 ### Revoking an Operator
@@ -152,7 +147,7 @@ import { Synapse, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 // ---cut---
-await synapse.payments.revokeService(calibration.contracts.fwss.address);
+await synapse.payments.revokeService();
 ```
 
 ### Checking Operator Approvals
@@ -163,7 +158,7 @@ import { Synapse, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 // ---cut---
-const approval = await synapse.payments.serviceApproval(calibration.contracts.fwss.address);
+const approval = await synapse.payments.serviceApproval();
 
 console.log("Approved:", approval.isApproved);
 console.log(

docs/src/content/docs/developer-guides/payments/rails-settlement.mdx

@@ -116,7 +116,7 @@ import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = null as unknown as bigint;
 // ---cut---
-const railInfo = await synapse.payments.getRail(railId);
+const railInfo = await synapse.payments.getRail({ railId });
 console.log("Rail details:", {
   from: railInfo.from,
   to: railInfo.to,
@@ -150,12 +150,12 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = 1n;
 // ---cut---
 // Automatically handles both active and terminated rails
-const hash1 = await synapse.payments.settleAuto(railId);
+const hash1 = await synapse.payments.settleAuto({ railId });
 await synapse.client.waitForTransactionReceipt({ hash: hash1 });
 console.log("Rail settled successfully");
 
 // For active rails, you can specify the epoch to settle up to
-const hash2 = await synapse.payments.settleAuto(railId, 1000n);
+const hash2 = await synapse.payments.settleAuto({ railId, untilEpoch: 1000n });
 await synapse.client.waitForTransactionReceipt({ hash: hash2 });
 console.log("Rail settled successfully up to epoch 1000");
 ```
@@ -176,7 +176,7 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = 1n;
 // ---cut---
 // Settle a specific rail (requires settlement fee)
-const hash = await synapse.payments.settle(railId);
+const hash = await synapse.payments.settle({ railId });
 await synapse.client.waitForTransactionReceipt({ hash });
 console.log("Rail settled successfully");
 ```
@@ -197,7 +197,7 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = 1n;
 // ---cut---
 const targetEpoch = 1000n; // Ensure it's not in the future
-const hash = await synapse.payments.settle(railId, targetEpoch);
+const hash = await synapse.payments.settle({ railId, untilEpoch: targetEpoch });
 await synapse.client.waitForTransactionReceipt({ hash });
 ```
 
@@ -220,11 +220,11 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = 1n;
 // ---cut---
 // Check if rail is terminated
-const railInfo = await synapse.payments.getRail(railId);
+const railInfo = await synapse.payments.getRail({ railId });
 if (railInfo.endEpoch > 0) {
   console.log(`Rail terminated at epoch ${railInfo.endEpoch}`);
   // Settle the terminated rail
-  const hash = await synapse.payments.settleTerminatedRail(railId);
+  const hash = await synapse.payments.settleTerminatedRail({ railId });
   await synapse.client.waitForTransactionReceipt({ hash });
   console.log("Terminated rail settled and closed");
 }
@@ -244,7 +244,7 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
 const railId = 1n;
 // ---cut---
 // Preview settlement to current epoch
-const amounts = await synapse.payments.getSettlementAmounts(railId);
+const amounts = await synapse.payments.getSettlementAmounts({ railId });
 const totalSettledAmount = formatUnits(amounts.totalSettledAmount);
 const totalNetPayeeAmount = formatUnits(amounts.totalNetPayeeAmount);
 const totalOperatorCommission = formatUnits(amounts.totalOperatorCommission);
@@ -259,14 +259,11 @@ console.log(`  Settled up to epoch: ${finalSettledEpoch}`);
 console.log(`  Note: ${note}`);
 
 // Preview partial settlement to a specific past epoch
-const targetEpoch = 1000n; // Must be less than or equal to current epoch
-const partialAmounts = await synapse.payments.getSettlementAmounts(
-  railId,
-  targetEpoch
-);
+const untilEpoch = 1000n; // Must be less than or equal to current epoch
+const partialAmounts = await synapse.payments.getSettlementAmounts({ railId, untilEpoch });
 const partialTotalSettledAmount = formatUnits(partialAmounts.totalSettledAmount);
 console.log(
-  `Partial settlement to epoch ${targetEpoch} -`,
+  `Partial settlement to epoch ${untilEpoch} -`,
   `would settle: ${partialTotalSettledAmount} USDFC`
 );
 ```
@@ -290,13 +287,13 @@ async function settleAllIncomingRails() {
   for (const rail of rails) {
     try {
       // Check if settlement is worthwhile
-      const amounts = await synapse.payments.getSettlementAmounts(rail.railId);
+      const amounts = await synapse.payments.getSettlementAmounts({ railId: rail.railId });
 
       // Only settle if amount exceeds threshold (e.g., $10)
       const threshold = parseUnits("10"); // 10 USDFC
       if (amounts.totalNetPayeeAmount > threshold) {
         // settleAuto handles both active and terminated rails
-        const hash = await synapse.payments.settleAuto(rail.railId);
+        const hash = await synapse.payments.settleAuto({ railId: rail.railId });
         await synapse.client.waitForTransactionReceipt({ hash });
         console.log(
           `Settled rail ${rail.railId} for ${formatUnits(amounts.totalNetPayeeAmount)} USDFC`
@@ -328,7 +325,7 @@ async function prepareForWithdrawal() {
 
   // Settle all rails to update balance (settleAuto handles both active and terminated)
   for (const rail of rails) {
-    const hash = await synapse.payments.settleAuto(rail.railId);
+    const hash = await synapse.payments.settleAuto({ railId: rail.railId });
     await synapse.client.waitForTransactionReceipt({ hash });
   }
 
@@ -347,7 +344,7 @@ Common settlement errors and solutions:
 
 ```typescript
 try {
-  await synapse.payments.settle(railId);
+  await synapse.payments.settle({railId});
 } catch (error) {
   if (error.message.includes("InsufficientNativeTokenForBurn")) {
     console.error("Insufficient FIL for settlement fee (0.0013 FIL required)");

docs/src/content/docs/developer-guides/storage/storage-context.mdx

@@ -156,12 +156,8 @@ export interface UploadCallbacks {
   onUploadComplete?: (pieceCid: PieceCID) => void;
   /** Called when the service provider has added the piece(s) and submitted the transaction to the chain */
   onPiecesAdded?: (transaction?: Hex, pieces?: { pieceCid: PieceCID }[]) => void;
-  /** @deprecated Use onPiecesAdded instead */
-  onPieceAdded?: (transaction?: Hex) => void;
   /** Called when the service provider agrees that the piece addition(s) are confirmed on-chain */
   onPiecesConfirmed?: (dataSetId: number, pieces: PieceRecord[]) => void;
-  /** @deprecated Use onPiecesConfirmed instead */
-  onPieceConfirmed?: (pieceIds: number[]) => void;
 }
 
 /**
@@ -233,7 +229,7 @@ const conversationId = "1234567890";
 
 const data = new TextEncoder().encode("Deep research on decentralization...")
 
-const preflight = await storageContext.preflightUpload(data.length);
+const preflight = await storageContext.preflightUpload({ size: data.length });
 
 console.log("Estimated costs:", preflight.estimatedCost);
 console.log("Allowance sufficient:", preflight.allowanceCheck.sufficient);
@@ -265,16 +261,16 @@ const { pieceCid, size, pieceId } = await storageContext.upload(data, {
   },
 });
 
-const receivedData = await storageContext.download(pieceCid);
+const receivedData = await storageContext.download({ pieceCid });
 
 console.log(`Received data: ${new TextDecoder().decode(receivedData)}`);
 
 // Get the list of piece CIDs in the current data set by querying the provider
-const pieceCids = await storageContext.getDataSetPieces();
+const pieceCids = await Array.fromAsync(storageContext.getPieces());
 console.log(`Piece CIDs: ${pieceCids.map((cid) => cid.toString()).join(", ")}`);
 
 // Check the status of a piece on the service provider
-const status = await storageContext.pieceStatus(pieceCid);
+const status = await storageContext.pieceStatus({ pieceCid });
 console.log(`Piece exists: ${status.exists}`);
 console.log(`Data set last proven: ${status.dataSetLastProven}`);
 console.log(`Data set next proof due: ${status.dataSetNextProofDue}`);
@@ -361,7 +357,7 @@ for await (const piece of storageContext.getPieces()) {
 }
 
 // Delete the first piece
-await storageContext.deletePiece(pieces[0].pieceId);
+await storageContext.deletePiece({ piece: pieces[0].pieceId });
 console.log(
   `Piece ${pieces[0].pieceCid} (ID: ${pieces[0].pieceId}) deleted successfully`
 );