Synapse Core
A JavaScript/TypeScript standard library for interacting with Filecoin Onchain Cloud smart contracts
Overview
@filoz/synapse-core is the low-level protocol package for building on Filecoin Onchain Cloud. It provides typed, composable JavaScript and TypeScript utilities for directly using FOC smart contracts, storage provider HTTP APIs, EIP-712 signing flows, and Filecoin-specific data formats.
The package is designed for developers who need finer control than the high-level @filoz/synapse-sdk API. Its modules are organized around protocol boundaries, including Filecoin Pay payment rails, PDP verification, warm storage, service provider discovery, session keys, typed-data signing, PieceCID utilities, devnet helpers, and test mocks.
Most contract helpers follow viem's action style: single-purpose functions that accept a viem client and return strongly typed results. You can import only the protocol area you need, compose actions with viem primitives such as multicall and simulateContract, or use the package as a foundation for higher-level storage workflows.
Installation
pnpm install @filoz/synapse-core [email protected]
Note: viem is a peer dependency and must be installed separately.
In browsers, PieceCID hashing uses WebAssembly. If your page sets a Content-Security-Policy with script-src, add 'wasm-unsafe-eval' (for example script-src 'self' 'wasm-unsafe-eval'). Without it, the package still loads, but hashing throws an error naming the missing directive.
Docs
Check the documentation website
Contributing
Read contributing guidelines.
Acknowledgments
The PieceCID primitives in src/piece/internal/ (FR32 expansion, merkle construction, zero-piece roots, and the digest/size math) are derived from @web3-storage/data-segment, Apache-2.0 OR MIT. That codebase in turn drew on js-fil-utils, go-data-segment, and go-fil-commp-hashhash.
PieceCID hashing is done by @hugomrdias/commp-wasm, a Rust/WASM implementation with SIMD SHA-256.
License
Dual-licensed: MIT, Apache Software License v2 by way of the Permissive License Stack.