Synapse React

Setup

Install dependencies:

npm

npm install @filoz/synapse-react wagmi viem @tanstack/react-query

Copy to clipboard

pnpm

pnpm add @filoz/synapse-react wagmi viem @tanstack/react-query

Copy to clipboard

yarn

yarn add @filoz/synapse-react wagmi viem @tanstack/react-query

Copy to clipboard

bun

bun add @filoz/synapse-react wagmi viem @tanstack/react-query

Copy to clipboard

Requirements:

• React 18+, Wagmi 3.x, viem 2.x, TanStack Query 5.x
• Connected Web3 wallet
• Supported networks: Filecoin Mainnet, Filecoin Calibration

Trying an unreleased version?

Install a preview build from a pull request, commit, or master. See Preview Packages.

Wagmi config:

import { calibration, mainnet } from "@filoz/synapse-core/chains";
import { createConfig, http } from "wagmi";

export const wagmiConfig = createConfig({
  chains: [calibration, mainnet],
  transports: {
    [mainnet.id]: http(),
    [calibration.id]: http(),
  },
});

Copy to clipboard

Provider setup:

Synapse React hooks work within Wagmi and TanStack Query providers. Set these up at the root of your app:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";

const queryClient = new QueryClient();

export default function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <YourApp />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Copy to clipboard

Payments

Query account info and make deposits using hooks:

import { useAccountInfo, useDepositAndApprove } from "@filoz/synapse-react";
import { parseUnits } from "viem";
import { useAccount } from "wagmi";

const PaymentsExample = () => {
  const { address } = useAccount();
  const { data: account, isLoading } = useAccountInfo(
    address ? { address, watch: true } : { watch: true }
  );

  const deposit = useDepositAndApprove({
    onHash: (hash) => console.log("Tx:", hash),
  });

  if (!address) return <div>Connect wallet</div>;
  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <p>Available: {account?.availableFunds.toString()} USDFC</p>
      <button
        onClick={() => deposit.mutate({ amount: parseUnits("1", 18) })}
        disabled={deposit.isPending}
      >
        {deposit.isPending ? "Depositing..." : "Deposit 1 USDFC"}
      </button>
    </div>
  );
};

Copy to clipboard

Storage

Upload files and list data sets:

import { useUpload, useDataSets, useProviders } from "@filoz/synapse-react";
import { useState } from "react";
import { useAccount } from "wagmi";

const StorageExample = () => {
  const { address } = useAccount();
  const { data: providers } = useProviders();
  const { data: dataSets } = useDataSets(address ? { address } : {});
  const [file, setFile] = useState<File>();

  const upload = useUpload({
    source: 'synapse',
    callbacks :{
      onPiecesAdded: (hash) => console.log("Tx:", hash),
    }
  });

  if (!address) return <div>Connect wallet</div>;

  return (
    <div>
      <p>Providers: {providers?.length ?? 0}</p>
      <p>Data sets: {dataSets?.length ?? 0}</p>

      {dataSets?.map((ds) => (
        <div key={ds.dataSetId.toString()}>
          <p>Dataset {ds.dataSetId.toString()}: {ds.pieces.length} pieces</p>
          <input
            type="file"
            onChange={(e) =>
              e.target.files && setFile(e.target.files[0])
            }
          />
          <button
            onClick={() => {
              if(!file)return 
              upload.mutate({ file })
            }}
            disabled={upload.isPending}
          >
            {upload.isPending ? "Uploading..." : "Upload"}
          </button>
          {ds.pieces.map((p) => (
            <div key={p.id.toString()}>
              <p>Piece {p.id.toString()}: {p.cid.toString()}</p>
              <p>URL: {p.url}</p>
            </div>
          ))}
        </div>
      ))}
    </div>
  );
};

Copy to clipboard

Listing data sets without pieces

useDataSets() loads every piece of every data set, which costs at least one extra RPC call per data set. For list views that don’t show pieces, pass includePieces: false to get PdpDataSet[] instead. Each data set’s hasActivePieces still tells you whether it holds pieces.

Piece metadata

Each data set returned by useDataSets() has a pieces: Piece[] array whose items have no metadata field. Read piece metadata from FWSS PieceAdded events or an indexer instead. See the migration guide for the core API changes.

Upload several files to one data set

useUploadPieces uploads files to a data set you choose using synapse-core only. It streams each file to the provider, adds every parked piece in one signed add-pieces request, and returns the files that failed instead of rejecting the whole upload. Pass a session key to sign without wallet prompts.

import type { SessionKey } from "@filoz/synapse-core/session-key";
import type { PdpDataSet } from "@filoz/synapse-core/warm-storage";
import { useUploadPieces } from "@filoz/synapse-react";

const UploadFiles = ({ dataSet, sessionKey }: { dataSet: PdpDataSet; sessionKey?: SessionKey<"Secp256k1"> }) => {
  const upload = useUploadPieces({
    sessionKey,
    onFileProgress: ({ file, bytesUploaded }) => console.log(file.name, bytesUploaded),
    onHash: (hash) => console.log("Tx:", hash),
  });

  return (
    <input
      type="file"
      multiple
      onChange={(e) => {
        const files = Array.from(e.target.files ?? []);
        upload.mutate(
          { dataSet, files, metadata: (file) => ({ name: file.name }) },
          {
            onSuccess: ({ pieces, failed }) => {
              console.log("Added", pieces.map((p) => p.pieceId));
              console.log("Retry", failed.map((f) => f.file.name));
            },
          }
        );
      }}
    />
  );
};

Copy to clipboard

Check out the Synapse React Reference for all available query and mutation hooks.