WarmStorageService

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:52

Constructors

Constructor

new WarmStorageService(options): WarmStorageService

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:63

Create a new WarmStorageService instance

Parameters

Parameter	Type	Description
options	{ client: Client<Transport, Chain, Account>; }	Options for the WarmStorageService
options.client	Client<Transport, Chain, Account>	Wallet client

Returns

WarmStorageService

A new WarmStorageService instance

Methods

addApprovedProvider()

addApprovedProvider(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:585

Add an approved provider by ID (owner only)

Parameters

Parameter	Type	Description
options	{ providerId: bigint; }	Options for the approved provider addition
options.providerId	bigint	Provider ID from registry

Returns

Promise<`0x${string}`>

Transaction response

---

calculateStorageCost()

calculateStorageCost(options): Promise<{ perDay: bigint; perEpoch: bigint; perMonth: bigint; withCDN: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; }>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:327

Calculate storage costs for a given size

Parameters

Parameter	Type	Description
options	{ sizeInBytes: bigint; }	Options for the storage cost
options.sizeInBytes	bigint	Size of data to store in bytes

Returns

Promise<{ perDay: bigint; perEpoch: bigint; perMonth: bigint; withCDN: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; }>

Cost estimates per epoch, day, and month

Remarks

CDN costs are usage-based (egress pricing), so withCDN field reflects base storage cost only

---

checkAllowanceForStorage()

checkAllowanceForStorage(options): Promise<{ costs: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; currentLockupAllowance: bigint; currentLockupUsed: bigint; currentRateAllowance: bigint; currentRateUsed: bigint; depositAmountNeeded: bigint; lockupAllowanceNeeded: bigint; message?: string; rateAllowanceNeeded: bigint; sufficient: boolean; }>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:368

Check if user has sufficient allowances for a storage operation and calculate costs

Parameters

Parameter	Type	Description
options	{ address?: `0x${string}`; lockupDays?: bigint; operator?: `0x${string}`; sizeInBytes: bigint; withCDN: boolean; }	Options for the allowance check
options.address?	`0x${string}`	Address of the account to check allowances for (optional, defaults to the client account address)
options.lockupDays?	bigint	Number of days for lockup period (defaults to 30)
options.operator?	`0x${string}`	Address of the operator to check allowances for (optional, defaults to the WarmStorage contract address)
options.sizeInBytes	bigint	Size of data to store
options.withCDN	boolean	Whether CDN is enabled

Returns

Promise<{ costs: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; currentLockupAllowance: bigint; currentLockupUsed: bigint; currentRateAllowance: bigint; currentRateUsed: bigint; depositAmountNeeded: bigint; lockupAllowanceNeeded: bigint; message?: string; rateAllowanceNeeded: bigint; sufficient: boolean; }>

Allowance requirement details and storage costs

---

getActivePieceCount()

getActivePieceCount(options): Promise<bigint>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:244

Get the count of active pieces in a dataset (excludes removed pieces)

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; }	Options for the data set
options.dataSetId	bigint	The PDPVerifier data set ID

Returns

Promise<bigint>

The number of active pieces

---

getApprovedProviderIds()

getApprovedProviderIds(): Promise<OutputType>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:611

Get list of approved provider IDs

Returns

Promise<OutputType>

Array of approved provider IDs

---

getClientDataSets()

getClientDataSets(options): Promise<OutputType>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:112

Get all data sets for a specific client

Parameters

Parameter	Type	Description
options	{ address: `0x${string}`; }	Options for the client data sets
options.address	`0x${string}`	The client address

Returns

Promise<OutputType>

Array of data set information getClientDataSets.OutputType

Throws

Errors getClientDataSets.ErrorType

---

getClientDataSetsWithDetails()

getClientDataSetsWithDetails(options): Promise<EnhancedDataSetInfo[]>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:124

Get all data sets for a client with enhanced details This includes live status and management information

Parameters

Parameter	Type	Description
options	{ address?: `0x${string}`; onlyManaged?: boolean; }	Options for the client data sets
options.address?	`0x${string}`	The client address
options.onlyManaged?	boolean	If true, only return data sets managed by this Warm Storage contract

Returns

Promise<EnhancedDataSetInfo[]>

Array of enhanced data set information EnhancedDataSetInfo

---

getDataSet()

getDataSet(options): Promise<OutputType>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:101

Get a single data set by ID

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; }	Options for the data set
options.dataSetId	bigint	The data set ID to retrieve

Returns

Promise<OutputType>

Data set information getDataSet.OutputType

Throws

Errors getDataSet.ErrorType

---

getDataSetMetadata()

getDataSetMetadata(options): Promise<MetadataObject>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:257

Get all metadata for a data set

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; }	Options for the data set
options.dataSetId	bigint	The data set ID

Returns

Promise<MetadataObject>

Object with metadata key-value pairs

---

getDataSetMetadataByKey()

getDataSetMetadataByKey(options): Promise<string | null>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:269

Get specific metadata key for a data set

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; key: string; }	Options for the data set
options.dataSetId	bigint	The data set ID
options.key	string	The metadata key to retrieve

Returns

Promise<string | null>

The metadata value if it exists, null otherwise

---

getOwner()

getOwner(): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:634

Get the contract owner address

Returns

Promise<`0x${string}`>

Owner address

---

getPDPConfig()

getPDPConfig(): Promise<{ challengesPerProof: bigint; challengeWindowSize: bigint; initChallengeWindowStart: bigint; maxProvingPeriod: bigint; }>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:657

Get the PDP config from the WarmStorage contract. Returns maxProvingPeriod, challengeWindowSize, challengesPerProof, initChallengeWindowStart

Returns

Promise<{ challengesPerProof: bigint; challengeWindowSize: bigint; initChallengeWindowStart: bigint; maxProvingPeriod: bigint; }>

---

getPieceMetadata()

getPieceMetadata(options): Promise<MetadataObject>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:287

Get all metadata for a piece in a data set

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; pieceId: bigint; }	Options for the piece
options.dataSetId	bigint	The data set ID
options.pieceId	bigint	The piece ID

Returns

Promise<MetadataObject>

Object with metadata key-value pairs

---

getPieceMetadataByKey()

getPieceMetadataByKey(options): Promise<string | null>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:300

Get specific metadata key for a piece in a data set

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; key: string; pieceId: bigint; }	Options for the piece
options.dataSetId	bigint	The data set ID
options.key	string	The metadata key to retrieve
options.pieceId	bigint	The piece ID

Returns

Promise<string | null>

The metadata value if it exists, null otherwise

---

getServicePrice()

getServicePrice(): Promise<OutputType>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:316

Get the current service price per TiB per month

Returns

Promise<OutputType>

Service price information for both CDN and non-CDN options

---

isOwner()

isOwner(options): Promise<boolean>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:648

Check if an address is the contract owner

Parameters

Parameter	Type	Description
options	{ address: `0x${string}`; }	Options for the owner check
options.address	`0x${string}`	Address to check

Returns

Promise<boolean>

Whether the address is the owner

---

isProviderIdApproved()

isProviderIdApproved(options): Promise<boolean>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:621

Check if a provider ID is approved

Parameters

Parameter	Type	Description
options	{ providerId: bigint; }	Options for the provider ID approval check
options.providerId	bigint	Provider ID to check

Returns

Promise<boolean>

Whether the provider is approved

---

prepareStorageUpload()

prepareStorageUpload(options): Promise<{ actions: object[]; allowanceCheck: { message?: string; sufficient: boolean; }; estimatedCost: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; }>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:480

Prepare for storage upload by checking balances and allowances

This method performs a comprehensive check of the prerequisites for storage upload, including verifying sufficient funds and service allowances. It returns a list of actions that need to be executed before the upload can proceed.

Parameters

Parameter	Type	Description
options	{ address?: `0x${string}`; dataSize: bigint; lockupDays?: bigint; operator?: `0x${string}`; withCDN?: boolean; }	Configuration options for the storage upload
options.address?	`0x${string}`	Address of the account to check allowances for (optional, defaults to the client account address)
options.dataSize	bigint	Size of data to store in bytes
options.lockupDays?	bigint	Number of days for lockup period (defaults to 30)
options.operator?	`0x${string}`	Address of the operator to check allowances for (optional, defaults to the WarmStorage contract address)
options.withCDN?	boolean	Whether to enable CDN for faster retrieval (optional, defaults to false)

Returns

Promise<{ actions: object[]; allowanceCheck: { message?: string; sufficient: boolean; }; estimatedCost: { perDay: bigint; perEpoch: bigint; perMonth: bigint; }; }>

Object containing:

• estimatedCost: Breakdown of storage costs (per epoch, day, and month)
• allowanceCheck: Status of service allowances with optional message
• actions: Array of required actions (deposit, approveService) that need to be executed

Example

const prep = await warmStorageService.prepareStorageUpload(
  { dataSize: SIZE_CONSTANTS.GiB, withCDN: true, address: '0x...' },
)

if (prep.actions.length > 0) {
  for (const action of prep.actions) {
    console.log(`Executing: ${action.description}`)
    await action.execute()
  }
}

---

removeApprovedProvider()

removeApprovedProvider(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:595

Remove an approved provider by ID (owner only)

Parameters

Parameter	Type	Description
options	{ providerId: bigint; }	Options for the approved provider removal
options.providerId	bigint	Provider ID from registry

Returns

Promise<`0x${string}`>

Transaction response

---

terminateDataSet()

terminateDataSet(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:573

Terminate a data set with given ID

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; }	Options for the data set termination
options.dataSetId	bigint	ID of the data set to terminate

Returns

Promise<`0x${string}`>

Transaction receipt

---

topUpCDNPaymentRails()

topUpCDNPaymentRails(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:691

Increments the fixed locked-up amounts for CDN payment rails.

This method tops up the prepaid balance for CDN services by adding to the existing lockup amounts. Both CDN and cache miss rails can be incremented independently.

Parameters

Parameter	Type	Description
options	{ cacheMissAmountToAdd: bigint; cdnAmountToAdd: bigint; dataSetId: bigint; }	Options for the top up CDN payment rails
options.cacheMissAmountToAdd	bigint	Amount to add to the cache miss rail lockup
options.cdnAmountToAdd	bigint	Amount to add to the CDN rail lockup
options.dataSetId	bigint	The ID of the data set

Returns

Promise<`0x${string}`>

Transaction response Hash

---

validateDataSet()

validateDataSet(options): Promise<void>

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:207

Validate that a dataset is live and managed by this WarmStorage contract

Performs validation checks in parallel:

• Dataset exists and is live
• Dataset is managed by this WarmStorage contract

Parameters

Parameter	Type	Description
options	{ dataSetId: bigint; }	Options for the data set
options.dataSetId	bigint	The PDPVerifier data set ID

Returns

Promise<void>

Throws

if dataset is not valid for operations

---

create()

static create(options): WarmStorageService

Defined in: packages/synapse-sdk/src/warm-storage/service.ts:77

Create a new WarmStorageService with pre-configured client

Parameters

Parameter	Type	Description
options	{ account: Account; chain?: Chain; transport?: Transport; }	Options for the WarmStorageService
options.account	Account	Viem account (required)
options.chain?	Chain	Filecoin chain (optional, defaults to DEFAULT_CHAIN)
options.transport?	Transport	Viem transport (optional, defaults to http())

Returns

WarmStorageService

A new WarmStorageService instance