diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs index 321461a..ce01eb9 100644 --- a/apps/docs/astro.config.mjs +++ b/apps/docs/astro.config.mjs @@ -16,6 +16,13 @@ export default defineConfig({ github: 'https://github.com/3loop/loop-decoder', twitter: 'https://x.com/3loop_io', }, + editLink: { + baseUrl: 'https://github.com/3loop/loop-decoder/edit/main/apps/docs/', + }, + components: { + Header: './src/components/Header.astro', + }, + lastUpdated: true, sidebar: [ { label: 'Welcome', diff --git a/apps/docs/src/components/Header.astro b/apps/docs/src/components/Header.astro new file mode 100644 index 0000000..740639d --- /dev/null +++ b/apps/docs/src/components/Header.astro @@ -0,0 +1,129 @@ +--- +import config from 'virtual:starlight/user-config'; + +import LanguageSelect from 'virtual:starlight/components/LanguageSelect'; +import Search from 'virtual:starlight/components/Search'; +import SiteTitle from 'virtual:starlight/components/SiteTitle'; +import SocialIcons from 'virtual:starlight/components/SocialIcons'; +import ThemeSelect from 'virtual:starlight/components/ThemeSelect'; + + +/** + * Render the `Search` component if Pagefind is enabled or the default search component has been overridden. + */ +const isHomePage = Astro.url.pathname === '/'; +const shouldRenderSearch = + !isHomePage && + (config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro'); +--- + +
+
+ +
+
+ {shouldRenderSearch && + } +
+
+
+ + Playground + + + + + + +
+ + + + + +
+
+ + diff --git a/apps/docs/src/content/docs/guides/decode-transaction.mdx b/apps/docs/src/content/docs/guides/decode-transaction.mdx index 98ec9d6..105dd93 100644 --- a/apps/docs/src/content/docs/guides/decode-transaction.mdx +++ b/apps/docs/src/content/docs/guides/decode-transaction.mdx @@ -59,7 +59,7 @@ To create a custom ABI Data Store, implement the `VanillaAbiStore` interface: -#### Example: an ABI data store with Etherscan and 4byte strategies and in-memory cache +#### Example: an ABI data store with Etherscan and 4byte data loaders and in-memory cache @@ -78,7 +78,7 @@ To create a custom Contract Metadata Store, implement the `VanillaContractMetaSt -#### Example: a Contract Metadata Store with ERC20 strategy and in-memory cache +#### Example: a Contract Metadata Store with ERC20 data loader and in-memory cache @@ -121,7 +121,7 @@ async function main() { main() ``` -Expected output: +Check the full expected output in our [Playground](https://loop-decoder-web.vercel.app/decode/1/0xc0bd04d7e94542e58709f51879f64946ff4a744e1c37f5f920cea3d478e115d7) or see it below: ```json { @@ -161,3 +161,7 @@ Expected output: // ... } ``` + +## Try it live + +Try decoding the above or any other transactions in the our playground [here](https://loop-decoder-web.vercel.app/decode). diff --git a/apps/docs/src/content/docs/guides/decode-method.mdx b/apps/docs/src/content/docs/reference/decode-method.mdx similarity index 70% rename from apps/docs/src/content/docs/guides/decode-method.mdx rename to apps/docs/src/content/docs/reference/decode-method.mdx index f8337ec..973e576 100644 --- a/apps/docs/src/content/docs/guides/decode-method.mdx +++ b/apps/docs/src/content/docs/reference/decode-method.mdx @@ -1,85 +1,26 @@ --- -title: How to decode a Calldata -description: On this page you will provide a step-by-step guide on how to decode and interpret a Calldata using Loop Decoder. +title: Decoding Calldata +description: On this page you will provide a guide on how to decode and interpret a Calldata using Loop Decoder. sidebar: order: 2 --- -import { Content as MemoryAbiLoader } from '../../components/memory-abi-loader.md' -import { Content as MemoryContractLoader } from '../../components/memory-contract-loader.md' -import { Content as RpcProvider } from '../../components/rpc-provider.md' +Loop Decoder provides a `decodeCalldata` method that decodes a transaction calldata. This method handles special cases: -In this guide, we will go through the process of decoding EVM Calldata using Loop Decoder. As an example we will decode a Calldata for Gnosis Safe Multisend transaction that has deep nested calls. +- Gnosis Safe Multisend or Multy Transfer transactions +- Multicalls and deeply nested calls +- Proxy contract resolutions -We recomend to copy all snipepts to a typescript project and run it at the end of this guide, or or you can copy the whole example from this file: [Full Example Code](https://stackblitz.com/~/github.com/3loop/loop-decoder/tree/main/sandbox/quick-start). Do not forget to replace the placeholder `YourApiKeyToken` with your own free Etherscan API key. +### Setting up Loop Decoder -## Prerequisites +To use `decodeCalldata` method, you need to setup a `TransactionDecoder` instance with the necessary data stores. For setup instructions, refer to: -### Create a new project +- Setup with default in-memory data stores (the quickest way): [Getting Started](/welcome/getting-started/) +- Setup with customizable data stores: [How To Decode Transaction (detailed)](/guides/decode-transaction/) -Optionally, you can create a new project to follow along, or skip to [Required packages](#required-packages). +### Decoding Calldata -1. Install Bun: - First, make sure you have Bun installed on your system. If you haven't installed it yet, you can do so using npm: - -```bash -npm install -g bun -``` - -1. Generate and initialize a new project: - -```bash -mkdir example-decode && cd example-decode -bun init -``` - -### Required packages - -For this guide, you will need to have the following packages installed: - -```bash -bun install @3loop/transaction-decoder viem -``` - -## Data Sources - -Loop Decoder requires some data sources to be able to decode transactions. We will need an RPC provider, a data source to fetch Contracts ABIs and a data source to fetch contract meta-information, such as token name, decimals, symbol, etc. - -### RPC Provider - -We will start by creating a function which will return an object with PublicClient based on the chain ID. For the sake of this example, we will only support mainnet. - - - -### ABI loader - -To avoid making unecessary calls to third-party APIs, Loop Decoder uses an API that allows cache. For this example, we will keep it simple and use an in-memory cache. We will also use some strategies to download contract ABIs from Etherscan and 4byte.directory. You can find more information about the strategies in the [Strategies](/reference/data-loaders/) reference. - -Create a cache for contract ABI and add your free Etherscan API key instead of the placeholder `YourApiKeyToken`: - - - -### Contract Metadata loader - -Create an in-memory cache for contract meta-information. Using `ERC20RPCStrategyResolver` we will automatically retrieve token meta information from the contract such as token name, decimals, symbol, etc. - - - -Finally, you can create a new instance of the LoopDecoder class: - -```ts -import { TransactionDecoder } from '@3loop/transaction-decoder' - -const decoder = new TransactionDecoder({ - getPublicClient: getPublicClient, - abiStore: abiStore, - contractMetaStore: contractMetaStore, -}) -``` - -## Decoding a Calldata - -Now that we have all the necessary components, we can start decoding a Calldata. For this example, we will use the following Calldata: +In the example below, we will decode a transaction calldata for for Gnosis Safe Multisend transaction that has deep nested calls. ```ts async function main() { @@ -99,12 +40,6 @@ async function main() { main() ``` -Run the script: - -```bash -bun run index.ts -``` - Expected output: ```json @@ -140,15 +75,9 @@ Expected output: "type": "address", "value": "0x2D8880BcC0618DBCC5d516640015A69e28fdC406" }, - { - "name": "value", - "type": "uint256", - "value": "0" - }, - { - "name": "dataLength", - "type": "uint256", - "value": "1544" - }, //... ``` + +### Try it live + +Try decoding the above or any other calldata in our [Playground](https://loop-decoder-web.vercel.app/calldata). diff --git a/apps/docs/src/content/docs/welcome/getting-started.mdx b/apps/docs/src/content/docs/welcome/getting-started.mdx index a5fdb9c..d61d4c1 100644 --- a/apps/docs/src/content/docs/welcome/getting-started.mdx +++ b/apps/docs/src/content/docs/welcome/getting-started.mdx @@ -21,7 +21,7 @@ Loop Decoder requires three components: 2. ABI Data Store 3. Contract Metadata Store -This guide demonstrates setup using the default in-memory implementations for Data Stores. For custom storage solutions, see our [How To Decode Transaction](/guides/decode-transaction/) guide. +This guide demonstrates setup using the default in-memory implementations for Data Stores (see and run [Full Example Code](https://stackblitz.com/github/3loop/loop-decoder/tree/main/sandbox/quick-start?file=src/decoder.ts) from this page). For custom storage solutions, see our [How To Decode Transaction](/guides/decode-transaction/) guide. ### 1. Set up your RPC Provider diff --git a/apps/docs/src/content/docs/welcome/overview.md b/apps/docs/src/content/docs/welcome/overview.md index 0aa90fd..b0bcf29 100644 --- a/apps/docs/src/content/docs/welcome/overview.md +++ b/apps/docs/src/content/docs/welcome/overview.md @@ -9,7 +9,7 @@ Loop Decoder is a TypeScript library with minimal dependencies that transforms b - Work in any JavaScript environment - Minimal external dependencies - you only need an RPC; everything else can be fetched from your own storage. -- Highly customizable - we don't force you to use a specific API or storage; instead, we provide data loaders. +- Highly customizable - we don't force you to use a specific API or storage; instead, we provide composable and customizable modules. ![Loop Decoder architecture](../../../assets/diagram.png) @@ -30,7 +30,11 @@ The minimal configuration for the Transaction Decoder requires an RPC URL, ABIs, ### Transaction Interpreter -Transaction Interpretation allows you to understand what really happened in any transaction. In Loop Decoder, this is a JavaScript function that takes a Decoded Transaction and selects the most important fields and parameters based on the type of contract interacted with. The goal is to abstract away blockchain and smart contract nuances, producing an object understandable for both technical and non-technical users. +Transaction Interpretation allows you to understand what really happened in any transaction. In Loop Decoder, this is a JavaScript function that takes a Decoded Transaction and selects the most important fields and parameters based on the type of contract interacted with. + +:::caution +The Transaction Interpreter is still under development and breaking changes are expected. +::: For example, the interpretation can construct a one-line description of the transaction: