docs: update README.md and CONTRIBUTING.md

[skip ci]

.env.example

@@ -1,5 +1,5 @@
-# This is an .env.example file. You must rename it to .env and fill in the values.
-# An Ethereum RPC node is required to run the tests. You must use an Infura RPC node or a local node:
-# Create Infura API key: https://docs.infura.io/infura/getting-started#2.-create-an-api-key
-# Run a local node: https://ethereum.org/en/run-a-node/
-ETH_MAINNET_RPC="https://mainnet.infura.io/v3/<your-api-key>"
+# This is an `.env.example` file. You must rename it to `.env` and fill in the values.
+# An Ethereum RPC node is required to run the tests. You can use an Alchemy RPC node or a local node:
+# Create an Alchemy API key: https://docs.alchemy.com/docs/alchemy-quickstart-guide
+# Or even better, run a local node: https://ethereum.org/en/run-a-node and use it's RPC URL.
+ETH_MAINNET_RPC="https://eth-mainnet.g.alchemy.com/v2/<your-api-key>"

.github/.CONTRIBUTING.md

@@ -6,25 +6,27 @@ Thank you for your interest in contributing to our project! Before you submit a
 
 First, [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone the repository onto your local machine. Once you have your local copy of the repository, you can commence with development. This typically involves installing the required dependencies and executing the tests.
 
-### Install dependencies
+### Install Dependencies
 
 After cloning the repository, navigate to its root directory and run the following command to install the necessary dependencies:
 
 ```
 npm install
 ```
 
-### Testing
+### Run the Tests
 
-The tests require a URL to an Ethereum RPC node. The simplest way to get started is by [creating](https://docs.infura.io/infura/getting-started#2.-create-an-api-key) an API key for an RPC node on Infura. Once created, you can follow the instructions found in the `.env.example` file. Run the tests by running the following command:
+Features and bug fixes must be accompanied by tests, as this library aims to maintain 100% test coverage 🧪. Focus on testing only the public interfaces; avoid testing implementation details. To run the tests, you'll need a URL to an Ethereum RPC node. The easiest way to obtain one is by [creating](https://docs.alchemy.com/docs/alchemy-quickstart-guide) an API key through Alchemy. After obtaining the key, follow the instructions in the `.env.example` file to get started.
+
+Run the tests by running the following command:
 
 ```
 npm test
 ```
 
 Once you have made your changes and verified they work correctly, you can submit a [pull request from your forked repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
 
-## Pull requests
+## Pull Requests
 
 Before proposing changes, please open an [issue](https://github.com/0xProject/0x-parser/issues/new) or [discussion](https://github.com/0xProject/0x-parser/discussions/new/choose) for collaborative decision-making on solutions prior to submitting a pull request. This enhances the effectiveness of your contributions and promotes collective input.
 
@@ -40,7 +42,7 @@ Before proposing changes, please open an [issue](https://github.com/0xProject/0x
 
 ### Dependabot
 
-This repository employs [Dependabot](https://docs.github.com/en/code-security/dependabot) to [secure](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates) and [update](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#about-version-updates-for-dependencies) project dependencies by automatically initiating pull requests for package upgrades. The duty of project maintainers is to review, test, approve, and merge these Dependabot-generated pull requests.
+This repository employs [Dependabot 🤖](https://docs.github.com/en/code-security/dependabot) to [secure](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates) and [update](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#about-version-updates-for-dependencies) project dependencies by automatically initiating pull requests for package upgrades. The duty of project maintainers is to review, test, approve, and merge these Dependabot-generated pull requests.
 
 ## Release
 

README.md

@@ -1,6 +1,7 @@
 # 0x-parser
 
-[![npm version](https://img.shields.io/npm/v/@0x/0x-parser.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/@0x/0x-parser)
+[![npm version](https://img.shields.io/npm/v/@0x/0x-parser.svg?logo=npm)](https://www.npmjs.com/package/@0x/0x-parser)
+[![minified size](https://img.shields.io/bundlephobia/min/@0x/0x-parser)](https://bundlephobia.com/package/@0x/0x-parser)
 [![codecov](https://codecov.io/gh/0xproject/0x-parser/branch/main/graph/badge.svg?token=OnNsoc2OrF)](https://codecov.io/gh/0xproject/0x-parser)
 [![build and test](https://github.com/0xproject/0x-parser/actions/workflows/test.yml/badge.svg)](https://github.com/0xproject/0x-parser/actions/workflows/test.yml)
 [![Medium](https://img.shields.io/badge/Medium-12100E?style=for-the-badge&logo=medium&logoColor=white&style=flat-square)](https://medium.com/@henballs/0x-parser-parsing-dex-transactions-9f9a6579d489)
@@ -13,9 +14,11 @@
 
 ## Overview
 
-This library is designed for [0x integrators](https://0x.org/docs/introduction/introduction-to-0x), and it simplifies the complex task of parsing [0x transactions](https://etherscan.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff) into a format that is both user-friendly and easy to understand. 
+This library is designed for [0x](https://0x.org/docs/introduction/introduction-to-0x) integrators, simplifying the complex task of parsing [0x transactions](https://etherscan.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff) into a format that is both user-friendly and easy to understand. When swapping tokens, one of the challenges is that the trade can experience slippage through Automated Market Makers ([AMMs](https://0x.org/post/what-is-an-automated-market-maker-amm)). This makes the final swap amounts difficult to predict prior to executing the trade. However, this library overcomes that challenge by parsing the transaction receipt and event logs to accurately identify the final swap amounts. 
 
-One of the challenges when swapping tokens is that the trade can experience [slippage](https://0x.org/post/what-is-slippage) through [Automated Market Makers](<[AMMs](https://0x.org/post/what-is-an-automated-market-maker-amm)>) (AMMs), making the final swap amounts difficult to predict prior to executing the trade. However, this library overcomes that challenge by parsing the transaction receipt and event logs to accurately identify the final swap amounts. Try the demo [here](https://0x-parser-demo.vercel.app).
+### Demo
+
+Try out the parser in a [live code environment](https://codesandbox.io/p/sandbox/0x-parser-node-js-demo-3wpfhc?file=/index.js:13,1) directly in your browser 🌐. You can also experience it in action through the [demo UI app](https://0x-parser-demo.vercel.app), which is built with 0x-parser.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/hzhu/yo/main/react-demo.png" alt="Screenshot of demo app using 0x-parser" width="650"/>
@@ -25,7 +28,7 @@ One of the challenges when swapping tokens is that the trade can experience [sli
 
 ### Step 1: Install Peer Dependencies
 
-First, make sure you have the required peer dependency [viem](https://viem.sh/) installed. If you haven't installed it yet, you can do so with the following command:
+First, make sure you have the required peer dependency [viem](https://viem.sh) installed. If you haven't installed it yet, you can do so with the following command:
 
 ```
 npm install viem
@@ -49,23 +52,28 @@ async function main() {
     "https://raw.githubusercontent.com/0xProject/protocol/development/packages/contract-artifacts/artifacts/IZeroEx.json"
   );
 
-  const IZeroEx = await response.json();
+  const data = await response.json();
+  const exchangeProxyAbi = data.compilerOutput.abi;
+
+  // You can pass any transaction hash from 0x Exchange Proxy:
+  // https://etherscan.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff
+  const transactionHash = "0xd8637124d650268ae7680781809800e103a3a2bee9fec56083028fea6d98140b";
 
-  const data = await parseSwap({
+  const swap = await parseSwap({
+    transactionHash,
+    exchangeProxyAbi,
     rpcUrl: "https://eth.llamarpc.com",
-    exchangeProxyAbi: IZeroEx.compilerOutput.abi,
-    transactionHash: "0xd8637124d650268ae7680781809800e103a3a2bee9fec56083028fea6d98140b",
   });
 
-  console.log(data);
+  console.log(swap); // Logs the swap details in the console.
 }
 
 main();
 ```
 
-## Examples
+## Development
 
-This repository includes examples you can execute locally. Navigate to the `/examples` directory for additional `README` information on how to run the demos locally. You can also explore a live demo of 0x-parser [here](https://0x-parser-demo.vercel.app/).
+This repository contains example code that you can run locally, which is useful for the development process. The code can be found in `/examples/web/index.html` and you can run the code by runnng `npm run web:example`.
 
 ## Contributing
 

src/index.ts

@@ -56,8 +56,8 @@ export async function parseSwap({
     : undefined;
 
   // The `to` property is null only in the case of a contract creation transaction,
-  // which never occurs in the context of the 0x-parser. Use TypeScript's
-  // non-null assertion operator to indicate that the to property will always be present.
+  // which never occurs in the context of the 0x-parser. Use TypeScript's non-null
+  // assertion operator to indicate that the `to` property will always be present.
   const to = getAddress(transaction.to!);
 
   const isToExchangeProxy = to === getAddress(exchangeProxy);

src/utils/index.ts

@@ -29,12 +29,15 @@ export async function transferLogs({
   publicClient,
   transactionReceipt,
 }: EnrichLogsArgs): Promise<EnrichedLog[]> {
+  // Extract logs from transaction receipt.
   const { logs } = transactionReceipt;
 
+  // Filter logs for the "Transfer" event signature.
   const transferLogsAddresses = logs
     .filter((log) => log.topics[0] === EVENT_SIGNATURES.Transfer)
     .map((log) => ({ ...log, address: getAddress(log.address) }));
 
+  // Prepare contract queries for symbols and decimals.
   const contracts = [
     ...transferLogsAddresses.map((log) => ({
       abi: minimalERC20Abi,
@@ -48,10 +51,15 @@ export async function transferLogs({
     })),
   ];
 
+  // Execute multicall to fetch symbols and decimals.
   const results = await publicClient.multicall({ contracts });
 
+  // There are two sets of results (symbol and decimals), each of the same length.
+  // They are concatenated, so the midpoint separates them.
   const midpoint = Math.floor(results.length / 2);
 
+  // Enrich original logs with additional data (symbol, decimals) and 
+  // format the transferred amount to a human-readable format.
   const enrichedLogs = transferLogsAddresses
     .map((log, index) => {
       const symbol = results[index].result as string;