From aa965992956d710d0fa350b048e8c3484f4eaca6 Mon Sep 17 00:00:00 2001 From: hzhu Date: Sun, 3 Sep 2023 17:06:20 -0700 Subject: [PATCH] docs: update README.md and CONTRIBUTING.md [skip ci] --- .env.example | 10 +++++----- .github/.CONTRIBUTING.md | 12 +++++++----- README.md | 30 +++++++++++++++++++----------- src/index.ts | 4 ++-- src/utils/index.ts | 8 ++++++++ 5 files changed, 41 insertions(+), 23 deletions(-) diff --git a/.env.example b/.env.example index d72ceb2..1790ea5 100644 --- a/.env.example +++ b/.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/" +# 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/" diff --git a/.github/.CONTRIBUTING.md b/.github/.CONTRIBUTING.md index 5b1fc85..5593af6 100644 --- a/.github/.CONTRIBUTING.md +++ b/.github/.CONTRIBUTING.md @@ -6,7 +6,7 @@ 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: @@ -14,9 +14,11 @@ After cloning the repository, navigate to its root directory and run the followi 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 @@ -24,7 +26,7 @@ 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 diff --git a/README.md b/README.md index f94c452..76c104a 100644 --- a/README.md +++ b/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.

Screenshot of demo app using 0x-parser @@ -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 diff --git a/src/index.ts b/src/index.ts index c032a2f..49fb373 100644 --- a/src/index.ts +++ b/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); diff --git a/src/utils/index.ts b/src/utils/index.ts index 3e3b6e2..7e5b4d0 100644 --- a/src/utils/index.ts +++ b/src/utils/index.ts @@ -29,12 +29,15 @@ export async function transferLogs({ publicClient, transactionReceipt, }: EnrichLogsArgs): Promise { + // 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;