@filoz/synapse-react 0.0.1

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@filoz/synapse-react",
+  "version": "0.0.1",
+  "description": "React hooks for interacting with Filecoin Onchain Cloud smart contracts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FilOzone/synapse-sdk.git"
+  },
+  "keywords": [
+    "filecoin",
+    "synapse",
+    "filecoin pay",
+    "filecoin onchain cloud",
+    "web3",
+    "react",
+    "hooks"
+  ],
+  "author": "Hugo Dias <hugomrdias@gmail.com>",
+  "license": "Apache-2.0 OR MIT",
+  "bugs": {
+    "url": "https://github.com/FilOzone/synapse-sdk/issues"
+  },
+  "homepage": "https://github.com/FilOzone/synapse-sdk/tree/main/packages/synapse-react",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "module": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist/src",
+    "dist/src/**/*.d.ts",
+    "dist/src/**/*.d.ts.map"
+  ],
+  "wireit": {
+    "build": {
+      "command": "tsc --build --pretty",
+      "clean": "if-file-deleted",
+      "files": [
+        "src/**/*.ts",
+        "tsconfig.json"
+      ],
+      "output": [
+        "dist/**"
+      ]
+    },
+    "lint": {
+      "command": "biome check --no-errors-on-unmatched --files-ignore-unknown=true .",
+      "files": [
+        "src/**/*.ts",
+        "../../biome.json"
+      ],
+      "output": [],
+      "dependencies": [
+        "build"
+      ]
+    }
+  },
+  "dependencies": {
+    "filsnap-adapter": "^3.3.8",
+    "@filoz/synapse-core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "~2.2.6",
+    "@types/node": "^24.9.1",
+    "type-fest": "^5.1.0",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "msw": {
+    "workerDirectory": [
+      "src/test/mocks"
+    ]
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "5.x",
+    "viem": "2.x",
+    "wagmi": "2.x"
+  },
+  "scripts": {
+    "build": "wireit",
+    "lint": "wireit"
+  }
+}

package/src/calibration.ts

@@ -0,0 +1,76 @@
+import { getChain } from '@filoz/synapse-core/chains'
+import { type MutateOptions, useMutation, useQueryClient } from '@tanstack/react-query'
+import type { TransactionReceipt } from 'viem'
+import { waitForTransactionReceipt } from 'viem/actions'
+import { useChainId, useConfig } from 'wagmi'
+import { getConnectorClient } from 'wagmi/actions'
+
+interface UseFundWalletProps {
+  /**
+   * The mutation options.
+   */
+  mutation?: Omit<MutateOptions<TransactionReceipt, Error>, 'mutationFn'>
+  /**
+   * The callback to call when the hash is available.
+   */
+  onHash?: (hash: string) => void
+}
+
+/**
+ * Fund the wallet with USDFC and FIL.
+ *
+ * @param props - The props for the fund wallet.
+ * @param props.mutation - The mutation options.
+ * @param props.onHash - The callback to call when the hash is available.
+ * @returns
+ */
+export function useFundWallet(props?: UseFundWalletProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const publicClient = config.getClient()
+  const queryClient = useQueryClient()
+  const result = useMutation({
+    ...props?.mutation,
+    mutationFn: async () => {
+      const client = await getConnectorClient(config)
+
+      if (!chain.testnet) {
+        throw new Error('Wallet funding is only available on testnet')
+      }
+
+      const responses = await Promise.all([
+        fetch(
+          `https://forest-explorer.chainsafe.dev/api/claim_token?faucet_info=CalibnetUSDFC&address=${client.account.address}`
+        ),
+        fetch(
+          `https://forest-explorer.chainsafe.dev/api/claim_token?faucet_info=CalibnetFIL&address=${client.account.address}`
+        ),
+      ])
+
+      const hashes = await Promise.all(responses.filter((response) => response.ok).map((response) => response.json()))
+
+      props?.onHash?.(hashes[0] as `0x${string}`)
+
+      const wait = await waitForTransactionReceipt(publicClient, {
+        hash: hashes[0] as `0x${string}`,
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-erc20-balance', client.account.address, chain.contracts.usdfc.address],
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: [
+          'balance',
+          {
+            address: client.account.address,
+            chainId,
+          },
+        ],
+      })
+      return wait
+    },
+  })
+  return result
+}

package/src/erc20.ts

@@ -0,0 +1,103 @@
+import { getChain } from '@filoz/synapse-core/chains'
+import type { ERC20BalanceOptions, ERC20BalanceResult } from '@filoz/synapse-core/erc20'
+import * as erc20 from '@filoz/synapse-core/erc20'
+import {
+  type MutateOptions,
+  skipToken,
+  type UseQueryOptions,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
+import type { SetOptional } from 'type-fest'
+import type { TransactionReceipt } from 'viem'
+import { waitForTransactionReceipt } from 'viem/actions'
+import { useAccount, useChainId, useConfig } from 'wagmi'
+import { getConnectorClient } from 'wagmi/actions'
+
+interface UseERC20BalanceProps extends SetOptional<ERC20BalanceOptions, 'address'> {
+  query?: Omit<UseQueryOptions<ERC20BalanceResult>, 'queryKey' | 'queryFn'>
+}
+
+/**
+ * Get the balance and allowance of the ERC20 token.
+ *
+ * @param props - The props to use.
+ * @returns The balance and allowance of the ERC20 token.
+ */
+export function useERC20Balance(props: UseERC20BalanceProps) {
+  const config = useConfig()
+  const chain = getChain(config.state.chainId)
+  const token = props.token ?? chain.contracts.usdfc.address
+  const address = props.address
+
+  const result = useQuery({
+    ...props.query,
+    queryKey: ['synapse-erc20-balance', address, token],
+    queryFn: address
+      ? async () => {
+          const result = await erc20.balance(config.getClient(), {
+            address,
+            token,
+          })
+
+          return result
+        }
+      : skipToken,
+  })
+  return result
+}
+
+type UseApproveAllowanceVariables = Pick<erc20.ERC20ApproveAllowanceOptions, 'amount'>
+
+interface UseApproveAllowanceProps extends Omit<erc20.ERC20ApproveAllowanceOptions, 'amount'> {
+  /**
+   * The mutation options.
+   */
+  mutation?: Omit<MutateOptions<TransactionReceipt, Error, UseApproveAllowanceVariables>, 'mutationFn'>
+  /**
+   * The callback to call when the hash is available.
+   */
+  onHash?: (hash: string) => void
+}
+
+/**
+ * Approve the allowance of the ERC20 token to the payments contract.
+ *
+ * @param props - The props to use.
+ * @returns The mutation to approve the allowance of the ERC20 token to the payments contract.
+ */
+export function useApproveAllowance(props?: UseApproveAllowanceProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const account = useAccount({ config })
+  const queryClient = useQueryClient()
+  const chain = getChain(config.state.chainId)
+  const token = props?.token ?? chain.contracts.usdfc.address
+
+  return useMutation({
+    ...props?.mutation,
+    mutationFn: async ({ amount }: UseApproveAllowanceVariables) => {
+      const client = await getConnectorClient(config, {
+        account: account.address,
+        chainId,
+        connector: account.connector,
+      })
+
+      const approve = await erc20.approveAllowance(client, {
+        token: props?.token,
+        amount,
+      })
+
+      props?.onHash?.(approve)
+      const transactionReceipt = await waitForTransactionReceipt(config.getClient(), {
+        hash: approve,
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-erc20-balance', account.address, token],
+      })
+      return transactionReceipt
+    },
+  })
+}

package/src/filsnap.ts

@@ -0,0 +1,16 @@
+import { type EIP1193Provider, getOrInstallSnap } from 'filsnap-adapter'
+import { useAccountEffect } from 'wagmi'
+
+const SNAP_ID = 'npm:filsnap' //'local:http://localhost:8080'
+// const SNAP_ID = 'local:http://localhost:8080'
+
+export const useFilsnap = ({ version, force }: { version?: string; force?: boolean } = {}) => {
+  useAccountEffect({
+    onConnect: async (data) => {
+      const provider = (await data.connector.getProvider()) as EIP1193Provider
+      if (provider.isMetaMask) {
+        await getOrInstallSnap(provider, SNAP_ID, version ?? '*', force)
+      }
+    },
+  })
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Synapse React - Main Entry Point
+ *
+ * @example
+ * ```ts
+ * import * as react from '@filoz/synapse-react'
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export * from './calibration.ts'
+export * from './erc20.ts'
+export * from './filsnap.ts'
+export * from './payments/index.ts'
+export * from './usdfc.ts'
+export * from './warm-storage/index.ts'

package/src/payments/index.ts

@@ -0,0 +1,357 @@
+import { getChain } from '@filoz/synapse-core/chains'
+import {
+  type AccountInfoOptions,
+  type AccountInfoResult,
+  accountInfo,
+  type DepositOptions,
+  deposit,
+  type OperatorApprovalsOptions,
+  type OperatorApprovalsResult,
+  operatorApprovals,
+  setOperatorApproval,
+  type WithdrawOptions,
+  withdraw,
+} from '@filoz/synapse-core/pay'
+import {
+  type MutateOptions,
+  skipToken,
+  type UseQueryOptions,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
+import type { SetOptional } from 'type-fest'
+import type { Address, TransactionReceipt } from 'viem'
+import { waitForTransactionReceipt } from 'viem/actions'
+import { useAccount, useBlock, useChainId, useConfig } from 'wagmi'
+import { getConnectorClient } from 'wagmi/actions'
+
+interface UseAccountInfoProps extends SetOptional<AccountInfoOptions, 'address'> {
+  /**
+   * Whether to watch blocks.
+   * @default false
+   */
+  watch?: boolean
+  query?: Omit<UseQueryOptions<AccountInfoResult>, 'queryKey' | 'queryFn'>
+}
+
+/**
+ * Get the account info from the payments contract.
+ *
+ * @param props - The props for the balance.
+ * @param props.address - The address of the account to get the balance for.
+ * @param props.token - The address of the ERC20 token to query.
+ * @param props.watch - Whether to watch blocks.
+ * @param props.query - The query options.
+ * @returns The account info including funds, lockup details, and available balance.
+ */
+export function useAccountInfo(props?: UseAccountInfoProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const address = props?.address
+  const { data } = useBlock({
+    blockTag: 'latest',
+    chainId,
+    watch: props?.watch ?? false,
+  })
+
+  const result = useQuery({
+    ...props?.query,
+    queryKey: ['synapse-payments-account-info', address, token, data?.number?.toString()],
+    queryFn: address
+      ? async () => {
+          return await accountInfo(config.getClient(), {
+            token,
+            address,
+            blockNumber: data?.number,
+          })
+        }
+      : skipToken,
+  })
+  return result
+}
+
+export interface UseOperatorApprovalsProps extends SetOptional<OperatorApprovalsOptions, 'address'> {
+  query?: Omit<UseQueryOptions<OperatorApprovalsResult>, 'queryKey' | 'queryFn'>
+}
+
+export type { OperatorApprovalsResult } from '@filoz/synapse-core/pay'
+
+/**
+ * Get the operator approvals from the payments contract.
+ *
+ * @param props - The props for the balance.
+ * @returns The operator approvals.
+ */
+export function useOperatorApprovals(props?: UseOperatorApprovalsProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const operator = props?.operator ?? chain.contracts.storage.address
+  const address = props?.address
+
+  const result = useQuery({
+    ...props?.query,
+    queryKey: ['synapse-payments-operator-approvals', address, token, operator],
+    queryFn: address
+      ? async () => {
+          return await operatorApprovals(config.getClient(), {
+            token,
+            address,
+            operator,
+          })
+        }
+      : skipToken,
+  })
+  return result
+}
+
+type UseDepositVariables = Pick<DepositOptions, 'amount'>
+interface UseDepositProps extends Omit<DepositOptions, 'amount'> {
+  /**
+   * The mutation options.
+   */
+  mutation?: Omit<MutateOptions<TransactionReceipt, Error, UseDepositVariables>, 'mutationFn'>
+  /**
+   * The callback to call when the hash is available.
+   */
+  onHash?: (hash: string) => void
+}
+
+/**
+ * Deposit ERC20 tokens into the payments contract.
+ *
+ * @param props - The props for the deposit.
+ * @param props.address - The address of the account to deposit from.
+ * @param props.token - The address of the ERC20 token to deposit.
+ * @param props.mutation - The mutation options.
+ * @param props.onHash - The callback to call when the hash is available.
+ * @returns The deposit mutation.
+ */
+export function useDeposit(props?: UseDepositProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const account = useAccount({ config })
+  const queryClient = useQueryClient()
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const from = props?.address ?? account.address
+
+  return useMutation({
+    mutationFn: async ({ amount }: UseDepositVariables) => {
+      const client = await getConnectorClient(config, {
+        account: account.address,
+        chainId,
+      })
+
+      const hash = await deposit(client, {
+        amount,
+        address: account.address,
+        token,
+      })
+
+      props?.onHash?.(hash)
+      const transactionReceipt = await waitForTransactionReceipt(config.getClient(), {
+        hash: hash,
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-account-info', from, token],
+      })
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-erc20-balance', from, token],
+      })
+      return transactionReceipt
+    },
+    ...props?.mutation,
+  })
+}
+
+type UseWithdrawVariables = Pick<WithdrawOptions, 'amount'>
+type UseWithdrawProps = Omit<WithdrawOptions, 'amount'> & {
+  mutation?: Omit<MutateOptions<TransactionReceipt, Error, UseWithdrawVariables>, 'mutationFn'>
+  onHash?: (hash: string) => void
+}
+/**
+ * Withdraw ERC20 tokens from the payments contract.
+ *
+ * @param props - The props for the withdraw.
+ * @returns The withdraw mutation.
+ */
+export function useWithdraw(props?: UseWithdrawProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const account = useAccount({ config })
+  const queryClient = useQueryClient()
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const from = props?.address ?? account.address
+
+  return useMutation({
+    mutationFn: async ({ amount }: UseWithdrawVariables) => {
+      const client = await getConnectorClient(config, {
+        account: account.address,
+        chainId,
+      })
+
+      const hash = await withdraw(client, {
+        amount,
+        address: account.address,
+        token,
+      })
+      props?.onHash?.(hash)
+      const transactionReceipt = await waitForTransactionReceipt(config.getClient(), {
+        hash,
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-account-info', from, token],
+      })
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-erc20-balance', from, token],
+      })
+      return transactionReceipt
+    },
+    ...props?.mutation,
+  })
+}
+
+type ApproveOperatorProps =
+  | {
+      /**
+       * The address of the operator to approve.
+       * If not provided, the operator will be the Warm Storage contract.
+       */
+      operator?: Address
+      /**
+       * The address of the ERC20 token to query.
+       * If not provided, the USDFC token address will be used.
+       */
+      token?: Address
+      /**
+       * The mutation options.
+       */
+      mutation?: Omit<MutateOptions<TransactionReceipt, Error>, 'mutationFn'>
+      onHash?: (hash: string) => void
+    }
+  | undefined
+
+/**
+ * Approve a service contract to act as an operator for payment rails.
+ *
+ * @param props - The props for the deposit.
+ * @param props.operator - The address of the operator to approve.
+ * @param props.token - The address of the ERC20 token to deposit.
+ * @param props.mutation - The mutation options.
+ * @param props.onHash - The callback to call when the hash is available.
+ * @returns The deposit mutation.
+ */
+export function useApproveOperator(props?: ApproveOperatorProps) {
+  const config = useConfig()
+  const chainId = useChainId({ config })
+  const chain = getChain(chainId)
+  const account = useAccount({ config })
+  const queryClient = useQueryClient()
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const operator = props?.operator ?? chain.contracts.storage.address
+
+  return useMutation({
+    ...props?.mutation,
+    mutationFn: async () => {
+      const client = await getConnectorClient(config, {
+        account: account.address,
+        chainId,
+      })
+      const hash = await setOperatorApproval(client, {
+        token: props?.token,
+        operator: props?.operator,
+        approve: true,
+      })
+
+      props?.onHash?.(hash)
+      const transactionReceipt = await waitForTransactionReceipt(config.getClient(), {
+        hash,
+      })
+
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-operator-approvals', account.address, token, operator],
+      })
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-account-info', account.address, token],
+      })
+
+      return transactionReceipt
+    },
+  })
+}
+
+type RevokeOperatorProps =
+  | {
+      /**
+       * The address of the operator to revoke.
+       * If not provided, the operator will be the Warm Storage contract.
+       */
+      operator?: Address
+      /**
+       * The address of the ERC20 token to query.
+       * If not provided, the USDFC token address will be used.
+       */
+      token?: Address
+      /**
+       * The mutation options.
+       */
+      mutation?: Omit<MutateOptions<TransactionReceipt, Error>, 'mutationFn'>
+      onHash?: (hash: string) => void
+    }
+  | undefined
+
+/**
+ * Revoke the operator to deposit and withdraw ERC20 tokens from the payments contract.
+ *
+ * @param props - The props for the deposit.
+ * @param props.operator - The address of the operator to approve.
+ * @param props.token - The address of the ERC20 token to deposit.
+ * @param props.mutation - The mutation options.
+ * @param props.onHash - The callback to call when the hash is available.
+ * @returns The deposit mutation.
+ */
+export function useRevokeOperator(props?: RevokeOperatorProps) {
+  const config = useConfig()
+  const configChainId = useChainId({ config })
+  const chain = getChain(configChainId)
+  const account = useAccount({ config })
+  const queryClient = useQueryClient()
+  const token = props?.token ?? chain.contracts.usdfc.address
+  const operator = props?.operator ?? chain.contracts.storage.address
+
+  return useMutation({
+    ...props?.mutation,
+    mutationFn: async () => {
+      const client = await getConnectorClient(config, {
+        account: account.address,
+        chainId: chain.id,
+      })
+      const hash = await setOperatorApproval(client, {
+        token: props?.token,
+        operator: props?.operator,
+        approve: false,
+      })
+      props?.onHash?.(hash)
+      const transactionReceipt = await waitForTransactionReceipt(config.getClient(), {
+        hash,
+      })
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-operator-approvals', account.address, token, operator],
+      })
+      queryClient.invalidateQueries({
+        queryKey: ['synapse-payments-account-info', account.address, token],
+      })
+      return transactionReceipt
+    },
+  })
+}
+
+export * from './use-deposit-and-approve.ts'