feat: decodeEventLog

.changeset/blue-pillows-peel.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added `decodeEventLog`.

site/.vitepress/sidebar.ts

@@ -435,8 +435,8 @@ export const sidebar: DefaultTheme.Sidebar = {
               link: '/docs/contract/decodeErrorResult',
             },
             {
-              text: 'decodeEventTopics 🚧',
-              link: '/docs/contract/decodeEventTopics',
+              text: 'decodeEventLog',
+              link: '/docs/contract/decodeEventLog',
             },
             {
               text: 'decodeFunctionData',

site/docs/contract/decodeAbi.md

@@ -2,7 +2,7 @@
 
 Decodes ABI encoded data using the [ABI specification](https://solidity.readthedocs.io/en/latest/abi-spec.html), given a set of ABI parameters (`inputs`/`outputs`) and the encoded ABI data.
 
-The `decodeAbi` function is used by the other contract decoding utilities (ie. `decodeFunctionData`, `decodeEventTopics`, etc).
+The `decodeAbi` function is used by the other contract decoding utilities (ie. `decodeFunctionData`, `decodeEventLog`, etc).
 
 ## Install
 

site/docs/contract/decodeEventLog.md

@@ -0,0 +1,158 @@
+# decodeEventLog
+
+Decodes ABI encoded event topics & data (from an [Event Log](/docs/glossary/terms#TODO)) into an event name and structured arguments (both indexed & non-indexed).
+
+## Install
+
+```ts
+import { decodeEventLog } from 'viem/contract'
+```
+
+## Usage
+
+::: code-group
+
+```ts [example.ts]
+import { decodeEventLog } from 'viem/contract'
+
+const topics = decodeEventLog({
+  abi: wagmiAbi,
+  data: '0x0000000000000000000000000000000000000000000000000000000000000001',
+  topics: [
+    '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0', 
+    '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
+    '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
+  ]
+})
+/**
+ *  {
+ *    eventName: 'Transfer',
+ *    args: {
+ *      from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+ *      to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
+ *      value: 1n
+ *    }
+ *  }
+ */
+```
+
+```ts
+export const wagmiAbi = [
+  ...
+  {
+    inputs: [
+      {
+        indexed: true,
+        name: 'from',
+        type: 'address',
+      },
+      { indexed: true, name: 'to', type: 'address' },
+      {
+        indexed: false,
+        name: 'value',
+        type: 'uint256',
+      },
+    ],
+    name: 'Transfer',
+    type: 'event',
+  },
+  ...
+] as const;
+```
+
+```ts [client.ts]
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+export const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: http()
+})
+```
+
+:::
+
+## Return Value
+
+```ts
+{
+  eventName: string;
+  args: Inferred;
+}
+```
+
+Decoded ABI event topics.
+
+## Parameters
+
+### abi
+
+- **Type:** [`Abi`](/docs/glossary/types#TODO)
+
+The contract's ABI.
+
+```ts
+const topics = decodeEventLog({
+  abi: wagmiAbi, // [!code focus]
+  data: '0x0000000000000000000000000000000000000000000000000000000000000001',
+  topics: [
+    '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0', 
+    '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
+    '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
+  ]
+})
+```
+
+### topics
+
+- **Type:** `[Hex, ...(Hex | Hex[] | null)[]]`
+
+A set of topics (encoded indexed args) from the [Event Log](/docs/glossary/terms#TODO).
+
+```ts
+const topics = decodeEventLog({
+  abi: wagmiAbi,
+  data: '0x0000000000000000000000000000000000000000000000000000000000000001',
+  topics: [ // [!code focus:5]
+    '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0', 
+    '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
+    '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
+  ]
+})
+```
+
+### data (optional)
+
+- **Type:** `string`
+
+The data (encoded non-indexed args) from the [Event Log](/docs/glossary/terms#TODO).
+
+```ts
+const topics = decodeEventLog({
+  abi: wagmiAbi,
+  data: '0x0000000000000000000000000000000000000000000000000000000000000001', // [!code focus]
+  topics: [
+    '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0', 
+    '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
+    '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
+  ]
+})
+```
+
+### eventName (optional)
+
+- **Type:** `string`
+
+An event name from the ABI. Provide an `eventName` to infer the return type of `decodeEventLog`.
+
+```ts
+const topics = decodeEventLog({
+  abi: wagmiAbi,
+  eventName: 'Transfer', // [!code focus]
+  topics: [
+    '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0', 
+    '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
+    '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
+  ]
+})
+```

site/docs/contract/encodeEventTopics.md

@@ -76,10 +76,10 @@ import { encodeEventTopics } from 'viem/contract'
 const topics = encodeEventTopics({
   abi: wagmiAbi,
   eventName: 'Transfer'
-  args: [{
+  args: {
     from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
     to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
-  }]
+  }
 })
 // ["0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0", "0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266", "0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8"]
 ```

src/actions/public/getFilterLogs.test.ts

@@ -90,6 +90,7 @@ describe('events', () => {
     await mine(testClient, { blocks: 1 })
 
     let logs = await getFilterLogs(publicClient, { filter })
+    console.log(logs[0])
     assertType<Log[]>(logs)
     expect(logs.length).toBe(2)
   })

src/contract.ts

@@ -37,6 +37,8 @@ export type {
   DecodeAbiArgs,
   DecodeErrorResultArgs,
   DecodeErrorResultResponse,
+  DecodeEventLogArgs,
+  DecodeEventLogResponse,
   DecodeFunctionDataArgs,
   DecodeFunctionResultArgs,
   DecodeFunctionResultResponse,
@@ -51,6 +53,7 @@ export type {
 export {
   decodeAbi,
   decodeErrorResult,
+  decodeEventLog,
   decodeFunctionData,
   decodeFunctionResult,
   encodeAbi,

src/errors/abi.ts

@@ -121,7 +121,23 @@ export class AbiErrorSignatureNotFoundError extends BaseError {
       [
         `Encoded error signature "${signature}" not found on ABI.`,
         'Make sure you are using the correct ABI and that the error exists on it.',
-        `You can look up the signature "${signature}" here: https://sig.eth.samczsun.com/.`,
+        `You can look up the signature here: https://openchain.xyz/signatures?query=${signature}.`,
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiEventSignatureNotFoundError extends BaseError {
+  name = 'AbiEventSignatureNotFoundError'
+  constructor(signature: Hex, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Encoded event signature "${signature}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the event exists on it.',
+        `You can look up the signature here: https://openchain.xyz/signatures?query=${signature}.`,
       ].join('\n'),
       {
         docsPath,
@@ -183,7 +199,7 @@ export class AbiFunctionSignatureNotFoundError extends BaseError {
       [
         `Encoded function signature "${signature}" not found on ABI.`,
         'Make sure you are using the correct ABI and that the function exists on it.',
-        `You can look up the signature "${signature}" here: https://sig.eth.samczsun.com/.`,
+        `You can look up the signature here: https://openchain.xyz/signatures?query=${signature}.`,
       ].join('\n'),
       {
         docsPath,

src/errors/index.ts

@@ -8,6 +8,7 @@ export {
   AbiErrorInputsNotFoundError,
   AbiErrorNotFoundError,
   AbiErrorSignatureNotFoundError,
+  AbiEventSignatureNotFoundError,
   AbiEventNotFoundError,
   AbiFunctionNotFoundError,
   AbiFunctionOutputsNotFoundError,