Merge pull request #36 from base-org/lukas/docs

[feat] docs

.changeset/honest-shirts-serve.md

@@ -0,0 +1,7 @@
+---
+"@op-wagmi/docs": minor
+"op-wagmi": minor
+"@op-wagmi/example": patch
+---
+
+Add docs

README.md

@@ -1,6 +1,12 @@
-# OP Wagmi
+<br />
 
-Wagmi hooks for OP Stack Chains
+<h1 align="center">
+  OP Wagmi
+</h1>
+
+<p align="center">
+  Wagmi hooks for OP Stack Chains
+<p>
 
 <!-- Badge row 1 - status -->
 
@@ -29,10 +35,6 @@ Wagmi hooks for OP Stack Chains
 - TypeScript ready
 - Test suite running against [forked](https://ethereum.org/en/glossary/#fork) Ethereum network
 
-## Overview
-
-## Community
-
 ## Contributing
 
 If you're interested in contributing, please read the [contributing docs](CONTRIBUTING.md) **before submitting a pull request**.

docs/.vitepress/config.mts

@@ -21,7 +21,76 @@ export default defineConfig({
         text: 'Introduction',
         items: [
           { text: 'Getting started', link: '/' },
-          { text: 'Examples', link: '/docs/examples' },
+          { text: 'Configuration', link: '/docs/configuration' },
+        ],
+      },
+      {
+        text: 'Hooks',
+        items: [
+          {
+            text: 'L1',
+            items: [
+              {
+                text: 'useSimulateDepositETH',
+                link: '/docs/hooks/L1/useSimulateDepositETH',
+              },
+              {
+                text: 'useWriteDepositETH',
+                link: '/docs/hooks/L1/useWriteDepositETH',
+              },
+              {
+                text: 'useSimulateDepositERC20',
+                link: '/docs/hooks/L1/useSimulateDepositERC20',
+              },
+              {
+                text: 'useWriteDepositERC20',
+                link: '/docs/hooks/L1/useWriteDepositERC20',
+              },
+              {
+                text: 'useSimulateProveWithdrawalTransaction',
+                link: '/docs/hooks/L1/useSimulateProveWithdrawalTransaction',
+              },
+              {
+                text: 'useWriteProveWithdrawalTransaction',
+                link: '/docs/hooks/L1/useWriteProveWithdrawalTransaction',
+              },
+              {
+                text: 'useSimulateFinalizeWithdrawalTransaction',
+                link: '/docs/hooks/L1/useSimulateFinalizeWithdrawalTransaction',
+              },
+              {
+                text: 'useWriteFinalizeWithdrawalTransaction',
+                link: '/docs/hooks/L1/useWriteFinalizeWithdrawalTransaction',
+              },
+            ],
+          },
+          {
+            text: 'L2',
+            items: [
+              {
+                text: 'useSimulateWithdrawETH',
+                link: '/docs/hooks/L2/useSimulateWithdrawETH',
+              },
+              {
+                text: 'useWriteWithdrawETH',
+                link: '/docs/hooks/L2/useWriteWithdrawETH',
+              },
+              {
+                text: 'useSimulateWithdrawERC20',
+                link: '/docs/hooks/L2/useSimulateWithdrawERC20',
+              },
+              {
+                text: 'useWriteWithdrawERC20',
+                link: '/docs/hooks/L2/useWriteWithdrawERC20',
+              },
+            ],
+          },
+        ],
+      },
+      {
+        text: 'Glossary',
+        items: [
+          { text: 'Types', link: '/reference/modules' },
         ],
       },
     ],

docs/docs/configuration.md

@@ -0,0 +1,92 @@
+## Configuration
+
+OP Wagmi currently ships with support for Base, Base Goerli, Optimism, Optimism Goerli, Zora, and Zora Goerli. If you'd like to interact with other OP Stack chains, you can extend Wagmi's config to include a list of additional `l2Chains`. You'll also need to add the corresponding chain objects to your Wagmi config so OP Wagmi has access to RPC URLs etc.
+
+::: code-group
+
+```ts [l2Chains.ts]
+export const customL2Chains = {
+  1230123: {
+    // Your L2 chain's ID
+    chainId: 1230123,
+    // The corresponding L1 chain ID
+    l1ChainId: 1,
+    // L1 OP Stack contract addresses for your chain
+    l1Addresses: {
+      portal: {
+        address: '0x...',
+        chainId: 1,
+      },
+      l2OutputOracle: {
+        address: '0x...',
+        chainId: 1,
+      },
+      l1StandardBridge: {
+        address: '0x...',
+        chainId: 1,
+      },
+      l1CrossDomainMessenger: {
+        address: '0x...',
+        chainId: 1,
+      },
+      l1Erc721Bridge: {
+        address: '0x...',
+        chainId: 1,
+      },
+    },
+    // L2 OP Stack contract addresses for your chain
+    l2Addresses: {
+      l2L1MessagePasserAddress: {
+        address: '0x4200000000000000000000000000000000000016',
+        chainId: 1230123,
+      },
+      l2StandardBridge: {
+        address: '0x4200000000000000000000000000000000000010',
+        chainId: 1230123,
+      },
+    },
+  },
+}
+```
+
+```tsx [app.tsx]
+import { useWriteDepositETH } from 'op-wagmi'
+import { useConfig } from 'wagmi'
+import { customL2Chains } from './l2Chains'
+
+const { writeDepositETH } = useWriteDepositETH()
+const config = useConfig()
+
+return (
+  <button
+    onClick={() =>
+      writeDepositETH({
+        args: {
+          to: '0x968Bb4fF2482ff56Af1255019d5b955510A1159e',
+          amount: 1n,
+        },
+        l2ChainId: 1230123,
+        config: { ...config, l2Chains: customL2Chains },
+      })}
+  >
+    Deposit ETH
+  </button>
+)
+```
+
+```ts [config.ts]
+import { createConfig, http } from 'wagmi'
+import { mainnet, sepolia } from 'wagmi/chains'
+import { customChain } from './chains'
+
+export const config = createConfig({
+  chains: [mainnet, sepolia, customChain],
+  transports: {
+    [mainnet.id]: http(),
+    [sepolia.id]: http(),
+    [customChain.id]: http(),
+  },
+})
+```
+
+:::

docs/docs/hooks/L1/useSimulateDepositERC20.md

@@ -0,0 +1,63 @@
+# useSimulateDepositERC20
+
+Simulates a deposit of an ERC20 to L2.
+
+```tsx [example.tsx]
+import { useSimulateDepositERC20 } from 'op-wagmi'
+
+function App() {
+  const result = useSimulateDepositERC20({
+    args: {
+      l1Token: '0xbe9895146f7af43049ca1c1ae358b0541ea49704',
+      l2Token: '0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22',
+      to: '0x968Bb4fF2482ff56Af1255019d5b955510A1159e',
+      amount: 1n,
+    },
+    l2ChainId: 8453,
+  })
+}
+```
+
+## Parameters
+
+### args
+
+- #### l1Token
+  `Address`
+
+  The contract address of the token on L1.
+
+- #### l2Token
+  `Address`
+
+  The contract address of the token on L2.
+
+- #### to
+  `Address`
+
+  The address to deposit the tokens to.
+
+- #### amount
+  `bigint`
+
+  The amount to deposit.
+
+- #### minGasLimit (optional)
+  `number`
+
+  The minimum gas limit to use for the deposit transaction.
+
+- #### extraData (optional)
+  `Hex`
+
+  Extra data to include in the transaction.
+
+### l2ChainId
+
+`number`
+
+The chain ID of the chain you want to deposit to.
+
+## Return Value
+
+Returns wagmi's [useSimulateContract return type](https://beta.wagmi.sh/react/api/hooks/useSimulateContract#return-type).

docs/docs/hooks/L1/useSimulateDepositETH.md

@@ -0,0 +1,51 @@
+# useSimulateDepositETH
+
+Simulates a deposit of ETH to L2.
+
+```tsx [example.tsx]
+import { useSimulateDepositETH } from 'op-wagmi'
+
+function App() {
+  const result = useSimulateDepositETH({
+    args: {
+      to: '0x968Bb4fF2482ff56Af1255019d5b955510A1159e',
+      amount: 1n,
+    },
+    l2ChainId: 8453,
+  })
+}
+```
+
+## Parameters
+
+### args
+
+- #### to
+  `Address`
+
+  The address to deposit the ETH to.
+
+- #### amount
+  `bigint`
+
+  The amount of ETH to deposit.
+
+- #### gasLimit (optional)
+  `number`
+
+  The minimum gas limit to use for the deposit transaction.
+
+- #### data (optional)
+  `Hex`
+
+  Data to include in the transaction.
+
+### l2ChainId
+
+`number`
+
+The chain ID of the chain you want to deposit to.
+
+## Return Value
+
+Returns wagmi's [useSimulateContract return type](https://beta.wagmi.sh/react/api/hooks/useSimulateContract#return-type).

docs/docs/hooks/L1/useSimulateFinalizeWithdrawalTransaction.md

@@ -0,0 +1,36 @@
+# useSimulateFinalizeWithdrawalTransaction
+
+Simulates finalizing a withdrawal transaction.
+
+```tsx [example.tsx]
+import { useSimulateFinalizeWithdrawalTransaction } from 'op-wagmi'
+
+function App() {
+  const result = useSimulateFinalizeWithdrawalTransaction({
+    args: {
+      withdrawalTxHash:
+        '0x18e70002441d72a82eebcf02786da417074c18cf54ca0eba49886773448151e8',
+    },
+    l2ChainId: 8453,
+  })
+}
+```
+
+## Parameters
+
+### args
+
+- #### withdrawalTxHash
+  `Hash`
+
+  The L2 transaction hash of the withdrawal initiation.
+
+### l2ChainId
+
+`number`
+
+The chain ID of the chain you want to withdraw from.
+
+## Return Value
+
+Returns wagmi's [useSimulateContract return type](https://beta.wagmi.sh/react/api/hooks/useSimulateContract#return-type).

docs/docs/hooks/L1/useSimulateProveWithdrawalTransaction.md

@@ -0,0 +1,36 @@
+# useSimulateProveWithdrawalTransaction
+
+Simulates proving a withdrawal transaction.
+
+```tsx [example.tsx]
+import { useSimulateProveWithdrawalTransaction } from 'op-wagmi'
+
+function App() {
+  const result = useSimulateProveWithdrawalTransaction({
+    args: {
+      withdrawalTxHash:
+        '0x18e70002441d72a82eebcf02786da417074c18cf54ca0eba49886773448151e8',
+    },
+    l2ChainId: 8453,
+  })
+}
+```
+
+## Parameters
+
+### args
+
+- #### withdrawalTxHash
+  `Hash`
+
+  The L2 transaction hash of the withdrawal initiation.
+
+### l2ChainId
+
+`number`
+
+The chain ID of the chain you want to withdraw from.
+
+## Return Value
+
+Returns wagmi's [useSimulateContract return type](https://beta.wagmi.sh/react/api/hooks/useSimulateContract#return-type).