Index
Synapse SDK - Main entry point
Example
Section titled “Example”import { Synapse } from '@filoz/synapse-sdk'Modules
Section titled “Modules”| Module | Description |
|---|---|
| <internal> | - |
Classes
Section titled “Classes”| Class | Description |
|---|---|
| PaymentsService | - |
| PDPAuthHelper | Helper class for creating EIP-712 typed signatures for PDP operations |
| PDPServer | - |
| PDPVerifier | - |
| StorageContext | - |
| StorageManager | - |
| SubgraphService | Defines the contract for a service that can retrieve provider information from a data source, typically a Synapse-compatible subgraph. |
| Synapse | - |
| WarmStorageService | - |
Interfaces
Section titled “Interfaces”| Interface | Description |
|---|---|
| AddPiecesInfo | Helper information for adding pieces to a data set |
| AddPiecesResponse | Response from adding pieces to a data set |
| AuthSignature | Signature data for authenticated operations |
| ComprehensiveDataSetStatus | Combined status information from both PDP server and chain |
| CreateDataSetResponse | Response from creating a data set |
| DataSetCreationStatusResponse | Response from checking data set creation status |
| DataSetCreationVerification | Result of verifying data set creation on-chain |
| DataSetData | Data set data returned from the API |
| DataSetInfo | Data set information returned from Warm Storage contract |
| DataSetPieceData | Individual data set piece data from API |
| DepositCallbacks | Callbacks for deposit operation visibility |
| DetailedSubgraphDataSetInfo | Detailed data set information from subgraph with additional metadata |
| EnhancedDataSetInfo | Enhanced data set information with chain details and clear ID separation |
| FaultRecord | Fault record information |
| FindPieceResponse | Response from finding a piece |
| NestedQueryOptions | Options for nested entity queries in subgraphs |
| PaginationOptions | Options for pagination in subgraph queries |
| PieceAdditionStatusResponse | Response from checking piece addition status |
| PieceInfo | Piece information with data set context |
| PieceRetriever | PieceRetriever interface for fetching pieces from various sources Returns standard Web API Response objects for flexibility |
| PieceStatus | Status information for a piece stored on a provider Note: Proofs are submitted for entire data sets, not individual pieces. The timing information reflects the data set’s status. |
| PreflightInfo | Preflight information for storage uploads |
| ProviderInfo | Decoded provider info for SDK use |
| ProviderSelectionResult | Result of provider selection and data set resolution |
| ProviderStats | Extended provider statistics including fault information |
| QueryOptions | Options for flexible subgraph queries with custom where clauses |
| RailInfo | Information about a payment rail |
| SettlementResult | Settlement result from settling a payment rail |
| StorageCreationCallbacks | Callbacks for storage service creation process |
| StorageInfo | Comprehensive storage service information |
| StorageOptions | Storage service options |
| StorageServiceOptions | Options for creating or selecting a storage context |
| SubgraphConfig | Configuration for the SubgraphService, determining how to connect to a Synapse-compatible subgraph for provider discovery. |
| SubgraphDataSetInfo | Basic data set information from subgraph |
| SubgraphRetrievalService | Defines the contract for a service that can retrieve provider information from a data source, typically a Synapse-compatible subgraph. |
| SynapseOptions | Options for initializing the Synapse instance Must provide one of: 1. privateKey + rpcURL (for server environments) 2. provider (for browser environments - user handles MetaMask coupling) 3. signer (for direct ethers.js integration) |
| UploadCallbacks | Callbacks for tracking upload progress |
| UploadOptions | Options for uploading individual pieces to an existing storage context |
| UploadResponse | Upload response containing piece information |
| UploadResult | Upload result information |
| UploadTask | Upload task tracking |
Type Aliases
Section titled “Type Aliases”| Type Alias | Description |
|---|---|
| Address | - |
| DataSetId | - |
| DownloadOptions | Download options Currently empty, reserved for future options |
| FilecoinNetworkType | Supported Filecoin network types |
| MetadataEntry | - |
| PieceCID | PieceCID - A constrained CID type for Piece Commitments. This is implemented as a Link type which is made concrete by a CID. A PieceCID uses the raw codec (0x55) and the fr32-sha256-trunc254-padbintree multihash function (0x1011) which encodes the base content length (as padding) of the original piece, and the height of the merkle tree used to hash it. |
| PrivateKey | - |
| ServiceProvider | - |
| TokenAmount | - |
| TokenIdentifier | Token identifier for balance queries |
Variables
Section titled “Variables”| Variable | Description |
|---|---|
| CHAIN_IDS | Network chain IDs |
| CONTRACT_ABIS | Contract ABIs |
| CONTRACT_ADDRESSES | Contract addresses |
| EIP2612_PERMIT_TYPES | EIP-2612 typed data schema (Permit) |
| GENESIS_TIMESTAMPS | Genesis timestamps for Filecoin networks (Unix timestamp in seconds) |
| METADATA_KEYS | Common metadata keys |
| RPC_URLS | Recommended RPC endpoints for Filecoin networks |
| SETTLEMENT_FEE | Settlement fee required for rail settlement operations This is the NETWORK_FEE constant in the Payments contract that gets burned to the Filecoin network Value: 0.0013 FIL (1300000000000000 attoFIL) |
| SIZE_CONSTANTS | Data size constants |
| TIME_CONSTANTS | Time and size constants |
| TIMING_CONSTANTS | Timing constants for blockchain operations |
| TOKENS | Token identifiers |
Functions
Section titled “Functions”| Function | Description |
|---|---|
| asDataSetData | Converts and validates data set data Returns null if validation fails |
| asDataSetPieceData | Converts and validates individual data set piece data Returns null if validation fails |
| calculateLastProofDate | Calculate when the last proof should have been submitted based on current time |
| combineMetadata | Combines metadata object with withCDN flag, ensuring consistent behavior. If withCDN is true, adds the withCDN key only if not already present. If withCDN is false or undefined, returns metadata unchanged. |
| constructFindPieceUrl | Construct a piece discovery (findPiece) URL |
| constructPieceUrl | Construct a piece retrieval URL |
| createError | Utility function to create descriptive errors with context |
| dateToEpoch | Convert a JavaScript Date to a Filecoin epoch |
| epochToDate | Convert a Filecoin epoch to a JavaScript Date |
| getCurrentEpoch | Get the current epoch from the blockchain This is an internal utility, not part of the public API |
| getFilecoinNetworkType | Extract and validate FilecoinNetworkType from an ethers Provider |
| getGenesisTimestamp | Get the genesis timestamp for a network |
| isDataSetCreationStatusResponse | Type guard for DataSetCreationStatusResponse Validates the response from checking data set creation status |
| isFindPieceResponse | Type guard for FindPieceResponse Validates the response from finding a piece Supports both pieceCid (new) and piece_cid (legacy) field names for backward compatibility |
| isPieceAdditionStatusResponse | Type guard for PieceAdditionStatusResponse Validates the response from checking piece addition status |
| metadataMatches | Checks if a data set’s metadata exactly matches the requested metadata. |
| timeUntilEpoch | Calculate the time until a future epoch |
| validateDataSetCreationStatusResponse | Validates and returns a DataSetCreationStatusResponse |
| validateFindPieceResponse | Validates and returns a FindPieceResponse Normalizes the response to always have pieceCid field as a PieceCID object |
| validatePieceAdditionStatusResponse | Validates and returns a PieceAdditionStatusResponse |
References
Section titled “References”StorageService
Section titled “StorageService”Renames and re-exports StorageContext