feat: New synapse costs API and improvs by lordshashank · Pull Request #632 · FilOzone/synapse-sdk

lordshashank · 2026-02-25T12:20:00Z

Resolves #360 , #437

Complete architecture and thought process: https://hackmd.io/@lordforever/SJ6Lwv2dWx (plz read to understand better and add comments)

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

juliangruber · 2026-02-27T10:46:34Z

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

+- **Needs deposit + approval**: calls `depositWithPermitAndApproveOperator`
+- **Needs approval only**: calls `approveService`
+- **Needs deposit only**: calls `depositWithPermit`
+- **Already ready**: returns `transaction: null`


Should exact API specs live outside of developer guides?

juliangruber · 2026-02-27T10:51:11Z

packages/synapse-core/src/pay/get-account-info-if-settled.ts

+ * @param params - Raw account fields + current epoch
+ * @returns Settled account info including fundedUntilEpoch
+ */
+export function getAccountInfoIfSettled(


I would expect this method to return the account info if settled. There is no condition here, it always returns account info. What does "if settled" mean here?

I mapped the exact onchain function https://github.com/FilOzone/filecoin-pay/blob/7bc77d86f94ef646721919426038a66290b862aa/src/FilecoinPayV1.sol#L1747

juliangruber · 2026-02-27T10:54:33Z

packages/synapse-core/src/pay/account-debt.ts

+    /** max(0, funds - totalOwed) */
+    availableFunds: bigint
+    /** Epoch when account runs out (maxUint256 if lockupRate == 0) */
+    fundedUntilEpoch: bigint


these two are out of scope for the function. The consumer can simply do this themselves:

const [debt, info] = await Promise.all([ calculateAccountDebt(), getAccountInfoIfSettled() ])

I would suggest to only return the debt from this function and not return other possibly useful but already easy to get information.

I did that as we needed fundedUntilEpoch in for buffer calcn, etc so made it more informative, can change to different functions if everyone wants to.

packages/synapse-core/src/pay/deposit-with-permit.ts

juliangruber · 2026-02-27T11:05:27Z

packages/synapse-core/src/pay/deposit-with-permit.ts

+
+export namespace depositWithPermitSync {
+  export type OptionsType = Simplify<depositWithPermit.OptionsType & ActionSyncCallback>
+  export type OutputType = ActionSyncOutput<typeof extractDepositWithPermitEvent>


I don't think <typeof extractDepositWithPermitEvent> can be inferred

extractDepositWithPermitEvent is defined below in the same file and the typeof is needed because this is a type declaration, not a value expression. wdym here?

packages/synapse-core/src/pay/fund.ts

juliangruber · 2026-02-27T11:39:47Z

packages/synapse-core/src/pay/fund.ts

+  }
+
+  if (needsApproval && options.amount === 0n) {
+    return setOperatorApproval(client, {


this code path is surprising: I would not expect a fund() method to not actually fund and only approve.

yeah, handling the edge cases

packages/synapse-core/src/pay/total-account-lockup.ts

juliangruber · 2026-02-27T11:58:57Z

packages/synapse-core/src/pay/total-account-rate.ts

+
+  return {
+    ratePerEpoch,
+    ratePerMonth: ratePerEpoch * TIME_CONSTANTS.EPOCHS_PER_MONTH,


this is a convenience field and always wrong, wdyt about never returning per-month data, always only the correct per-epoch data, and exposing an extra method for converting per-epoch to per-month? This way the developer has to opt in to the conversion.

This way, there's higher confidence in the return values of core methods, and it's more clear that the per-month value is rather for display or human readability.

#375 (comment),

Actually on chain is per month so convenience field is per epoch one, kept it to let user calculate anuthing and is more generic

juliangruber · 2026-02-27T12:04:51Z

packages/synapse-core/src/pdp-verifier/get-dataset-size.ts

+ * @returns Array of data set sizes in bytes {@link getMultiDatasetSize.OutputType}
+ * @throws Errors {@link getMultiDatasetSize.ErrorType}
+ */
+export async function getMultiDatasetSize(


is this method actually adventageous over calling getDataSetSize multiple times in parallel? If the benefit is not obvious already, I would suggest to remove this utility method, to reduce the maintenance cost

Yeah, it reduces rpc calls for multi context cases in prepare through multicall, probably we can just keep this and remove single one and rename this to getDatasetsSize but I am ok with two functions as well let me know if this feels critical

juliangruber · 2026-02-27T12:05:26Z

packages/synapse-core/src/utils/constants.ts

+ * Default extra runway in epochs beyond the required lockup.
+ * 0n means no additional runway beyond the lockup period.
+ */
+export const DEFAULT_RUNWAY_EPOCHS = 0n


Is the decision to go with 0 documented somewhere?

packages/synapse-core/src/warm-storage/calculate-additional-lockup-required.ts

juliangruber · 2026-02-27T12:12:04Z

packages/synapse-core/src/warm-storage/calculate-additional-lockup-required.ts

+  if (currentDataSetSize > 0n && !isNewDataset) {
+    // Existing dataset: compute delta between new and current rates
+    const newRate = calculateEffectiveRate({
+      ...rateParams,
+      sizeInBytes: currentDataSetSize + dataSize,
+    })
+    const currentRate = calculateEffectiveRate({
+      ...rateParams,
+      sizeInBytes: currentDataSetSize,
+    })
+    rateDeltaPerEpoch = newRate.ratePerEpoch - currentRate.ratePerEpoch
+    // Floor-to-floor: if both sizes are below floor, delta is 0
+    if (rateDeltaPerEpoch < 0n) rateDeltaPerEpoch = 0n
+  } else {
+    // New dataset or unknown current size: full rate for new data
+    const newRate = calculateEffectiveRate({
+      ...rateParams,
+      sizeInBytes: dataSize,
+    })
+    rateDeltaPerEpoch = newRate.ratePerEpoch
+  }


refactor: less branches

Suggested change

if (currentDataSetSize > 0n && !isNewDataset) {

// Existing dataset: compute delta between new and current rates

const newRate = calculateEffectiveRate({

...rateParams,

sizeInBytes: currentDataSetSize + dataSize,

})

const currentRate = calculateEffectiveRate({

...rateParams,

sizeInBytes: currentDataSetSize,

})

rateDeltaPerEpoch = newRate.ratePerEpoch - currentRate.ratePerEpoch

// Floor-to-floor: if both sizes are below floor, delta is 0

if (rateDeltaPerEpoch < 0n) rateDeltaPerEpoch = 0n

} else {

// New dataset or unknown current size: full rate for new data

const newRate = calculateEffectiveRate({

...rateParams,

sizeInBytes: dataSize,

})

rateDeltaPerEpoch = newRate.ratePerEpoch

}

const newRate = calculateEffectiveRate({

...rateParams,

sizeInBytes: currentDataSetSize + dataSize,

})

const currentRate = calculateEffectiveRate({

...rateParams,

sizeInBytes: currentDataSetSize,

})

rateDeltaPerEpoch = newRate.ratePerEpoch - currentRate.ratePerEpoch

this is wrong as for the case of new dataset it would return zero as calculateEffectiveRate would return base price for both

packages/synapse-core/src/warm-storage/calculate-deposit-needed.ts

lordshashank requested review from hugomrdias and rvagg as code owners February 25, 2026 12:20

github-project-automation bot added this to FOC Feb 25, 2026

github-project-automation bot moved this to 📌 Triage in FOC Feb 25, 2026

rjan90 assigned lordshashank Feb 25, 2026

rjan90 moved this from 📌 Triage to 🔎 Awaiting review in FOC Feb 25, 2026

rjan90 added this to the M4.1: mainnet ready milestone Feb 25, 2026

rjan90 linked an issue Feb 25, 2026 that may be closed by this pull request

Add intelligent synapse.payments.fund(amount) (improve golden path) #437

Open

lordshashank force-pushed the feat/costs-api branch 2 times, most recently from bdd0623 to e269ba9 Compare February 26, 2026 08:18

juliangruber self-requested a review February 26, 2026 10:18

feat: New synapse costs API and improvs

4883c02

lordshashank force-pushed the feat/costs-api branch from e269ba9 to 4883c02 Compare February 27, 2026 05:50

juliangruber requested changes Feb 27, 2026

View reviewed changes

github-project-automation bot moved this from 🔎 Awaiting review to ⌨️ In Progress in FOC Feb 27, 2026

juliangruber requested changes Feb 27, 2026

View reviewed changes

packages/synapse-core/src/warm-storage/calculate-deposit-needed.ts Outdated Show resolved Hide resolved

refactor: Update storage cost calculations and improve deposit logic

67d9b07

Conversation

lordshashank commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lordshashank commented Feb 25, 2026 •

edited

Loading