feat(sdk)!: require source parameter for dataset namespace isolation (#647)

Author: rvagg

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

@@ -27,6 +27,7 @@ import { Synapse } from '@filoz/synapse-sdk'
 const synapse = await Synapse.create({
   privateKey: process.env.PRIVATE_KEY,
   rpcURL: process.env.RPC_URL,
+  source: 'my-app',
   warmStorageAddress: process.env.WARM_STORAGE_ADDRESS,
   multicall3Address: process.env.MULTICALL3_ADDRESS,
   // Optional: override USDFC token address

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

@@ -32,6 +32,7 @@ import { Synapse } from '@filoz/synapse-sdk'
 
 const synapse = Synapse.create({
   account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
+  source: 'my-app',
   chain: calibration, // optional
   transport: http() // optional
 })

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

@@ -28,7 +28,7 @@ Monitor your account balance to ensure you have sufficient funds for storage ope
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 const walletBalance = await synapse.payments.walletBalance();
 const accountInfo = await synapse.payments.accountInfo();
@@ -44,7 +44,7 @@ console.log("Spending rate:", accountInfo.lockupRate, "per epoch");
 // @lib: esnext,dom
 import { Synapse, parseUnits } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 import { TOKENS } from "@filoz/synapse-sdk";
 
@@ -62,7 +62,7 @@ If you cannot use permit-based deposits, you can use the traditional two-transac
 // @lib: esnext,dom
 import { Synapse, parseUnits } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 const filecoinpay = synapse.chain.contracts.filecoinPay.address
 const amount = parseUnits("100");
@@ -86,7 +86,7 @@ This requires two transactions and higher gas costs. Use `depositWithPermit` ins
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 import { TIME_CONSTANTS } from "@filoz/synapse-sdk";
 
@@ -106,7 +106,7 @@ if (daysRemaining < 7) console.warn("⚠️ Low balance!");
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
 
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 const info = await synapse.payments.accountInfo();
 await synapse.payments.withdraw({ amount: info.availableFunds });
@@ -131,7 +131,7 @@ Approving warmStorage for 1TiB of storage for 3 months.
 import { Synapse, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
 
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const monthlyPricePerTiB = null as unknown as bigint;
 // ---cut---
 import { TIME_CONSTANTS } from "@filoz/synapse-sdk";
@@ -153,7 +153,7 @@ Revoking warmStorage's operator approvals.
 // @lib: esnext,dom
 import { Synapse, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 await synapse.payments.revokeService();
 ```
@@ -164,7 +164,7 @@ await synapse.payments.revokeService();
 // @lib: esnext,dom
 import { Synapse, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 const approval = await synapse.payments.serviceApproval();
 

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

@@ -79,7 +79,7 @@ Check rails where you're the payer:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') })
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })
 // ---cut---
 const payerRails = await synapse.payments.getRailsAsPayer();
 console.log(`You have ${payerRails.length} outgoing payment rails`);
@@ -99,7 +99,7 @@ Check rails where you're receiving payments:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 const payeeRails = await synapse.payments.getRailsAsPayee();
 console.log(`You have ${payeeRails.length} incoming payment rails`);
@@ -113,7 +113,7 @@ For detailed information about a specific rail:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = null as unknown as bigint;
 // ---cut---
 const railInfo = await synapse.payments.getRail({ railId });
@@ -146,7 +146,7 @@ The simplest way to settle a rail is using `settleAuto()`, which automatically d
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 // Automatically handles both active and terminated rails
@@ -172,7 +172,7 @@ Settle up to the current epoch:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 // Settle a specific rail (requires settlement fee)
@@ -193,7 +193,7 @@ Settle up to a specific past epoch (partial settlement):
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 const targetEpoch = 1000n; // Ensure it's not in the future
@@ -216,7 +216,7 @@ When a rail is terminated, use the specific method for terminated rails:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 // Check if rail is terminated
@@ -240,7 +240,7 @@ if (railInfo.endEpoch > 0) {
 // @lib: esnext,dom
 import { Synapse, formatUnits } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 // Preview settlement to current epoch
@@ -278,7 +278,7 @@ Service providers (payees) should settle regularly to receive accumulated earnin
 // @lib: esnext,dom
 import { Synapse, parseUnits, formatUnits } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 // Example: Settle all incoming rails using settleAuto
 async function settleAllIncomingRails() {
@@ -317,7 +317,7 @@ Clients (payers) typically don't need to settle unless:
 // @lib: esnext,dom
 import { Synapse, parseUnits, formatUnits } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 // ---cut---
 // Example: Settle before withdrawal
 async function prepareForWithdrawal() {
@@ -346,7 +346,7 @@ Common settlement errors and solutions:
 // @lib: esnext,dom
 import { Synapse } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const railId = 1n;
 // ---cut---
 try {

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

@@ -51,7 +51,7 @@ A Storage Context represents a connection to a specific storage provider and dat
 import { Synapse } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 
 // Single context — auto-selects provider
 await synapse.storage.createContext({
@@ -126,7 +126,7 @@ Upload data to a provider without committing on-chain:
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const data = new TextEncoder().encode("Hello, Filecoin!")
 const abortController = new AbortController()
 const preCalculatedCid = null as unknown as PieceCID;
@@ -164,7 +164,7 @@ Request a secondary provider to fetch pieces from the primary:
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const [primary, secondary] = await synapse.storage.createContexts({
       count: 2,
   metadata: { source: "my-app" },
@@ -207,7 +207,7 @@ Add pieces to an on-chain data set. Creates the data set and payment rail if one
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 import type { Hex } from "viem";
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const contexts = await synapse.storage.createContexts({
       count: 2,
   metadata: { source: "my-app" },
@@ -260,7 +260,7 @@ Upload multiple files to 2 providers with full error handling:
 import { Synapse } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x..")})
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 
 const files = [
   new TextEncoder().encode("File 1 content..."),
@@ -348,7 +348,7 @@ You can also terminate a data set using `synapse.storage.terminateDataSet({ data
 import { Synapse } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const ctx = await synapse.storage.createContext({
   metadata: { source: "my-app" },
 })
@@ -374,7 +374,7 @@ This method submits an on-chain transaction to initiate the deletion process.
 import { Synapse } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const ctx = await synapse.storage.createContext({
   metadata: { source: "my-app" },
 })
@@ -408,7 +408,7 @@ Download pieces from any available provider using the StorageManager:
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const pieceCid = null as unknown as PieceCID;
 // ---cut---
 // Download from any provider that has the piece
@@ -427,7 +427,7 @@ When using a StorageContext, downloads are automatically restricted to that spec
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const ctx = await synapse.storage.createContext({
   metadata: { source: "my-app" },
 })
@@ -449,7 +449,7 @@ The `withCDN` option follows a clear inheritance hierarchy:
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const ctx = await synapse.storage.createContext({ withCDN: false })
 const pieceCid = null as unknown as PieceCID;
 // ---cut---
@@ -471,7 +471,7 @@ For maximum control, use the core library functions without the SDK wrapper clas
 import { Synapse, type PieceCID } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const ctx = await synapse.storage.createContext({
   metadata: { source: "my-app" },
 })
@@ -517,7 +517,7 @@ The `endorsedIds` parameter controls which providers are eligible. When non-empt
 import { Synapse, type PieceCID, asChain } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from "viem/accounts"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const client = synapse.client;
 const chain = asChain(client.chain);
 const walletAddress = client.account.address;
@@ -570,7 +570,7 @@ import { privateKeyToAccount } from "viem/accounts"
 
 import * as SP from "@filoz/synapse-core/sp"
 
-const synapse = Synapse.create({ account: privateKeyToAccount("0x...") })
+const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const client = synapse.client;
 const walletAddress = client.account.address;
 

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

@@ -165,7 +165,7 @@ Allowances are **cumulative** - you must add your new storage requirements to an
 // @lib: esnext,dom
 import { Synapse, TOKENS, TIME_CONSTANTS, calibration } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const pricePerMonth = null as unknown as bigint;
 const pricePerEpoch = null as unknown as bigint;
 // ---cut---
@@ -214,7 +214,7 @@ Check balances, calculate deposit amount, and execute the appropriate transactio
 // @lib: esnext,dom
 import { Synapse, TIME_CONSTANTS, calibration, TOKENS } from "@filoz/synapse-sdk";
 import { privateKeyToAccount } from 'viem/accounts'
-const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
+const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
 const totalCostNeeded = null as unknown as bigint;
 const rateAllowanceNeeded = null as unknown as bigint;
 const lockupAllowanceNeeded = null as unknown as bigint;