docs: developer guides for Synapse SDK by nijoe1 · Pull Request #404 · FilOzone/synapse-sdk

nijoe1 · 2025-11-05T14:02:49Z

Overview

Implements comprehensive developer guides for Synapse SDK covering basic and advanced storage and payment operations. This PR builds upon previously refined documentation sections (introduction, getting-started, and core concepts) and includes overall documentation infrastructure improvements.

📖 Live Preview: https://synapse-sdk-docs.netlify.app/

Related Issues

Closes Docs: Developer/Synapse-sdk #346 (Developer/Synapse-sdk guides) ✅
Builds upon Docs: Introduction #322 (Introduction)
Builds upon Docs: Getting started #323 (Getting Started)
Builds upon Docs: concepts section #345 (Core Concepts)
Part of Filecoin Onchain Cloud docs #321 (Filecoin Onchain Cloud docs)

Main Scope: Developer Guides

📝 Overview: Developer documentation structure and navigation
🚀 Quick Start: Getting started with Synapse SDK
💳 Payment Operations: Basic and advanced payment workflows
💾 Storage Operations: Basic and advanced storage management
📊 Monitoring: Tracking and observing SDK operations

Key Feature: TypeScript Twoslash Integration

✨ Extensive TS Twoslash usage across all code blocks
🛡️ Type-safe examples: Validates all Synapse SDK imports and usage at build time
🚫 Prevents deployment with invalid/outdated code examples
✅ Ensures accuracy: All code examples are valid and up-to-date

Additional Improvements

🔗 Link Validation: Fixed broken links across all documentation
🧭 Navigation: Improved sidebar structure and navigation flow
🔖 Slugs: Optimized URL slugs for better accessibility

rvagg · 2025-11-05T21:40:27Z

There's been a bit of disagreement about this but I'd personally prefer "Data Set" as two words, data-set, dataSet, DataSet and Data Set in prose, rather than Dataset etc. I've tried to align code to this form, although we're talking about adding a filecoin-pin dataset alias for filecoin-pin data-set to satisfy those who object to having to type the extra character.

rvagg · 2025-11-05T21:55:28Z

In "The Cost Model" - we don't touch on the 30 day lockup; there's a lot of coverage of lockups in the Filecoin Pay section, but specifically for storage, with FWSS, we should be clear that FWSS doesn't have a variable lockup, all you need to know is that you're always pre-paying 30 days for an active service. Then when you dip below 30 days in your balance you're essentially heading for default and the SP is going to treat you as delinquent and will schedule removal of your data. I suspect that using more simplified ways of talking about lockup without having to cover all of the complexities of lockup makes some of the problems go away.

Also in the costing, we should be clear that "per month" means "per 30 days", not calendar month like a traditional storage service. A point Hugo was making yesterday that I think is worth being crystal clear about - we say "per month" for simplicity but you have to read that as "per 30 days" if you're doing any nontrivial calculation with it.

The code in that cost model shows how broken our current API for pricing is .. we really need to get that fixed.

In "Creating a Storage Context" we have "Slower (2-5 minutes)", I would think it's closer to "1-3 minutes" but maybe this is based on your experience? But aside from that I think this whole section needs a revisit now with the create+add flow, there isn't a "slower" path now since it's built in to the add pieces operation, so all createContext is roughly the same - we either find one for you to use, or queue up a create when you add your first piece. You could mention that, it's internal complexity, but they might care that their first createContext doesn't actually land anything on chain until they've added data.

There's a "Metadata Matching for Cost Efficiency" - you should change the wording here I think to talk about floor pricing, "unnecessary dataset creation costs" -- it's really about "avoiding the minimum data set storage fee of 6¢/month.

Last though: I don't know if it's there but a link to Filecoin Pin would be great -- when people want a concept of "files and directories" then Filecoin Pin is the answer to that, a layer on top that brings IPFS's filesystem structure to FOC.

That's all for a quick skim for now. Good work so far. Sorry that we have more breakage to come that will change some of this.

timfong888

Prerequisites must appear before first code example (getting-started)
Quick start needs complete runnable example in <5 min (getting-started)
Replace placeholder null as unknown as bigint with actual API call (payments/index.mdx line 118-139)
- Add real-world cost examples:

timfong888 · 2025-11-06T00:05:35Z

+import { Synapse } from "@filoz/synapse-sdk";
+// @ts-ignore
+const synapse = await Synapse.create();
+const monthlyPricePerTiB = null as unknown as bigint;


What does this mean? Can we make as a thing before code is offered for review it works; this seems odd to me.

Fixed! There is only one place now that uses @ts-ignore and that's because /pieces is not exported in the sdk @rvagg can you export all the pieces utils in the main package without having to import from synapse-sdk/pieces ?

I'm still a little bit unclear as to keeping const monthlyPricePerTiB = null as unknown as bigint; in the code sample?

longfeiWan9 · 2025-11-06T06:33:56Z

Thanks, @rvagg, for reviewing it and providing your comments. I have addressed most of your comments but one.

@nijoe1 can you revisit the "Creating a Storage Context" section? Since Rod mentioned that after implementing create+add flow to the add pieces operation, there isn't a "slower" path. If you can verify that, maybe we should remove the slow and fast option.

longfeiWan9 · 2025-11-06T08:03:19Z

Prerequisites must appear before first code example (getting-started)

Fixed

Quick start needs complete runnable example in <5 min (getting-started)

Fixed

Replace placeholder null as unknown as bigint with actual API call (payments/index.mdx line 118-139)

Add real-world cost examples:

Sorry I do not really understand this. Maybe you can directly add a comment in payments/index.mdx so Nick can fix that. @timfong888

nijoe1 · 2025-11-06T17:39:17Z

In "The Cost Model" - we don't touch on the 30 day lockup; there's a lot of coverage of lockups in the Filecoin Pay section, but specifically for storage, with FWSS, we should be clear that FWSS doesn't have a variable lockup, all you need to know is that you're always pre-paying 30 days for an active service. Then when you dip below 30 days in your balance you're essentially heading for default and the SP is going to treat you as delinquent and will schedule removal of your data. I suspect that using more simplified ways of talking about lockup without having to cover all of the complexities of lockup makes some of the problems go away.

I made major changes in the storage-costs page that I think that they address @rvagg & @timfong888 comments

Check it out and let me know for further feedback

https://synapse-sdk-docs.netlify.app/developer-guides/storage/storage-costs/

nijoe1 · 2025-11-06T17:42:33Z

In "Creating a Storage Context" we have "Slower (2-5 minutes)", I would think it's closer to "1-3 minutes" but maybe this is based on your experience? But aside from that I think this whole section needs a revisit now with the create+add flow, there isn't a "slower" path now since it's built in to the add pieces operation, so all createContext is roughly the same - we either find one for you to use, or queue up a create when you add your first piece. You could mention that, it's internal complexity, but they might care that their first createContext doesn't actually land anything on chain until they've added data.

I've made updates to the storage-context section. I agree this was outdated and taken from the old docs. I removed it due to the createAndAdd feature. Check the updates here and let me know if it reads better now!

https://synapse-sdk-docs.netlify.app/developer-guides/storage/storage-context/

cc: @rvagg

longfeiWan9 · 2025-11-10T07:49:53Z

Lets include pricing somewhere, maybe https://synapse-sdk-docs.netlify.app/introduction/about/.

Fixed.

longfeiWan9 · 2025-11-10T07:50:36Z

Please replace FilecoinPay with Filecoin Pay

Fixed

longfeiWan9 · 2025-11-10T08:18:22Z

could you please cherry pick this commit in as well fd90d93

Done

longfeiWan9 · 2025-11-10T08:55:02Z

For quick start

should have a mainnet path as well (cant find anywhere in the doc atm

should have prerequisites, i.e: filecoinwallet, rpc nodes?

it is unclear if deposit amount has to be 5 USDFC or not, and what does 5USDFC mean/get me

in the quick advanced example, maybe show an example with filbeam add on

It is not necessary to have a mainnet path in the quick start for builders. Let's keep it simple to educate builders in a quicker way to learn how to build with Synpase.
Other 3 points are addressed. Actually withCND is already there, I just add a bit explaination to make it clearly link to Filecoin beam.

Done

longfeiWan9 · 2025-11-10T08:57:12Z

@jennijuju @timfong888 @Kubuxu Thank you for reviewing. All comments are addressed.

@timfong888 , can you double-check if those changes are good for your Changes Requested? Thank you.

- Resolved conflict by removing old gettingStarted/getting-started.mdx - Kept the newer getting-started/index.mdx with comprehensive documentation - Merged updates to storage.mdx, why.mdx, manager.ts, and synapse.test.ts

Completes the comprehensive Filecoin Onchain Cloud documentation, building upon previously refined sections with developer guides and infrastructure improvements. **Related Issues:** - Builds upon #322 (Introduction) - Builds upon #323 (Getting Started) - Builds upon #345 (Core Concepts) - Builds upon #404 (Developer Guides) - Part of #321 (Filecoin Onchain Cloud docs) **Documentation:** - Add comprehensive introduction section and developer guides - Update quickstart guide with improved examples - Add pricing and storage costs documentation - Fix broken links and improve navigation **Other:** - Add mainnet contract addresses - Documentation of synapse-version@0.35.3 - Bug fixes for types and error handling --------- Co-authored-by: longfeiW <longfeiwang.88@gmail.com> Co-authored-by: Rod Vagg <rod@vagg.org> Co-authored-by: Jennifer Wang <jiayingw703@gmail.com> Co-authored-by: Jakub Sztandera <oss@kubuxu.com>

timfong888 · 2025-11-12T10:16:59Z

For quick start

should have a mainnet path as well (cant find anywhere in the doc atm

should have prerequisites, i.e: filecoinwallet, rpc nodes?

it is unclear if deposit amount has to be 5 USDFC or not, and what does 5USDFC mean/get me

in the quick advanced example, maybe show an example with filbeam add on

I had the same comments as well in my original re: prequisits, does this mean this is still opened or it is addressed since it is closed?

timfong888 · 2025-11-12T10:20:42Z

+- Supports both streaming and one-time payments
+- Supports native token streaming
+
+The real innovation isn't just streaming payments - it's enabling **trustless business relationships** where math and code enforce agreements, eliminating the need for intermediaries and manual oversight.


Can we remove this paragraph or make it a little less exuberant?

timfong888 · 2025-11-12T10:22:38Z

+- Cryptographic guarantees and verifiable delivery
+- Programmable quality checks with instant consequences
+- Supports both streaming and one-time payments
+- Supports native token streaming


What does this really mean ? aren't we doing auto-lockups on an epoch basis? And "native token" sounds like, especially since we are working with chains, they can pay in their native token. Can you confirm we do this? My understanding is we didn.t

timfong888 · 2025-11-12T10:23:56Z

+You manually send $100 to a friend once.
+
+**Filecoin Pay payment rail:**
+You set up an automatic stream of $100/month for 3 months. Payments flow continuously without any manual intervention, with built-in guarantees that protect both parties.


Similar here: I think we need to be precise about the word "continuosly"

timfong888 · 2025-11-12T10:48:16Z

+By the end of this guide, you'll understand how to:
+
+- Install and configure the Synapse SDK
+- Connect to Filecoin networks (mainnet and calibration)


I don't see mainnet instructions....

timfong888 · 2025-11-12T10:49:34Z

+    const formattedBalance = ethers.formatUnits(walletBalance, 18);
+    console.log(`Wallet USDFC balance: ${formattedBalance} USDFC\n`);
+
+    // Validate sufficient balance before proceeding


How do we define "sufficient balance" -- should be both inline and maybe guidance above as a recommended start for clarity.

maybe it's resolved if we just say up front $5 is for purposes of getting started.

timfong888 · 2025-11-13T20:55:12Z

+
+As the economic core of the Filecoin Onchain Cloud (FOC), **Filecoin Pay** embeds **financial logic directly into on-chain contracts**, ensuring that providers receive funds only when they deliver verifiable service, and clients pay only when conditions are met.
+
+With Filecoin Pay, service economics become as **transparent and composable** as the data services they underpin, enabling the Filecoin network to operate not just as a storage market but as a fully programmable cloud economy.


I don't actually know what this means. It feels wordy. What does the developer do?

timfong888 · 2025-11-13T20:55:43Z

+
+In the Filecoin Onchain Cloud architecture, services (storage, retrieval) must be paired with economic incentives. Without a robust, verifiable settlement layer, the system risks:
+
+- Providers performing work without guaranteed payment.


We shouldn't be talking about problems with our system. Just what they can get and use.

timfong888 · 2025-11-13T20:55:58Z

+
+Filecoin Pay addresses these risks by tying **service delivery** (e.g., proofs of data possession, retrieval success) to **on-chain payment flows** that lets services run automated, controllable payment “rails” between a payer and a payee. It supports:
+
+- **Token-agnostic billing**: support for FIL, stablecoins, ERC-20 tokens.


is this true?

timfong888

I have a number of clarification language, some of it seems too wordy or imprecise, and I called out several examples, but I think this should be reviewed throughout using those as examples.

hugomrdias · 2025-11-13T21:00:27Z

@nijoe1 @timfong888 this is closed but not merged! whats are we doing here ?

theres yet another pr opened updating docs #265

nijoe1 · 2025-11-13T21:03:49Z

Because we were blocked on merging from Tim's staled review request while he was traveling. I opened a fresh pr and merged it.

timfong888

File: docs/src/content/docs/developer-guides/components.mdx
Lines: ~1478-1481 (in diff)

Placeholder pattern needs explanation.

The pattern const provider = null as unknown as ethers.Provider appears throughout examples without explanation.
What happens if this is run?

Completes the comprehensive Filecoin Onchain Cloud documentation, building upon previously refined sections with developer guides and infrastructure improvements. **Related Issues:** - Builds upon FilOzone#322 (Introduction) - Builds upon FilOzone#323 (Getting Started) - Builds upon FilOzone#345 (Core Concepts) - Builds upon FilOzone#404 (Developer Guides) - Part of FilOzone#321 (Filecoin Onchain Cloud docs) **Documentation:** - Add comprehensive introduction section and developer guides - Update quickstart guide with improved examples - Add pricing and storage costs documentation - Fix broken links and improve navigation **Other:** - Add mainnet contract addresses - Documentation of synapse-version@0.35.3 - Bug fixes for types and error handling --------- Co-authored-by: longfeiW <longfeiwang.88@gmail.com> Co-authored-by: Rod Vagg <rod@vagg.org> Co-authored-by: Jennifer Wang <jiayingw703@gmail.com> Co-authored-by: Jakub Sztandera <oss@kubuxu.com>

nijoe1 and others added 7 commits November 5, 2025 02:51

feat(docs): dev guides

dc20c25

updates intro & core-concepts

f8a4d99

formating

60d5582

chore: fix sidebar

a6f41aa

chore: replace deprecated method

8be248f

chore: small improv

06b5e12

chore: refactor introduction slugs

00af154

github-project-automation Bot added this to FOC Nov 5, 2025

github-project-automation Bot moved this to 📌 Triage in FOC Nov 5, 2025

timfong888 reviewed Nov 5, 2025

View reviewed changes

Comment thread docs/src/content/docs/getting-started/index.mdx

timfong888 suggested changes Nov 6, 2025

View reviewed changes

github-project-automation Bot moved this from 📌 Triage to ⌨️ In Progress in FOC Nov 6, 2025

longfeiWan9 requested a review from Kubuxu November 6, 2025 03:58

longfeiWan9 added 2 commits November 6, 2025 12:08

merge master

c85f657

address comments from PR-333

d3797bd

longfeiWan9 mentioned this pull request Nov 6, 2025

Docs: quick start for synapse SDK #333

Closed

use data set as two words in docs

380e331

update quick start

704105c

nijoe1 added 2 commits November 6, 2025 15:35

chore(docs): remove ts-ignore where possible

d4cfce7

fix(docs): improve storage context page

aad6048

Kubuxu reviewed Nov 6, 2025

View reviewed changes

Comment thread docs/src/content/docs/cookbooks/filecoin-pay.mdx

nijoe1 added 2 commits November 6, 2025 18:36

fix(docs): address storage costs comments

31a7e17

fix(docs): address tim comment on advanced components usage

0aac66d

nijoe1 requested a review from timfong888 November 6, 2025 19:11

fix about

b5ef29b

update quickStart for Jennis comments

843dbac

nijoe1 added 2 commits November 10, 2025 11:16

chore: use synapse 0.35.3

50256c4

chore: add mainnet contract addresses

8fd71fa

nijoe1 requested a review from timfong888 November 11, 2025 16:46

nijoe1 added 3 commits November 11, 2025 18:50

Merge upstream/master into docs/dev_guides

7d33b4f

- Resolved conflict by removing old gettingStarted/getting-started.mdx - Kept the newer getting-started/index.mdx with comprehensive documentation - Merged updates to storage.mdx, why.mdx, manager.ts, and synapse.test.ts

fix: broken link

97930f6

fix: filecoin-pin link

c3d7913

nijoe1 closed this Nov 12, 2025

github-project-automation Bot moved this from ⌨️ In Progress to 🎉 Done in FOC Nov 12, 2025

timfong888 reviewed Nov 12, 2025

View reviewed changes

timfong888 reviewed Nov 13, 2025

View reviewed changes

timfong888 reviewed Nov 14, 2025

View reviewed changes


		As the economic core of the Filecoin Onchain Cloud (FOC), Filecoin Pay embeds financial logic directly into on-chain contracts, ensuring that providers receive funds only when they deliver verifiable service, and clients pay only when conditions are met.

		With Filecoin Pay, service economics become as transparent and composable as the data services they underpin, enabling the Filecoin network to operate not just as a storage market but as a fully programmable cloud economy.


		In the Filecoin Onchain Cloud architecture, services (storage, retrieval) must be paired with economic incentives. Without a robust, verifiable settlement layer, the system risks:

		- Providers performing work without guaranteed payment.


		Filecoin Pay addresses these risks by tying service delivery (e.g., proofs of data possession, retrieval success) to on-chain payment flows that lets services run automated, controllable payment “rails” between a payer and a payee. It supports:

		- Token-agnostic billing: support for FIL, stablecoins, ERC-20 tokens.

Conversation

nijoe1 commented Nov 5, 2025

Overview

Related Issues

Main Scope: Developer Guides

Key Feature: TypeScript Twoslash Integration

Additional Improvements

Uh oh!

rvagg commented Nov 5, 2025

Uh oh!

rvagg commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

timfong888 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

longfeiWan9 commented Nov 6, 2025

Uh oh!

longfeiWan9 commented Nov 6, 2025

Uh oh!

Uh oh!

nijoe1 commented Nov 6, 2025

Uh oh!

nijoe1 commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

longfeiWan9 commented Nov 10, 2025

Uh oh!

longfeiWan9 commented Nov 10, 2025

Uh oh!

longfeiWan9 commented Nov 10, 2025

Uh oh!

longfeiWan9 commented Nov 10, 2025

Uh oh!

longfeiWan9 commented Nov 10, 2025

Uh oh!

timfong888 commented Nov 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timfong888 left a comment

Choose a reason for hiding this comment

Uh oh!

hugomrdias commented Nov 13, 2025

Uh oh!

nijoe1 commented Nov 13, 2025

Uh oh!

timfong888 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

rvagg commented Nov 5, 2025 •

edited

Loading

nijoe1 commented Nov 6, 2025 •

edited

Loading

timfong888 left a comment •

edited

Loading