Skip to content

Commit

Permalink
Update hooks args and return values to make them more readable and ad…
Browse files Browse the repository at this point in the history 
…d wagmi links (#40)
  • Loading branch information
@Pabl0cks
Pabl0cks authored Nov 28, 2023
1 parent 6ee23b4 commit 0a5f8a6
Show file tree
Hide file tree
Showing 6 changed files with 93 additions and 17 deletions.
11 changes: 10 additions & 1 deletion docs/hooks/useDeployedContractInfo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,17 @@ sidebar_position: 5
Use this hook to fetch details about a deployed smart contract, including the ABI and address.

```ts
// ContractName: name of the deployed contract
const { data: deployedContractData } = useDeployedContractInfo(contractName);
```

This example retrieves the details of the deployed contract with the specified name and stores the details in the deployedContractData object.

## Parameters

| Parameter | Type | Description |
| :--------------- | :------- | :-------------------- |
| **contractName** | `string` | Name of the contract. |

### Return Value

- `data`: Object containing `address` and `abi` of contract.
13 changes: 12 additions & 1 deletion docs/hooks/useScaffoldContract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,15 @@ const setGreeting = async () => {
};
```

This example uses the `useScaffoldContract` hook to obtain a contract instance for the `YourContract` smart contract. The data property of the returned object contains the contract instance that can be used to call any of the smart contract methods.
This example uses the `useScaffoldContract` hook to obtain a contract instance for the `YourContract` smart contract.

## Configuration

| Parameter | Type | Description |
| :-------------------------- | :------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **contractName** | `string` | Name of the contract. |
| **walletClient** (optional) | [`WalletClient`](https://wagmi.sh/react/hooks/useWalletClient) | Wallet client must be passed in order to call `write` methods of the contract |

## Return Value

- `data` : Object representing viem's [contract instance](https://viem.sh/docs/contract/getContract.html#return-value). Which can be used to call `read` and `write` of the contract.
22 changes: 19 additions & 3 deletions docs/hooks/useScaffoldContractRead.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,25 @@ Use this hook to read public variables and get data from read-only functions of
```ts
const { data: totalCounter } = useScaffoldContractRead({
contractName: "YourContract",
functionName: "getGreeting",
args: ["ARGUMENTS IF THE FUNCTION ACCEPTS ANY"],
functionName: "userGreetingCounter",
args: ["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],
});
```

This example retrieves the data returned by the `getGreeting` function of the `YourContract` smart contract. If the function accepts any arguments, they can be passed in the args array. The retrieved data is stored in the `data` property of the returned object.
This example retrieves the data returned by the `userGreetingCounter` function of the `YourContract` smart contract.

## Configuration

| Parameter | Type | Description |
| :------------------ | :------- | :----------------------------------------------------------- |
| **contractName** | `string` | Name of the contract to read from. |
| **functionName** | `string` | Name of the function to call. |
| **args** (optional) | `any[]` | Array of arguments to pass to the function (if accepts any). |

You can also pass other arguments accepted by [useContractRead wagmi hook](https://wagmi.sh/react/hooks/useContractRead#configuration).

## Return Values

- The retrieved data is stored in the `data` property of the returned object.
- You can refetch the data by calling the `refetch` function.
- The extended object includes properties inherited from wagmi useContractRead. You can check the [useContractRead return values](https://wagmi.sh/react/hooks/useContractRead#return-value) documentation to check the types.
24 changes: 20 additions & 4 deletions docs/hooks/useScaffoldContractWrite.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,8 @@ const { writeAsync, isLoading, isMining } = useScaffoldContractWrite({
contractName: "YourContract",
functionName: "setGreeting",
args: ["The value to set"],
// For payable functions
value: parseEther("0.1"),
// The number of block confirmations to wait for before considering transaction to be confirmed (default : 1).
blockConfirmations: 1,
// The callback function to execute when the transaction is confirmed.
onBlockConfirmation: txnReceipt => {
console.log("Transaction blockHash", txnReceipt.blockHash);
},
Expand All @@ -30,7 +27,7 @@ To send the transaction, you can call the `writeAsync` function returned by the
</button>
```

This example sends a transaction to the `YourContract` smart contract to call the `setGreeting` function with the arguments passed in `args`. The `writeAsync` function sends the transaction to the smart contract, and the `isLoading` and `isMining` properties indicate whether the transaction is currently being processed by the network.
This example sends a transaction to the `YourContract` smart contract to call the `setGreeting` function with the arguments passed in `args`. The `writeAsync` function sends the transaction to the smart contract.

It is also possible to pass arguments imperatively to the `writeAsync` function:

Expand All @@ -39,3 +36,22 @@ It is also possible to pass arguments imperatively to the `writeAsync` function:
Send TX
</button>
```

## Configuration

| Parameter | Type | Description |
| :--------------------------------- | :--------- | :------------------------------------------------------------------------------------------------------ |
| **contractName** | `string` | Name of the contract to write to. |
| **functionName** | `string` | Name of the function to call. |
| **args** (optional) | `any[]` | Array of arguments to pass to the function (if accepts any). |
| **value** (optional) | `bigint` | Amount of ETH to send with the transaction (for payable functions only). |
| **onBlockConfirmation** (optional) | `function` | Callback function to execute when the transaction is confirmed. |
| **blockConfirmations** (optional) | `number` | Number of block confirmations to wait for before considering transaction to be confirmed (default : 1). |

You can also pass other arguments accepted by [useContractWrite wagmi hook](https://wagmi.sh/react/hooks/useContractWrite#configuration).

## Return Values

- `writeAsync` function sends the transaction to the smart contract.
- `isMining` property indicates whether the transaction is currently being mined.
- The extended object includes properties inherited from wagmi useContractWrite. You can check the [useContractWrite return values](https://wagmi.sh/react/hooks/useContractWrite#return-value) documentation to check the types.
28 changes: 21 additions & 7 deletions docs/hooks/useScaffoldEventHistory.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,33 @@ const {
} = useScaffoldEventHistory({
contractName: "YourContract",
eventName: "GreetingChange",
// Specify the starting block number from which to read events, this is a bigint.
fromBlock: 31231n,
// If set to true, the events will be updated every pollingInterval milliseconds set at scaffoldConfig (default: false)
watch: true,
// Apply filters to the event based on parameter names and values { [parameterName]: value },
filters: { premium: true },
// If set to true it will return the block data for each event (default: false)
blockData: true,
// If set to true it will return the transaction data for each event (default: false),
transactionData: true,
// If set to true it will return the receipt data for each event (default: false),
receiptData: true,
});
```

This example retrieves the historical event logs for the `GreetingChange` event of the `YourContract` smart contract, starting from block number 31231 and filtering events where the premium parameter is true. The data property of the returned object contains an array of event objects, each containing the event parameters and (optionally) the block, transaction, and receipt data. The `isLoading` property indicates whether the event logs are currently being fetched, and the `error` property contains any error that occurred during the fetching process (if applicable). Since `watch` is set to true, the event logs will be refetched every [`pollingInterval`](/deploying/deploy-nextjs-app#--pollinginterval) (set at `scaffold.config.ts`).
This example retrieves the historical event logs for the `GreetingChange` event of the `YourContract` smart contract, starting from block number 31231 and filtering events where the premium parameter is true.

## Configuration

| Parameter | Type | Description |
| :----------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **contractName** | `string` | Name of the contract to read from. |
| **eventName** | `string` | Name of the event to read. |
| **fromBlock** | `bigint` | Block number from which to start reading events. |
| **filters** (optional) | `object` | Apply filters to the event based on parameter names and values `{ [parameterName]: value }`. |
| **blockData** (optional) | `boolean` | If set to true it will return the block data for each event (default: false). |
| **transactionData** (optional) | `boolean` | If set to true it will return the transaction data for each event (default: false). |
| **receiptData** (optional) | `boolean` | If set to true it will return the receipt data for each event (default: false). |
| **watch** (optional) | `boolean` | If set to true, the events will be refetched every [`pollingInterval`](/deploying/deploy-nextjs-app#--pollinginterval) set at `scaffold.config.ts`. (default: false). |
| **enabled** (optional) | `boolean` | If set to false, the hook will not fetch any data (default: true). |

## Return Values

- `data` property of the returned object contains an array of event objects, each containing the event parameters and (optionally) the block, transaction, and receipt data.
- `isLoading` property indicates whether the event logs are currently being fetched.
- `error` property contains any error that occurred during the fetching process (if applicable).
12 changes: 11 additions & 1 deletion docs/hooks/useScaffoldEventSubscriber.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,17 @@ useScaffoldEventSubscriber({
});
```

This example subscribes to the `GreetingChange` event emitted by the `YourContract` smart contract and logs the parameters from the event to the console when it's emitted. The `listener` function accepts an array of `logs` that occurred during the [`pollingInterval`](/deploying/deploy-nextjs-app#--pollinginterval) (set at `scaffold.config.ts`) and each array items contains an `args` property which can be destructured to get the parameters emitted by the event, this function can customized according to your needs.
This example subscribes to the `GreetingChange` event emitted by the `YourContract` smart contract and logs the parameters from the event to the console when it's emitted.

This hook is a wrapper around wagmi's [useContractEvent](https://wagmi.sh/react/hooks/useContractEvent).

## Configuration

| Parameter | Type | Description |
| :--------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **contractName** | `string` | Name of the contract to read from. |
| **eventName** | `string` | Name of the event to read. |
| **listener** | `function` | Callback function to execute when the event is emitted. Accepts an array of `logs` that occurred during the [`pollingInterval`](/deploying/deploy-nextjs-app#--pollinginterval) set at `scaffold.config.ts`. Each array item contains an `args` property, which can be destructured to get the parameters emitted by the event. This function can customized according to your needs. |

:::note

Expand Down

0 comments on commit 0a5f8a6

Please sign in to comment.