diff --git a/.github/styles/config/vocabularies/default/accept.txt b/.github/styles/config/vocabularies/default/accept.txt index ff5d87f2..5fe7197c 100644 --- a/.github/styles/config/vocabularies/default/accept.txt +++ b/.github/styles/config/vocabularies/default/accept.txt @@ -271,6 +271,8 @@ peaq pluggable polyfills precompile(?s) +refetch +refetching saltNonce stablecoin superset diff --git a/pages/_meta.json b/pages/_meta.json index 130ecd0f..08e9a17f 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -12,6 +12,11 @@ "type": "page", "display": "hidden" }, + "reference-sdk-react-hooks": { + "title": "React Hooks Reference", + "type": "page", + "display": "hidden" + }, "core-api": { "title": "API", "type": "page" diff --git a/pages/reference-sdk-react-hooks/_meta.json b/pages/reference-sdk-react-hooks/_meta.json new file mode 100644 index 00000000..3e0cc9f7 --- /dev/null +++ b/pages/reference-sdk-react-hooks/_meta.json @@ -0,0 +1,18 @@ +{ + "home": { + "title": "← Go Back", + "href": "/sdk/react-hooks" + }, + "overview": "Overview", + "-- React Hooks Reference": { + "type": "separator", + "title": "React Hooks Reference" + }, + "safeprovider": "SafeProvider", + "createconfig": "createConfig", + "useconfirmtransaction": "useConfirmTransaction", + "usesafe": "useSafe", + "usesendtransaction": "useSendTransaction", + "useupdateowners": "useUpdateOwners", + "useupdatethreshold": "useUpdateThreshold" +} diff --git a/pages/reference-sdk-react-hooks/createconfig.mdx b/pages/reference-sdk-react-hooks/createconfig.mdx new file mode 100644 index 00000000..ebfcb084 --- /dev/null +++ b/pages/reference-sdk-react-hooks/createconfig.mdx @@ -0,0 +1,242 @@ +import { Tabs } from 'nextra/components' + +# `createConfig` + +Returns the configuration object required to initialize the Safe React Hooks. + +## Usage + +It can be used to initialize the [`SafeProvider`](./safeprovider.mdx) or any of the Safe React Hooks. The global configuration will be overwritten within the scope of a hook if a hook is created with a custom configuration. + +{/* */} + + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import App from './App.tsx' + + const config = createConfig({ + // ... + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + ```typescript + import { createConfig, useSafe } from '@safe-global/safe-react-hooks' + + const config = createConfig({ + // ... + }) + + function CustomComponent() { + const { + getChain, + // ... + } = useSafe() + const { name } = getChain({ config }) + + return ( +
+ {name} +
+ ) + } + + export default CustomComponent + ``` + + + +{/* */} + +The `createConfig` parameters vary depending on if you want to connect a Safe account that is already deployed or you want to deploy a new one. + +{/* */} + + + + Use the `safeAddress` property to use an existing Safe account. + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + const config = createConfig({ + chain: sepolia + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + Use the `safeOptions` property to configure and deploy a new Safe account. The Safe address generation is deterministic based on the `owners`, `threshold`, and `saltNonce` values. + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + const config = createConfig({ + chain: sepolia + provider, + signer, + safeOptions: { + owners: ['0x...', '0x...', '0x...'], + threshold: 2, + saltNonce: 123n // Optional + } + }) + ``` + + + +{/* */} + +## Parameters + +`CreateConfigParams` + +```typescript +import { CreateConfigParams } from '@safe-global/safe-react-hooks' +``` + +### `chain` +- **Type:** `Chain` + +The connected chain. + +```typescript focus=2 +const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' +}) +``` + +### `provider` + +- **Type:** `Eip1193Provider | HttpTransport | SocketTransport` + +The provider connected to the blockchain. + +```typescript focus=3 +const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' +}) +``` + +### `signer` + +- **Type:** `HexAddress | PrivateKey | PasskeyClient` + +The signer connected to the Safe as an owner. +- If it's an address, the same address from the `provider` will be used to sign. +- If it's a private key, its derived address will be used to sign. +- If it's a passkey, the passkey will be used to sign. + +```typescript focus=4 +const config = createConfig({ + chain: sepolia + provider, + signer, + safeAddress: '0x...' +}) +``` + +### `safeAddress` (Optional) + +- **Type:** `HexAddress` + +The address of the connected Safe. + +```typescript focus=5 +const config = createConfig({ + chain: sepolia + provider, + signer, + safeAddress: '0x...' +}) +``` + +### `safeOptions` (Optional) + +#### `owners` + +- **Type:** `string[]` + +The list of owners to configure in the Safe. + +```typescript focus=6 +const config = createConfig({ + chain: sepolia + provider, + signer, + safeOptions: { + owners: ['0x...', '0x...', '0x...'], + threshold: 2, + saltNonce: 123n + } +}) +``` + +#### `threshold` + +- **Type:** `number` + +The threshold of the Safe. It must be lower or equal to the number of owners. + +```typescript focus=7 +const config = createConfig({ + chain: sepolia + provider, + signer, + safeOptions: { + owners: ['0x...', '0x...', '0x...'], + threshold: 2, + saltNonce: 123n + } +}) +``` + +#### `saltNonce` (Optional) + +- **Type:** `string` + +The salt introduces randomness or predictability when the Safe address is generated. + +```typescript focus=8 +const config = createConfig({ + chain: sepolia + provider, + signer, + safeOptions: { + owners: ['0x...', '0x...', '0x...'], + threshold: 2, + saltNonce: 123n + } +}) +``` + +## Returns + +`SafeConfig` + +The Safe React Hooks configuration. + +```typescript +import { SafeConfig } from '@safe-global/safe-react-hooks' +``` diff --git a/pages/reference-sdk-react-hooks/overview.mdx b/pages/reference-sdk-react-hooks/overview.mdx new file mode 100644 index 00000000..a0af0a11 --- /dev/null +++ b/pages/reference-sdk-react-hooks/overview.mdx @@ -0,0 +1,27 @@ +# Safe React Hooks Reference + +[Safe React Hooks](../sdk/react-hooks) is a collection of React hooks written in TypeScript that simplify the usage of the Safe\{Core\} SDK for React developers. + +## Install dependencies + +To add the Safe React Hooks to your project, run: + +{/* */} + + + + ```bash pnpm + pnpm add @safe-global/sdk-react-hooks + ``` + + ```bash npm + npm install @safe-global/sdk-react-hooks + ``` + + ```bash yarn + yarn add @safe-global/sdk-react-hooks + ``` + + + +{/* */} diff --git a/pages/reference-sdk-react-hooks/safeprovider.mdx b/pages/reference-sdk-react-hooks/safeprovider.mdx new file mode 100644 index 00000000..fa5f4237 --- /dev/null +++ b/pages/reference-sdk-react-hooks/safeprovider.mdx @@ -0,0 +1,46 @@ +# `SafeProvider` + +The `SafeProvider` is a [context provider](https://react.dev/reference/react/createContext#provider) that wraps a React application and makes all the Safe React Hooks available within the application with a global configuration. + +## Usage + +Any component that uses a Safe React Hook requires a `SafeProvider` to be present somewhere in its parent component tree. + +{/* */} + +```typescript +import ReactDOM from 'react-dom/client' +import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' +import { sepolia } from 'viem/chains' +import App from './App.tsx' + +const config = createConfig({ + chain: sepolia, + provider, + signer, + safeOptions: { + owners: ['0x...', '0x...', '0x...'], + threshold: 2 + } +}) + +const root = document.getElementById('root') + +ReactDOM.createRoot(root).render( + + + +) +``` + +{/* */} + +## Parameters + +### `config` + +- **Type**: `SafeConfig` + +The configuration object required to connect and setup a Safe account in the application. + +Use the [`createConfig`](./createconfig.mdx) function to create the configuration object. diff --git a/pages/reference-sdk-react-hooks/useconfirmtransaction.mdx b/pages/reference-sdk-react-hooks/useconfirmtransaction.mdx new file mode 100644 index 00000000..e675efdf --- /dev/null +++ b/pages/reference-sdk-react-hooks/useconfirmtransaction.mdx @@ -0,0 +1,247 @@ +import { Tabs } from 'nextra/components' + +# `useConfirmTransaction` + +Confirms a pending multi-signature transaction shared via the Safe Transaction Service. + +## Usage + +- If the number of signatures collected in the Safe Transaction Service for a given Safe transaction hash hasn't met the `threshold`, it adds the signature from the connected signer. +- If the number of collected signatures reaches the `threshold`, it executes the Safe transaction. + +This function is only relevant for Safes with their `threshold` greater than `1`. + +{/* */} + + + + ```typescript + import { useConfirmTransaction, ConfirmTransactionVariables } from '@safe-global/safe-react-hooks' + + function App() { + const { + confirmTransaction, + data, + // ... + } = useConfirmTransaction() + + const confirmTransactionParams: ConfirmTransactionVariables = { + safeTxHash: '0x...' + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default App + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Parameters + +`UseConfirmTransactionParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseConfirmTransactionParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfigWithSigner` + +The configuration used instead of the one from the nearest [`SafeProvider`](./safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = useConfirmTransaction({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseConfirmTransactionReturnType` + +```typescript +import { UseConfirmTransactionReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `confirmTransaction` + +- **Type**: `UseMutateFunction` + +Function to confirm a Safe transaction from the connected Safe. + +#### Parameters + +`ConfirmTransactionVariables` + +```typescript +import { ConfirmTransactionVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `confirmTransactionAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to confirm a Safe transaction from the connected Safe. + +#### Parameters + +`ConfirmTransactionVariables` + +```typescript +import { ConfirmTransactionVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `ConfirmTransactionVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-react-hooks/usesafe.mdx b/pages/reference-sdk-react-hooks/usesafe.mdx new file mode 100644 index 00000000..71230d23 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe.mdx @@ -0,0 +1,84 @@ +import { Tabs } from 'nextra/components' + +# `useSafe` + +Provides a set of utilities to access different information about the Safe connected to the [`SafeProvider`](./safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function App() { + const { + isInitialized, + connect, + disconnect, + isOwnerConnected, + isSignerConnected, + getBalance, + getChain, + getTransaction, + getTransactions, + getPendingTransactions, + getSafeInfo, + getSignerAddress + } = useSafe() + + // ... + } + + export default App + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Returns + +`UseSafeReturnType` + +```typescript +import { UseSafeReturnType } from '@safe-global/safe-react-hooks' +``` + +### [`isInitialized`](./usesafe/isinitialized.mdx) +### [`connect`](./usesafe/connect.mdx) +### [`disconnect`](./usesafe/disconnect.mdx) +### [`isOwnerConnected`](./usesafe/isownerconnected.mdx) +### [`isSignerConnected`](./usesafe/issignerconnected.mdx) +### [`getBalance`](./usesafe/getbalance.mdx) +### [`getChain`](./usesafe/getchain.mdx) +### [`getTransaction`](./usesafe/gettransaction.mdx) +### [`getTransactions`](./usesafe/gettransactions.mdx) +### [`getPendingTransactions`](./usesafe/getpendingtransactions.mdx) +### [`getSafeInfo`](./usesafe/getsafeinfo.mdx) +### [`getSignerAddress`](./usesafe/getsigneraddress.mdx) diff --git a/pages/reference-sdk-react-hooks/usesafe/_meta.json b/pages/reference-sdk-react-hooks/usesafe/_meta.json new file mode 100644 index 00000000..b9082ab9 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/_meta.json @@ -0,0 +1,14 @@ +{ + "connect": "connect", + "disconnect": "disconnect", + "getbalance": "getBalance", + "getchain": "getChain", + "getpendingtransactions": "getPendingTransactions", + "getsafeinfo": "getSafeInfo", + "getsigneraddress": "getSignerAddress", + "gettransaction": "getTransaction", + "gettransactions": "getTransactions", + "isinitialized": "isInitialized", + "isownerconnected": "isOwnerConnected", + "issignerconnected": "isSignerConnected" +} diff --git a/pages/reference-sdk-react-hooks/usesafe/connect.mdx b/pages/reference-sdk-react-hooks/usesafe/connect.mdx new file mode 100644 index 00000000..7b3de67d --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/connect.mdx @@ -0,0 +1,47 @@ +import { Tabs } from 'nextra/components' + +# `connect` + +Connects a given signer to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function Connect() { + const { connect } = useSafe() + + const signerAddress = '0x...' + + return ( + + ) + } + + export default Connect + ``` + + + +{/* */} + +## Parameters + +### `signer` + +- **Type**: `string` + +The address of the signer. + +```typescript focus=2 +connect( + '0x...' +) +``` diff --git a/pages/reference-sdk-react-hooks/usesafe/disconnect.mdx b/pages/reference-sdk-react-hooks/usesafe/disconnect.mdx new file mode 100644 index 00000000..4c7df743 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/disconnect.mdx @@ -0,0 +1,31 @@ +import { Tabs } from 'nextra/components' + +# `disconnect` + +Disconnects the signer connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function Disconnect() { + const { disconnect } = useSafe() + + return ( + + ) + } + + export default Disconnect + ``` + + + +{/* */} diff --git a/pages/reference-sdk-react-hooks/usesafe/getbalance.mdx b/pages/reference-sdk-react-hooks/usesafe/getbalance.mdx new file mode 100644 index 00000000..11569144 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/getbalance.mdx @@ -0,0 +1,242 @@ +import { Tabs } from 'nextra/components' + +# `getBalance` + +Returns the balance information of the Safe connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function SafeBalance() { + const { getBalance } = useSafe() + const { + data, + // ... + } = getBalance() + + return ( + <> + {data && JSON.stringify(data)} + + ) + } + + export default SafeBalance + ``` + + + +{/* */} + +## Parameters + +`UseBalanceParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseBalanceParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getBalance({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +[`UseBalanceReturnType`](https://wagmi.sh/react/api/hooks/useBalance#return-type) + +```typescript +import { UseBalanceReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) + +### `data` + +- **Type**: `{ decimals: number; formatted: string; symbol: string; value: bigint; }` +- **Default**: `undefined` + +The last successfully resolved data for the query. + +### `dataUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'success'`. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the query, if an error was thrown. + +### `errorUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'error'`. + +### `errorUpdateCount` + +- **Type**: `number` + +The sum of all errors. + +### `failureCount` + +- **Type**: `number` + +The failure count for the query. + +Incremented every time the query fails. + +Reset to `0` when the query succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the query retry. + +Reset to `null` when the query succeeds. + +### `fetchStatus` + +- **Type**: `'fetching' | 'idle' | 'paused'` + +`fetching` Is true whenever the `queryFn` is executing, which includes initial pending as well as background refetches. + +`paused` The query wanted to fetch, but has been paused. + +`idle` The query is not fetching. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `isError` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isFetched` + +- **Type**: `boolean` + +Will be true if the query has been fetched. + +### `isFetchedAfterMount` + +- **Type**: `boolean` + +Will be `true` if the query has been fetched after the component mounted. + +This property can be used to not show any previously cached data. + +### `isFetching` / `isPaused` + +- **Type**: `boolean` + +The boolean variables derived from `fetchStatus`. + +### `isLoading` + +- **Type**: `boolean` + +Is `true` whenever the first fetch for a query is in-flight. + +Is the same as `isFetching && !isPending`. + +### `isLoadingError` + +- **Type**: `boolean` + +Will be `true` if the query failed while fetching for the first time. + +### `isPlaceholderData` + +- **Type**: `boolean` + +Will be `true` if the data shown is the placeholder data. + +### `isRefetchError` + +- **Type**: `boolean` + +Will be `true` if the query failed while refetching. + +### `isRefetching` + +- **Type**: `boolean` + +Is `true` whenever a background refetch is in-flight, which does not include initial `'pending'`. + +Is the same as `isFetching && !isPending`. + +### `isStale` + +- **Type**: `boolean` + +Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + +### `refetch` + +- **Type**: `(options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise` + +A function to manually refetch the query. + +- `throwOnError` + - When set to `true`, an error will be thrown if the query fails. + - When set to `false`, an error will be logged if the query fails. +- `cancelRefetch` + - When set to `true`, a currently running request will be cancelled before a new request is made. + - When set to `false`, no refetch will be made if there is already a request running. + - Defaults to `true` + +### `status` + +- **Type**: `'error' | 'pending' | 'success'` + +`pending` if there's no cached data and no query attempt was finished yet. + +`error` if the query attempt resulted in an error. The corresponding `error` property has the error received from the attempted fetch. + +`success` if the query has received a response with no errors and is ready to display its data. The corresponding `data` property on the query is the data received from the successful fetch or if the query's `enabled` property is set to `false` and has not been fetched yet `data` is the first `initialData` supplied to the query on initialization. diff --git a/pages/reference-sdk-react-hooks/usesafe/getchain.mdx b/pages/reference-sdk-react-hooks/usesafe/getchain.mdx new file mode 100644 index 00000000..6b62a413 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/getchain.mdx @@ -0,0 +1,90 @@ +import { Tabs } from 'nextra/components' + +# `getChain` + +Get the chain information of the Safe connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function ChainInfo() { + const { getChain } = useSafe() + const { + name, + // ... + } = getChain() + + return ( + <> + {name} + + ) + } + + export default ChainInfo + ``` + + + +{/* */} + +## Parameters + +`UseChainParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseChainParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getChain({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseChainReturnType` + +Returns `UseChainReturnType = SafeConfig['chain']` being `SafeConfig['chain']` the viem's [Chain Type](https://github.com/wevm/viem/blob/main/src/types/chain.ts). + +```typescript +import { UseChainReturnType } from '@safe-global/safe-react-hooks' +``` diff --git a/pages/reference-sdk-react-hooks/usesafe/getpendingtransactions.mdx b/pages/reference-sdk-react-hooks/usesafe/getpendingtransactions.mdx new file mode 100644 index 00000000..68d2efc8 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/getpendingtransactions.mdx @@ -0,0 +1,242 @@ +import { Tabs } from 'nextra/components' + +# `getPendingTransactions` + +Returns all the pending transactions associated with the Safe connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function PendingTransactions() { + const { getPendingTransactions } = useSafe() + const { + data, + // ... + } = getPendingTransactions() + + return ( + <> + {data && JSON.stringify(data)} + + ) + } + + export default PendingTransactions + ``` + + + +{/* */} + +## Parameters + +`UsePendingTransactionsParams` + +Parameters to customize the hook behavior. + +```typescript +import { UsePendingTransactionsParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getPendingTransactions({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UsePendingTransactionsReturnType` + +```typescript +import { UsePendingTransactionsReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) + +### `data` + +- **Type**: [`SafeMultisigTransaction[]`](https://github.com/safe-global/safe-core-sdk/blob/dc602ed126cc210048b278b2372c0979ee4be62b/packages/types-kit/src/types.ts#L216C1-L247C2) +- **Default**: `undefined` + +The last successfully resolved data for the query. + +### `dataUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'success'`. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the query, if an error was thrown. + +### `errorUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'error'`. + +### `errorUpdateCount` + +- **Type**: `number` + +The sum of all errors. + +### `failureCount` + +- **Type**: `number` + +The failure count for the query. + +Incremented every time the query fails. + +Reset to `0` when the query succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the query retry. + +Reset to `null` when the query succeeds. + +### `fetchStatus` + +- **Type**: `'fetching' | 'idle' | 'paused'` + +`fetching` Is true whenever the `queryFn` is executing, which includes initial pending as well as background refetches. + +`paused` The query wanted to fetch, but has been paused. + +`idle` The query is not fetching. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `isError` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isFetched` + +- **Type**: `boolean` + +Will be true if the query has been fetched. + +### `isFetchedAfterMount` + +- **Type**: `boolean` + +Will be `true` if the query has been fetched after the component mounted. + +This property can be used to not show any previously cached data. + +### `isFetching` / `isPaused` + +- **Type**: `boolean` + +The boolean variables derived from `fetchStatus`. + +### `isLoading` + +- **Type**: `boolean` + +Is `true` whenever the first fetch for a query is in-flight. + +Is the same as `isFetching && !isPending`. + +### `isLoadingError` + +- **Type**: `boolean` + +Will be `true` if the query failed while fetching for the first time. + +### `isPlaceholderData` + +- **Type**: `boolean` + +Will be `true` if the data shown is the placeholder data. + +### `isRefetchError` + +- **Type**: `boolean` + +Will be `true` if the query failed while refetching. + +### `isRefetching` + +- **Type**: `boolean` + +Is `true` whenever a background refetch is in-flight, which does not include initial `'pending'`. + +Is the same as `isFetching && !isPending`. + +### `isStale` + +- **Type**: `boolean` + +Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + +### `refetch` + +- **Type**: `(options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise` + +A function to manually refetch the query. + +- `throwOnError` + - When set to `true`, an error will be thrown if the query fails. + - When set to `false`, an error will be logged if the query fails. +- `cancelRefetch` + - When set to `true`, a currently running request will be cancelled before a new request is made. + - When set to `false`, no refetch will be made if there is already a request running. + - Defaults to `true` + +### `status` + +- **Type**: `'error' | 'pending' | 'success'` + +`pending` if there's no cached data and no query attempt was finished yet. + +`error` if the query attempt resulted in an error. The corresponding `error` property has the error received from the attempted fetch. + +`success` if the query has received a response with no errors and is ready to display its data. The corresponding `data` property on the query is the data received from the successful fetch or if the query's `enabled` property is set to `false` and has not been fetched yet `data` is the first `initialData` supplied to the query on initialization. diff --git a/pages/reference-sdk-react-hooks/usesafe/getsafeinfo.mdx b/pages/reference-sdk-react-hooks/usesafe/getsafeinfo.mdx new file mode 100644 index 00000000..10774af1 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/getsafeinfo.mdx @@ -0,0 +1,242 @@ +import { Tabs } from 'nextra/components' + +# `getSafeInfo` + +Returns the information associated with the Safe connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafeInfo } from '@safe-global/safe-react-hooks' + + function SafeInfo() { + const { getSafeInfo } = useSafe() + const { + data, + // ... + } = getSafeInfo() + + return ( + <> + {data && JSON.stringify(data)} + + ) + } + + export default SafeInfo + ``` + + + +{/* */} + +## Parameters + +`UseSafeInfoParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseSafeInfoParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getSafeInfo({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseSafeInfoReturnType` + +```typescript +import { UseSafeInfoReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) + +### `data` + +- **Type**: [`SafeInfo`](https://github.com/safe-global/safe-react-hooks/blob/6f620f2f9492d518af332cb7f21646beef4fb42f/src/types/index.ts#L32-L38) +- **Default**: `undefined` + +The last successfully resolved data for the query. + +### `dataUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'success'`. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the query, if an error was thrown. + +### `errorUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'error'`. + +### `errorUpdateCount` + +- **Type**: `number` + +The sum of all errors. + +### `failureCount` + +- **Type**: `number` + +The failure count for the query. + +Incremented every time the query fails. + +Reset to `0` when the query succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the query retry. + +Reset to `null` when the query succeeds. + +### `fetchStatus` + +- **Type**: `'fetching' | 'idle' | 'paused'` + +`fetching` Is true whenever the `queryFn` is executing, which includes initial pending as well as background refetches. + +`paused` The query wanted to fetch, but has been paused. + +`idle` The query is not fetching. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `isError` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isFetched` + +- **Type**: `boolean` + +Will be true if the query has been fetched. + +### `isFetchedAfterMount` + +- **Type**: `boolean` + +Will be `true` if the query has been fetched after the component mounted. + +This property can be used to not show any previously cached data. + +### `isFetching` / `isPaused` + +- **Type**: `boolean` + +The boolean variables derived from `fetchStatus`. + +### `isLoading` + +- **Type**: `boolean` + +Is `true` whenever the first fetch for a query is in-flight. + +Is the same as `isFetching && !isPending`. + +### `isLoadingError` + +- **Type**: `boolean` + +Will be `true` if the query failed while fetching for the first time. + +### `isPlaceholderData` + +- **Type**: `boolean` + +Will be `true` if the data shown is the placeholder data. + +### `isRefetchError` + +- **Type**: `boolean` + +Will be `true` if the query failed while refetching. + +### `isRefetching` + +- **Type**: `boolean` + +Is `true` whenever a background refetch is in-flight, which does not include initial `'pending'`. + +Is the same as `isFetching && !isPending`. + +### `isStale` + +- **Type**: `boolean` + +Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + +### `refetch` + +- **Type**: `(options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise` + +A function to manually refetch the query. + +- `throwOnError` + - When set to `true`, an error will be thrown if the query fails. + - When set to `false`, an error will be logged if the query fails. +- `cancelRefetch` + - When set to `true`, a currently running request will be cancelled before a new request is made. + - When set to `false`, no refetch will be made if there is already a request running. + - Defaults to `true` + +### `status` + +- **Type**: `'error' | 'pending' | 'success'` + +`pending` if there's no cached data and no query attempt was finished yet. + +`error` if the query attempt resulted in an error. The corresponding `error` property has the error received from the attempted fetch. + +`success` if the query has received a response with no errors and is ready to display its data. The corresponding `data` property on the query is the data received from the successful fetch or if the query's `enabled` property is set to `false` and has not been fetched yet `data` is the first `initialData` supplied to the query on initialization. diff --git a/pages/reference-sdk-react-hooks/usesafe/getsigneraddress.mdx b/pages/reference-sdk-react-hooks/usesafe/getsigneraddress.mdx new file mode 100644 index 00000000..185fd9c0 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/getsigneraddress.mdx @@ -0,0 +1,87 @@ +import { Tabs } from 'nextra/components' + +# `getSignerAddress` + +Returns the address of the signer connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function SignerAddress() { + const { getSignerAddress } = useSafe() + const address = getSignerAddress() + + return ( + <> + {address ? address : 'No signer address'} + + ) + } + + export default SignerAddress + ``` + + + +{/* */} + +## Parameters + +`UseAddressParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseAddressParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getSignerAddress({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseSignerAddressReturnType | undefined` + +The signer address. + +```typescript +import { UseSignerAddressReturnType } from '@safe-global/safe-react-hooks' +``` diff --git a/pages/reference-sdk-react-hooks/usesafe/gettransaction.mdx b/pages/reference-sdk-react-hooks/usesafe/gettransaction.mdx new file mode 100644 index 00000000..4619693e --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/gettransaction.mdx @@ -0,0 +1,282 @@ +import { Tabs } from 'nextra/components' + +# `getTransaction` + +Returns a transaction by its Safe transaction hash or Ethereum transaction hash. + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function TransactionStatus({ safeTxHash, ethereumTxHash }) { + const { getTransaction } = useSafe() + const { + data, + // ... + } = getTransaction({ + safeTxHash // Optional + // ethereumTxHash // Optional + }) + + return ( + <> + {data && JSON.stringify(data)} + + ) + } + + export default TransactionStatus + ``` + + + +{/* */} + +## Parameters + +`UseTransactionParams` + +Parameters to customize the hook behavior. Either `safeTxHash` or `ethereumTxHash` must be provided. + +```typescript +import { UseTransactionParams } from '@safe-global/safe-react-hooks' +``` + +### `safeTxHash` (Optional) + +- **Type**: `string` + +Hash of the Safe transaction to be fetched. + +{/* */} + +```typescript focus=2 +const result = getTransaction({ + safeTxHash: '0x...' +}) +``` + +{/* */} + +### `ethereumTxHash` (Optional) + +- **Type**: `string` + +Hash of the Ethereum transaction to be fetched. + +{/* */} + +```typescript focus=2 +const result = getTransaction({ + ethereumTxHash: '0x...' +}) +``` + +{/* */} + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=5 + import { config } from './config.ts' + + const result = getTransaction({ + safeTxHash: '0x...', + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseTransactionReturnType` + +```typescript +import { UseTransactionReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) + +### `data` + +- **Type**: [`SafeMultisigTransactionResponse`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/types-kit/src/types.ts#L208-L239) | [`UseTransactionReturnTypeWagmi`](https://github.com/safe-global/safe-react-hooks/blob/a0b08e3392e69e2bcf704bc64bae564e989ced8a/src/hooks/useTransaction.ts#L17) +- **Default**: `undefined` + +The last successfully resolved data for the query. + +If `safeTxHash` is provided, it returns the [`SafeMultisigTransactionResponse`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/types-kit/src/types.ts#L208-L239) type. + +If `ethereumTxHash` is provided, it returns the [`UseTransactionReturnTypeWagmi`](https://github.com/safe-global/safe-react-hooks/blob/a0b08e3392e69e2bcf704bc64bae564e989ced8a/src/hooks/useTransaction.ts#L17) type. + +### `dataUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'success'`. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the query, if an error was thrown. + +### `errorUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'error'`. + +### `errorUpdateCount` + +- **Type**: `number` + +The sum of all errors. + +### `failureCount` + +- **Type**: `number` + +The failure count for the query. + +Incremented every time the query fails. + +Reset to `0` when the query succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the query retry. + +Reset to `null` when the query succeeds. + +### `fetchStatus` + +- **Type**: `'fetching' | 'idle' | 'paused'` + +`fetching` Is true whenever the `queryFn` is executing, which includes initial pending as well as background refetches. + +`paused` The query wanted to fetch, but has been paused. + +`idle` The query is not fetching. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `isError` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isFetched` + +- **Type**: `boolean` + +Will be true if the query has been fetched. + +### `isFetchedAfterMount` + +- **Type**: `boolean` + +Will be `true` if the query has been fetched after the component mounted. + +This property can be used to not show any previously cached data. + +### `isFetching` / `isPaused` + +- **Type**: `boolean` + +The boolean variables derived from `fetchStatus`. + +### `isLoading` + +- **Type**: `boolean` + +Is `true` whenever the first fetch for a query is in-flight. + +Is the same as `isFetching && !isPending`. + +### `isLoadingError` + +- **Type**: `boolean` + +Will be `true` if the query failed while fetching for the first time. + +### `isPlaceholderData` + +- **Type**: `boolean` + +Will be `true` if the data shown is the placeholder data. + +### `isRefetchError` + +- **Type**: `boolean` + +Will be `true` if the query failed while refetching. + +### `isRefetching` + +- **Type**: `boolean` + +Is `true` whenever a background refetch is in-flight, which does not include initial `'pending'`. + +Is the same as `isFetching && !isPending`. + +### `isStale` + +- **Type**: `boolean` + +Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + +### `refetch` + +- **Type**: `(options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise` + +A function to manually refetch the query. + +- `throwOnError` + - When set to `true`, an error will be thrown if the query fails. + - When set to `false`, an error will be logged if the query fails. +- `cancelRefetch` + - When set to `true`, a currently running request will be cancelled before a new request is made. + - When set to `false`, no refetch will be made if there is already a request running. + - Defaults to `true` + +### `status` + +- **Type**: `'error' | 'pending' | 'success'` + +`pending` if there's no cached data and no query attempt was finished yet. + +`error` if the query attempt resulted in an error. The corresponding `error` property has the error received from the attempted fetch. + +`success` if the query has received a response with no errors and is ready to display its data. The corresponding `data` property on the query is the data received from the successful fetch or if the query's `enabled` property is set to `false` and has not been fetched yet `data` is the first `initialData` supplied to the query on initialization. diff --git a/pages/reference-sdk-react-hooks/usesafe/gettransactions.mdx b/pages/reference-sdk-react-hooks/usesafe/gettransactions.mdx new file mode 100644 index 00000000..1be10894 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/gettransactions.mdx @@ -0,0 +1,242 @@ +import { Tabs } from 'nextra/components' + +# `getTransactions` + +Returns all the transactions associated with the Safe connected to the [`SafeProvider`](../safeprovider.mdx). + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function Transactions() { + const { getTransactions } = useSafe() + const { + data, + // ... + } = getTransactions() + + return ( + <> + {data && JSON.stringify(data)} + + ) + } + + export default Transactions + ``` + + + +{/* */} + +## Parameters + +`UseTransactionsParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseTransactionsParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfig` + +The configuration used instead of the one from the nearest [`SafeProvider`](../safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = getTransactions({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseTransactionsReturnType` + +```typescript +import { UseTransactionsReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) + +### `data` + +- **Type**: [`Transaction[]`](https://github.com/safe-global/safe-react-hooks/blob/main/src/types/index.ts#L66) +- **Default**: `undefined` + +The last successfully resolved data for the query. + +### `dataUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'success'`. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the query, if an error was thrown. + +### `errorUpdatedAt` + +- **Type**: `number` + +The timestamp for when the query most recently returned the `status` as `'error'`. + +### `errorUpdateCount` + +- **Type**: `number` + +The sum of all errors. + +### `failureCount` + +- **Type**: `number` + +The failure count for the query. + +Incremented every time the query fails. + +Reset to `0` when the query succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the query retry. + +Reset to `null` when the query succeeds. + +### `fetchStatus` + +- **Type**: `'fetching' | 'idle' | 'paused'` + +`fetching` Is true whenever the `queryFn` is executing, which includes initial pending as well as background refetches. + +`paused` The query wanted to fetch, but has been paused. + +`idle` The query is not fetching. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `isError` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isFetched` + +- **Type**: `boolean` + +Will be true if the query has been fetched. + +### `isFetchedAfterMount` + +- **Type**: `boolean` + +Will be `true` if the query has been fetched after the component mounted. + +This property can be used to not show any previously cached data. + +### `isFetching` / `isPaused` + +- **Type**: `boolean` + +The boolean variables derived from `fetchStatus`. + +### `isLoading` + +- **Type**: `boolean` + +Is `true` whenever the first fetch for a query is in-flight. + +Is the same as `isFetching && !isPending`. + +### `isLoadingError` + +- **Type**: `boolean` + +Will be `true` if the query failed while fetching for the first time. + +### `isPlaceholderData` + +- **Type**: `boolean` + +Will be `true` if the data shown is the placeholder data. + +### `isRefetchError` + +- **Type**: `boolean` + +Will be `true` if the query failed while refetching. + +### `isRefetching` + +- **Type**: `boolean` + +Is `true` whenever a background refetch is in-flight, which does not include initial `'pending'`. + +Is the same as `isFetching && !isPending`. + +### `isStale` + +- **Type**: `boolean` + +Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + +### `refetch` + +- **Type**: `(options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise` + +A function to manually refetch the query. + +- `throwOnError` + - When set to `true`, an error will be thrown if the query fails. + - When set to `false`, an error will be logged if the query fails. +- `cancelRefetch` + - When set to `true`, a currently running request will be cancelled before a new request is made. + - When set to `false`, no refetch will be made if there is already a request running. + - Defaults to `true` + +### `status` + +- **Type**: `'error' | 'pending' | 'success'` + +`pending` if there's no cached data and no query attempt was finished yet. + +`error` if the query attempt resulted in an error. The corresponding `error` property has the error received from the attempted fetch. + +`success` if the query has received a response with no errors and is ready to display its data. The corresponding `data` property on the query is the data received from the successful fetch or if the query's `enabled` property is set to `false` and has not been fetched yet `data` is the first `initialData` supplied to the query on initialization. diff --git a/pages/reference-sdk-react-hooks/usesafe/isinitialized.mdx b/pages/reference-sdk-react-hooks/usesafe/isinitialized.mdx new file mode 100644 index 00000000..e2ad05f4 --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/isinitialized.mdx @@ -0,0 +1,39 @@ +import { Tabs } from 'nextra/components' + +# `isInitialized` + +Checks if the [`SafeProvider`](../safeprovider.mdx) is initialized and ready to use. + +This function must be called before interacting with the Safe. + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function IsInitialized() { + const { isInitialized } = useSafe() + + return ( + <> + {isInitialized ? 'Is initialized' : 'Not initialized'} + + ) + } + + export default IsInitialized + ``` + + + +{/* */} + +## Returns + +`boolean` + +The boolean value that indicates if the [`SafeProvider`](../safeprovider.mdx) is initialized and ready to use. diff --git a/pages/reference-sdk-react-hooks/usesafe/isownerconnected.mdx b/pages/reference-sdk-react-hooks/usesafe/isownerconnected.mdx new file mode 100644 index 00000000..fca65adc --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/isownerconnected.mdx @@ -0,0 +1,39 @@ +import { Tabs } from 'nextra/components' + +# `isOwnerConnected` + +Checks if the signer connected to the [`SafeProvider`](../safeprovider.mdx) is an owner of the connected Safe. + +Use the [`isSignerConnected`](./issignerconnected.mdx) function instead to avoid checking ownership. + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function IsOwnerConnected() { + const { isOwnerConnected } = useSafe() + + return ( + <> + {isOwnerConnected ? 'Owner is connected' : 'No owner connected'} + + ) + } + + export default IsOwnerConnected + ``` + + + +{/* */} + +## Returns + +`boolean` + +The boolean value that indicates if an owner of the Safe is connected as a signer. diff --git a/pages/reference-sdk-react-hooks/usesafe/issignerconnected.mdx b/pages/reference-sdk-react-hooks/usesafe/issignerconnected.mdx new file mode 100644 index 00000000..16a6a8ae --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesafe/issignerconnected.mdx @@ -0,0 +1,39 @@ +import { Tabs } from 'nextra/components' + +# `isSignerConnected` + +Checks if a signer is connected to the [`SafeProvider`](../safeprovider.mdx). + +This function doesn't differentiate between signers who are owners of the connected Safe and those who aren't. Use the [`isOwnerConnected`](./isownerconnected.mdx) function instead to explicitly check ownership. + +## Usage + +{/* */} + + + + ```typescript + import { useSafe } from '@safe-global/safe-react-hooks' + + function IsSignerConnected() { + const { isSignerConnected } = useSafe() + + return ( + <> + {isSignerConnected ? 'Signer is connected' : 'No signer connected'} + + ) + } + + export default IsSignerConnected + ``` + + + +{/* */} + +## Returns + +`boolean` + +The boolean value that indicates if a signer is connected. diff --git a/pages/reference-sdk-react-hooks/usesendtransaction.mdx b/pages/reference-sdk-react-hooks/usesendtransaction.mdx new file mode 100644 index 00000000..3193877a --- /dev/null +++ b/pages/reference-sdk-react-hooks/usesendtransaction.mdx @@ -0,0 +1,250 @@ +import { Tabs } from 'nextra/components' + +# `useSendTransaction` + +Executes a Safe transaction from the Safe connected to the [`SafeProvider`](./safeprovider.mdx) or sends it to the Safe Transaction Service if it isn't executable. + +## Usage + +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. +- If the connected Safe is not deployed, it deploys it using the funds from the connected signer to pay for the transaction fees, and executes the transaction or sends it to the Safe Transaction Service, depending on the `threshold`. + +{/* */} + + + + ```typescript + import { useSendTransaction, SendTransactionVariables } from '@safe-global/safe-react-hooks' + + function App() { + const { + sendTransaction, + data, + // ... + } = useSendTransaction() + + const sendTransactionParams: SendTransactionVariables = { + transactions: [{ + to: '0x...', + value: '123', + data: '0x' + }] + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default App + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Parameters + +`UseSendTransactionParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseSendTransactionParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfigWithSigner` + +The configuration used instead of the one from the nearest [`SafeProvider`](./safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = useSendTransaction({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseSendTransactionReturnType` + +```typescript +import { UseSendTransactionReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `sendTransaction` + +- **Type**: `UseMutateFunction` + +Function to send a transaction with the connected Safe. + +#### Parameters + +`SendTransactionVariables` + +```typescript +import { SendTransactionVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to send the transactions. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `sendTransactionAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to send a transaction with the connected Safe. + +#### Parameters + +`SendTransactionVariables` + +```typescript +import { SendTransactionVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to send the transactions. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `SendTransactionVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-react-hooks/useupdateowners.mdx b/pages/reference-sdk-react-hooks/useupdateowners.mdx new file mode 100644 index 00000000..f29f4b9d --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdateowners.mdx @@ -0,0 +1,107 @@ +import { Tabs } from "nextra/components" + +# `useUpdateOwners` + +Updates the owners of the Safe connected to the [`SafeProvider`](./safeprovider.mdx). + +## Usage + +The connected Safe must be already deployed. + +{/* */} + + + + ```typescript + import { useUpdateOwners } from '@safe-global/safe-react-hooks' + + function App() { + const { add, remove, swap } = useUpdateOwners() + + // ... + } + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx ' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Parameters + +`UseUpdateOwnersParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseUpdateOwnersParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfigWithSigner` + +The configuration used instead of the one from the nearest [`SafeProvider`](./safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = useUpdateOwners({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseUpdateOwnersReturnType` + +```typescript +import { UseUpdateOwnersReturnType } from '@safe-global/safe-react-hooks' +``` + +### [`add`](./useupdateowners/add.mdx) +### [`remove`](./useupdateowners/remove.mdx) +### [`swap`](./useupdateowners/swap.mdx) diff --git a/pages/reference-sdk-react-hooks/useupdateowners/_meta.json b/pages/reference-sdk-react-hooks/useupdateowners/_meta.json new file mode 100644 index 00000000..2da2b0c9 --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdateowners/_meta.json @@ -0,0 +1,5 @@ +{ + "add": "add", + "remove": "remove", + "swap": "swap" +} diff --git a/pages/reference-sdk-react-hooks/useupdateowners/add.mdx b/pages/reference-sdk-react-hooks/useupdateowners/add.mdx new file mode 100644 index 00000000..3d797dc9 --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdateowners/add.mdx @@ -0,0 +1,204 @@ +import { Tabs } from "nextra/components" + +# `add` + +Contains the `addOwner` and `addOwnerAsync` functions, which execute a Safe transaction to add a new owner to the Safe connected to the [`SafeProvider`](./safeprovider.mdx) or send it to the Safe Transaction Service if it isn't executable. + +## Usage + +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. + +The connected Safe must be already deployed. + +{/* */} + + + + ```typescript + import { useUpdateOwners, AddOwnerVariables } from '@safe-global/safe-react-hooks' + + function AddOwner() { + const { add } = useUpdateOwners() + const { + addOwner, + data, + // ... + } = add + + const addOwnerParams: AddOwnerVariables = { + ownerAddress: '0x...', + threshold: 2 // Optional + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default AddOwner + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx ' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Structure + +`UseAddOwnerReturnType` + +```typescript +import { UseAddOwnerReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `addOwner` + +- **Type**: `UseMutateFunction` + +Function to add an owner to the connected Safe. + +#### Parameters + +`AddOwnerVariables` + +```typescript +import { AddOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `addOwnerAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to add an owner to the connected Safe. + +#### Parameters + +`AddOwnerVariables` + +```typescript +import { AddOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `TVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-react-hooks/useupdateowners/remove.mdx b/pages/reference-sdk-react-hooks/useupdateowners/remove.mdx new file mode 100644 index 00000000..336a274f --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdateowners/remove.mdx @@ -0,0 +1,204 @@ +import { Tabs } from "nextra/components" + +# `remove` + +Contains the `removeOwner` and `removeOwnerAsync` functions, which execute a Safe transaction to remove an owner of the Safe connected to the [`SafeProvider`](./safeprovider.mdx) or send it to the Safe Transaction Service if it isn't executable. + +## Usage + +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. + +The connected Safe must be already deployed. + +{/* */} + + + + ```typescript + import { useUpdateOwners, RemoveOwnerVariables } from '@safe-global/safe-react-hooks' + + function RemoveOwner() { + const { remove } = useUpdateOwners() + const { + removeOwner, + data, + // ... + } = remove + + const removeOwnerParams: RemoveOwnerVariables = { + ownerAddress: '0x...', + threshold: 1 // Optional + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default RemoveOwner + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx ' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Structure + +`UseRemoveOwnerReturnType` + +```typescript +import { UseRemoveOwnerReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `removeOwner` + +- **Type**: `UseMutateFunction` + +Function to remove an owner of the connected Safe. + +#### Parameters + +`RemoveOwnerVariables` + +```typescript +import { RemoveOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `removeOwnerAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to remove an owner of the connected Safe. + +#### Parameters + +`RemoveOwnerVariables` + +```typescript +import { RemoveOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `RemoveOwnerVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-react-hooks/useupdateowners/swap.mdx b/pages/reference-sdk-react-hooks/useupdateowners/swap.mdx new file mode 100644 index 00000000..a42dbe09 --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdateowners/swap.mdx @@ -0,0 +1,204 @@ +import { Tabs } from "nextra/components" + +# `swap` + +Contains the `swapOwner` and `swapOwnerAsync` functions, which execute a Safe transaction to swap an owner of the Safe connected to the [`SafeProvider`](./safeprovider.mdx) or send it to the Safe Transaction Service if it isn't executable. + +## Usage + +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. + +The connected Safe must be already deployed. + +{/* */} + + + + ```typescript + import { useUpdateOwners, SwapOwnerVariables } from '@safe-global/safe-react-hooks' + + function SwapOwner() { + const { swap } = useUpdateOwners() + const { + swapOwner, + data, + // ... + } = swap + + const swapOwnerParams: SwapOwnerVariables = { + oldOwnerAddress: '0x...', + newOwnerAddress: '0x...' + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default SwapOwner + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx ' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Structure + +`UseSwapOwnerReturnType` + +```typescript +import { UseSwapOwnerReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `swapOwner` + +- **Type**: `UseMutateFunction` + +Function to swap an owner of the connected Safe. + +#### Parameters + +`SwapOwnerVariables` + +```typescript +import { SwapOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `swapOwnerAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to swap an owner of the connected Safe. + +#### Parameters + +`SwapOwnerVariables` + +```typescript +import { SwapOwnerVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `SwapOwnerVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-react-hooks/useupdatethreshold.mdx b/pages/reference-sdk-react-hooks/useupdatethreshold.mdx new file mode 100644 index 00000000..89425fa4 --- /dev/null +++ b/pages/reference-sdk-react-hooks/useupdatethreshold.mdx @@ -0,0 +1,247 @@ +import { Tabs } from 'nextra/components' + +# `useUpdateThreshold` + +Executes a Safe transaction to update the threshold of the Safe connected to the [`SafeProvider`](./safeprovider.mdx). + +## Usage + +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. + +The connected Safe must be already deployed. + +{/* */} + + + + ```typescript + import { useUpdateThreshold, UpdateThresholdVariables } from '@safe-global/safe-react-hooks' + + function App() { + const { + updateThreshold, + data, + // ... + } = useUpdateThreshold() + + const updateThresholdParams: UpdateThresholdVariables = { + threshold: 3 + } + + return ( + <> + + {data && JSON.stringify(data)} + + ) + } + + export default App + ``` + + + ```typescript + import ReactDOM from 'react-dom/client' + import { createConfig, SafeProvider } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + import App from './App.tsx' + + const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + + const root = document.getElementById('root') + + ReactDOM.createRoot(root).render( + + + + ) + ``` + + + +{/* */} + +## Parameters + +`UseUpdateThresholdParams` + +Parameters to customize the hook behavior. + +```typescript +import { UseUpdateThresholdParams } from '@safe-global/safe-react-hooks' +``` + +### `config` (Optional) + +- **Type**: `SafeConfigWithSigner` + +The configuration used instead of the one from the nearest [`SafeProvider`](./safeprovider.mdx). + +{/* */} + + + + ```typescript focus=4 + import { config } from './config.ts' + + const result = useUpdateThreshold({ + config + }) + ``` + + + ```typescript + import { createConfig } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + + export const config = createConfig({ + chain: sepolia, + provider, + signer, + safeAddress: '0x...' + }) + ``` + + + +{/* */} + +## Returns + +`UseUpdateThresholdReturnType` + +```typescript +import { UseUpdateThresholdReturnType } from '@safe-global/safe-react-hooks' +``` + +[TanStack Query mutation documentation](https://tanstack.com/mutation/v5/docs/framework/react/reference/useMutation). + +### `updateThreshold` + +- **Type**: `UseMutateFunction` + +Function to update the threshold of the connected Safe. + +#### Parameters + +`UpdateThresholdVariables` + +```typescript +import { UpdateThresholdVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `updateThresholdAsync` + +- **Type**: `UseMutateAsyncFunction` + +Asynchronous function to update the threshold of the connected Safe. + +#### Parameters + +`UpdateThresholdVariables` + +```typescript +import { UpdateThresholdVariables } from '@safe-global/safe-react-hooks' +``` + +Variables to update the threshold. + +#### Returns + +[`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) + +The result of the transaction in the [`data`](#data) property. + +### `data` + +- **Type**: [`SafeClientResult`](https://github.com/safe-global/safe-core-sdk/blob/main/packages/sdk-starter-kit/src/types.ts#L67-L85) +- **Default**: `undefined` + +The last successfully resolved data for the mutation. + +### `error` + +- **Type**: `null | TError` +- **Default**: `null` + +The error object for the mutation, if an error was encountered. + +### `failureCount` + +- **Type**: `number` + +The failure count for the mutation. + +Incremented every time the mutation fails. + +Reset to `0` when the mutation succeeds. + +### `failureReason` + +- **Type**: `null | TError` + +The failure reason for the mutation retry. + +Reset to `null` when the mutation succeeds. + +### `isError` / `isIdle` / `isPending` / `isSuccess` + +- **Type**: `boolean` + +The boolean variables derived from `status`. + +### `isPaused` + +- **Type**: `boolean` + +Will be `true` if the mutation has been `paused`. + +See [Network Mode](https://tanstack.com/query/v5/docs/framework/react/guides/network-mode) for more information. + +### `reset` + +- **Type**: `() => void` + +A function to clean the mutation internal state (for example, it resets the mutation to its initial state). + +### `status` + +- **Type**: `'idle' | 'pending' | 'error' | 'success'` + +`'idle'` initial status prior to the mutation function executing. + +`'pending'` if the mutation is currently executing. + +`'error'` if the last mutation attempt resulted in an error. + +`'success'` if the last mutation attempt was successful. + +### `submittedAt` + +- **Type**: `number` +- **Default**: `0` + +The timestamp for when the mutation was submitted. + +### `variables` + +- **Type**: `UpdateThresholdVariables` +- **Default**: `undefined` + +The `variables` object passed to the mutation function. diff --git a/pages/reference-sdk-starter-kit/safe-client/confirm.mdx b/pages/reference-sdk-starter-kit/safe-client/confirm.mdx index e4c4419f..900847c4 100644 --- a/pages/reference-sdk-starter-kit/safe-client/confirm.mdx +++ b/pages/reference-sdk-starter-kit/safe-client/confirm.mdx @@ -2,9 +2,10 @@ import { Tabs } from 'nextra/components' # `confirm` -If the number of signatures collected in the Safe Transaction Service for a given Safe transaction hash hasn't met the `threshold`, it will add the signature from the connected signer. +Confirms a pending multi-signature transaction shared via the Safe Transaction Service. -If the number of collected signatures reaches the `threshold`, the Safe transaction will be submitted instantly. +- If the number of signatures collected in the Safe Transaction Service for a given Safe transaction hash hasn't met the `threshold`, it adds the signature from the connected signer. +- If the number of collected signatures reaches the `threshold`, it executes the Safe transaction. ## Usage @@ -17,7 +18,7 @@ If the number of collected signatures reaches the `threshold`, the Safe transact const txResult = await safeClient.confirm({ safeTxHash: '0x...' - }) + }) ``` diff --git a/pages/reference-sdk-starter-kit/safe-client/send.mdx b/pages/reference-sdk-starter-kit/safe-client/send.mdx index df840662..0fad1310 100644 --- a/pages/reference-sdk-starter-kit/safe-client/send.mdx +++ b/pages/reference-sdk-starter-kit/safe-client/send.mdx @@ -2,11 +2,12 @@ import { Tabs } from 'nextra/components' # `send` -If the `threshold` of the connected Safe is greater than 1, it will create the Safe transaction and store it in the Safe Transaction Service to collect the signatures from the Safe owners. +Executes a Safe transaction from the connected Safe or sends it to the Safe Transaction Service if it isn't executable. -If the `threshold` of the connected Safe is 1, the Safe transaction will be submitted and executed immediately. +- If the `threshold` of the connected Safe is greater than `1`, it creates the Safe transaction and submits it to the Safe Transaction Service to collect the signatures from the Safe owners. +- If the `threshold` of the connected Safe is `1`, it executes the Safe transaction. +- If the connected Safe is not deployed, it deploys it using the funds from the connected signer to pay for the transaction fees, and executes the transaction or sends it to the Safe Transaction Service, depending on the `threshold`. -If the Safe account is not deployed, it will be deployed when this method is called and funds will be required in the connected signer account. ## Usage diff --git a/pages/sdk/_meta.json b/pages/sdk/_meta.json index 504dcfb2..982acac7 100644 --- a/pages/sdk/_meta.json +++ b/pages/sdk/_meta.json @@ -12,6 +12,15 @@ "protocol-kit": "Protocol Kit", "api-kit": "API Kit", "relay-kit": "Relay Kit", + "-- React Hooks": { + "type": "separator", + "title": "React Hooks" + }, + "react-hooks": "Safe React Hooks", + "-- Integrations": { + "type": "separator", + "title": "Integrations" + }, "signers": "Signers", "onramp": "Onramp" } diff --git a/pages/sdk/api-kit.mdx b/pages/sdk/api-kit.mdx index 89688823..201cee90 100644 --- a/pages/sdk/api-kit.mdx +++ b/pages/sdk/api-kit.mdx @@ -17,4 +17,5 @@ The following guides show how to use the API Kit and integrate it into your proj - [Propose and confirm transactions](./api-kit/guides/propose-and-confirm-transactions.mdx) ## Resources + - [API Kit on GitHub](https://github.com/safe-global/safe-core-sdk/tree/main/packages/api-kit) diff --git a/pages/sdk/protocol-kit.mdx b/pages/sdk/protocol-kit.mdx index 2c06ac5c..2d6a05bb 100644 --- a/pages/sdk/protocol-kit.mdx +++ b/pages/sdk/protocol-kit.mdx @@ -19,4 +19,5 @@ The following guides show how to use the Protocol Kit and integrate it into your - [Message signatures](./protocol-kit/guides/signatures/messages) ## Resources + - [Protocol Kit on GitHub](https://github.com/safe-global/safe-core-sdk/tree/main/packages/protocol-kit) diff --git a/pages/sdk/react-hooks.mdx b/pages/sdk/react-hooks.mdx new file mode 100644 index 00000000..d0f8f2d6 --- /dev/null +++ b/pages/sdk/react-hooks.mdx @@ -0,0 +1,23 @@ +import { Grid } from '@mui/material' +import CustomCard from '../../components/CustomCard' + +# Safe React Hooks + +The Safe React Hooks are the starting point for interacting with the Safe smart account using a React application. + +These hooks are built on top of the [Starter Kit](./starter-kit.mdx), which leverages and abstracts the complex logic from several kits from the Safe\{Core\} SDK, allowing you to set a React context that gives access to the exposed Safe functionality everywhere in your application. + + + + + +The following guides show how to use the Safe React Hooks and integrate it into your project: +- [Send transactions](./react-hooks/guides/send-transactions) + +## Resources + +- [Safe React Hooks on GitHub](https://github.com/safe-global/safe-react-hooks) diff --git a/pages/sdk/react-hooks/_meta.json b/pages/sdk/react-hooks/_meta.json new file mode 100644 index 00000000..da9d17ec --- /dev/null +++ b/pages/sdk/react-hooks/_meta.json @@ -0,0 +1,7 @@ +{ + "guides": "Guides", + "references": { + "title": "Reference", + "href": "/reference-sdk-react-hooks/overview" + } +} diff --git a/pages/sdk/react-hooks/guides/_meta.json b/pages/sdk/react-hooks/guides/_meta.json new file mode 100644 index 00000000..90f872c2 --- /dev/null +++ b/pages/sdk/react-hooks/guides/_meta.json @@ -0,0 +1,3 @@ +{ + "send-transactions": "Send Transactions" +} \ No newline at end of file diff --git a/pages/sdk/react-hooks/guides/send-transactions.mdx b/pages/sdk/react-hooks/guides/send-transactions.mdx new file mode 100644 index 00000000..cefb9e29 --- /dev/null +++ b/pages/sdk/react-hooks/guides/send-transactions.mdx @@ -0,0 +1,208 @@ +import { Steps, Tabs } from 'nextra/components' + +# Send Transactions + +This guide will teach you how to deploy new Safe accounts and create, sign, and execute Safe transactions using the Safe React Hooks. + +For more detailed information, see the [Safe React Hooks Reference](../../../reference-sdk-react-hooks/overview.mdx). + +## Prerequisites + +- [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) + +## Install dependencies + +First, you need to install some dependencies. + +```bash +pnpm add @safe-global/safe-react-hooks +``` + +## Steps + + + + ### Imports + + Here are all the necessary imports for this guide. + + {/* */} + + ```typescript + import { + SafeProvider, + createConfig, + useSafe, + useSendTransaction, + SendTransactionVariables, + useConfirmTransaction, + ConfirmTransactionVariables + } from '@safe-global/safe-react-hooks' + import { sepolia } from 'viem/chains' + ``` + + {/* */} + + ### Create a signer and provider + + Firstly, you need to get a signer, which will be the owner of a Safe account after it's deployed. + + This example uses a private key, but any way to get an EIP-1193 compatible signer can be used. + + {/* */} + + ```typescript + const SIGNER_ADDRESS = // ... + const SIGNER_PRIVATE_KEY = // ... + + const RPC_URL = 'https://rpc.ankr.com/eth_sepolia' + ``` + + {/* */} + + ### Initialize the Safe React Hooks + + You need to wrap your app with the [`SafeProvider`](../../../reference-sdk-react-hooks/safeprovider.mdx) to have access to the different Safe React Hooks like `useSendTransaction()`, `useConfirmTransaction()`, and `usePendingTransactions()` that will provide the functionality you need in this guide. + + `SafeProvider` receives a `config` object with different properties to create the global configuration that you can get from the [`createConfig`](../../../reference-sdk-react-hooks/createconfig.mdx) function. + + {/* */} + + + + When deploying a new Safe account for the connected signer, you need to pass the configuration of the Safe in the `safeOptions` property. In this case, the Safe account is configured with your signer as the only owner. + + ```typescript + const config = createConfig({ + chain: sepolia, + provider: RPC_URL, + signer: SIGNER_PRIVATE_KEY, + safeOptions: { + owners: [SIGNER_ADDRESS], + threshold: 1 + } + }) + ``` + + + When connecting an existing Safe account, you need to pass the `safeAddress` property. + + ```typescript + const config = createConfig({ + chain: sepolia, + provider: RPC_URL, + signer: SIGNER_PRIVATE_KEY, + safeAddress: '0x...' + }) + ``` + + + + {/* */} + + To apply the global configuration to your app, pass the created `config` to the `SafeProvider`. + + {/* */} + + ```typescript + + + + ``` + + {/* */} + + ### Create a Safe transaction + + Create an array of Safe transactions to execute. + + {/* */} + + ```typescript + const transactions = [{ + to: '0x...', + data: '0x', + value: '0' + }] + ``` + + {/* */} + + ### Send the Safe transaction + + Create a `SendTransaction` component in your application to create and send a transaction. + + If you configured your Safe with `threshold` equal to `1`, calling the `sendTransaction` function from the [`useSendTransaction`](../../../reference-sdk-react-hooks/usesendtransaction.mdx) hook will execute the Safe transaction. However, if the `threshold` is greater than `1` the other owners of the Safe will need to confirm the transaction until the required number of signatures are collected. + + {/* */} + + + + ```typescript + function SendTransaction() { + const { sendTransaction } = useSendTransaction() + + const sendTransactionParams: SendTransactionVariables = { + transactions + } + + return ( + + ) + } + + export default SendTransaction + ``` + + + + {/* */} + + ### Confirm the Safe transaction + + Create a `ConfirmPendingTransactions` component in your application to check the transactions pending for confirmation in case the Safe transaction needs to be confirmed by other Safe owners. + + Retrieve all the pending Safe transactions from the Safe Transaction Service by calling the [`getPendingTransaction`](../../../reference-sdk-react-hooks/usesafe/getpendingtransactions.mdx) function from the [`useSafe`](../../../reference-sdk-react-hooks/usesafe.mdx) hook, and call the `confirmTransaction` function from the [`useConfirmTransaction`](../../../reference-sdk-react-hooks/useconfirmtransaction.mdx) hook to confirm them. + + Notice that the `SafeProvider` configuration needs to be initialized with a different Safe owner as the `signer` when confirming a transaction. + + {/* */} + + + + ```typescript + function ConfirmPendingTransactions() { + const { getPendingTransactions } = useSafe() + const { data = [] } = getPendingTransactions() + const { confirmTransaction } = useConfirmTransaction() + + return ( + <> + {data.length > 0 && data.map(tx => ( + <> + {tx.safeTxHash} +