From 575fb7e3e0d89459a75d046bac1bf0f21f16222d Mon Sep 17 00:00:00 2001 From: Alex Wagner Date: Thu, 14 Dec 2023 22:55:02 -0500 Subject: [PATCH 1/2] Added docs for getProof, transactionSerializer, and getArgsFromTransactionDepositedOpaqueData. --- .../deposits/getL2HashFromL1DepositInfo.md | 10 ++ ...tArgsFromTransactionDepositedOpaqueData.md | 77 +++++++++++ .../transactionSerializer.md | 68 ++++++++++ site/docs/utilities/withdrawals/getProof.md | 125 ++++++++++++++++++ 4 files changed, 280 insertions(+) create mode 100644 site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md create mode 100644 site/docs/utilities/transactionHelpers/transactionSerializer.md create mode 100644 site/docs/utilities/withdrawals/getProof.md diff --git a/site/docs/utilities/deposits/getL2HashFromL1DepositInfo.md b/site/docs/utilities/deposits/getL2HashFromL1DepositInfo.md index fc7eeb1e..c7cb13f9 100644 --- a/site/docs/utilities/deposits/getL2HashFromL1DepositInfo.md +++ b/site/docs/utilities/deposits/getL2HashFromL1DepositInfo.md @@ -1,3 +1,13 @@ +--- +head: + - - meta + - property: og:title + content: getL2HashFromL1DepositInfo + - - meta + - name: description + content: Get the L2 transaction hash for a given L1 deposit transaction. +--- + # getL2HashFromL1DepositInfo Get the L2 transaction hash for a given L1 deposit transaction. diff --git a/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md b/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md new file mode 100644 index 00000000..dfa86f96 --- /dev/null +++ b/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md @@ -0,0 +1,77 @@ +--- +head: + - - meta + - property: og:title + content: getArgsFromTransactionDepositedOpaqueData + - - meta + - name: description + content: Parses the opaque data from the `TransactionDepositedEvent` event args, extracting and structuring key transaction data. +--- + +# getArgsFromTransactionDepositedOpaqueData + +Parses the opaque data from the `TransactionDepositedEvent` event args, returning structured transaction data. + +This function is a key component in the `getDepositTransaction` process, where it extracts and formats fields like `mint`, `value`, `gas`, `isCreation`, and `data` from the opaque data. These fields are then used to construct a `DepositTransaction` object. + +## Import + +```ts +import { parseOpaqueData } from './getArgsFromTransactionDepositedOpaqueData.js'; +``` + +## Usage + +```ts +import { parseOpaqueData } from './getArgsFromTransactionDepositedOpaqueData.js'; + +// ... within getDepositTransaction function +const parsedOpaqueData = parseOpaqueData(event.args.opaqueData); +// Use parsedOpaqueData to construct DepositTransaction +``` + +## Returns + +`ParsedTransactionDepositedOpaqueData` + +Returns an object containing structured transaction data with fields such as mint, value, gas, isCreation, and data. + +## Parameters + +`opaqueData` + +**Type:** Hex +**Description:** The opaque data from the TransactionDepositedEvent event args. + +## Types + +`ParsedTransactionDepositedOpaqueData` + +* **Type:** object +* **Properties:** + * **mint:** Hex - Potentially represents the value to be minted on L2. + * **value:** Hex - The transaction value. + * **gas:** Hex - The gas used for the transaction. + * **isCreation:** boolean - Indicates whether the transaction is a creation transaction. + * **data:** Hex - Additional transaction data. + +## Integration with Other Systems + +This function is commonly used in conjunction with other components handling Ethereum transactions, such as the `writeContractDeposit` and `getDepositTransaction` functions. It extracts standardized transaction fields that these downstream components expect. + +## Error Handling + +The function expects well-formed hexadecimal data. If the data is malformed or does not follow the expected format, the function may return incomplete or incorrect results. Users are advised to ensure data integrity before passing it to this function. + +## Performance Considerations + +`getArgsFromTransactionDepositedOpaqueData` is designed to efficiently process typical transaction data sizes. However, performance may vary with large or complex data sets. Regular performance monitoring is recommended for high-volume applications. + +## Security Considerations + +While the function is secure for standard use cases, it does not implement additional security checks on the input data. Users should be cautious with data from untrusted sources and consider implementing additional validation layers as necessary. + +## Notes + +* This utility is essential for interpreting Ethereum transaction data, especially for transactions involving deposit events. +* The isCreation field is specifically determined by a unique value in the opaque data, aligning with Ethereum's transaction structure. \ No newline at end of file diff --git a/site/docs/utilities/transactionHelpers/transactionSerializer.md b/site/docs/utilities/transactionHelpers/transactionSerializer.md new file mode 100644 index 00000000..de5e8554 --- /dev/null +++ b/site/docs/utilities/transactionHelpers/transactionSerializer.md @@ -0,0 +1,68 @@ +--- +head: + - - meta + - property: og:title + content: transactionSerializer + - - meta + - name: description + content: Add here. +--- + +# transactionSerializer + +Serializes a transaction compliant with Ethereum Improvement Proposal (EIP) 1559. + +This utility function takes transaction parameters and serializes them into a format compatible with EIP-1559, which introduced a new transaction type to Ethereum's fee market. It is essential for applications interacting with Ethereum's Layer 1 and Layer 2 solutions, particularly in scenarios where precise gas fee calculations and transaction structuring are required. + +## Import + +```ts +import { serializeEip1559Transaction } from './transactionSerializer.js'; +``` + +## Usage + +```ts +// Example usage in an Ethereum transaction +import { serializeEip1559Transaction } from './transactionSerializer.js'; +// Additional imports... + +const serializedTx = serializeEip1559Transaction({ + // Transaction parameters... +}); +// Use serializedTx for further processing... +``` + +## Parameters + +`options`: Combination of `EncodeFunctionDataParameters` and `TransactionSerializableEIP1559` (excluding `data`). + +**Type:** Object +**Details:** Contains all the necessary parameters to encode function data and serialize the transaction. + +## Returns + +`TransactionSerializedEIP1559` + +**Type:** Object +**Description:** The serialized transaction data, formatted according to EIP-1559 standards. + +## Function Details + +The function internally calls `encodeFunctionData` to encode the ABI and function parameters. It then calls `serializeTransaction`, incorporating the encoded data and specifying the transaction type as 'eip1559'. The result is a transaction object that adheres to the EIP-1559 structure. + +## Error Handling + +No explicit error handling is described in the provided code. Users should handle potential errors related to data encoding and serialization in their implementation. + +## Performance Considerations + +As with any serialization function, performance may vary based on the complexity and size of the input data. Regular monitoring is advised in high-volume or performance-critical applications. + +## Security Considerations + +The function processes sensitive transaction data. Ensure that input data is validated and secure, and consider additional security measures as needed in the broader application context. + +## Integration with Other Systems + +This utility is used in conjunction with other components for Ethereum transaction processing, such as `readContract` for contract interactions and `estimateL1GasUsed` for gas usage estimations. The serialized output can be passed to functions like sendTransaction to broadcast the transaction on-chain. \ No newline at end of file diff --git a/site/docs/utilities/withdrawals/getProof.md b/site/docs/utilities/withdrawals/getProof.md new file mode 100644 index 00000000..b76ba2a2 --- /dev/null +++ b/site/docs/utilities/withdrawals/getProof.md @@ -0,0 +1,125 @@ +--- +head: + - - meta + - property: og:title + content: getProof + - - meta + - name: description + content: Generates a proof of account state and storage for a specified Ethereum address at a given block. + +--- + +# getProof + +Generates a proof of account state and storage for a specified Ethereum address at a given block. + +This function is crucial for verifying the state of an Ethereum account, particularly in applications dealing with cross-chain operations, such as withdrawals from Layer 2 to Layer 1 networks. It fetches proofs for given storage keys of an account at a specific block. + +## Import + +```ts +import { getProof } from './getProof.js'; +``` + +## Usage + +```ts +// Example usage in fetching account proof +import { getProof } from './getProof.js'; +// Additional imports... + +const proof = await getProof(client, { + address: '0x...', + storageKeys: ['0x...'], + block: 'latest' // or a specific block number/hash +}); +// Use the proof for further processing... +``` + +## Parameters + +* `client`: An instance of PublicClient. Responsible for making the request to the Ethereum node. +* `GetProofParameters`: An object containing: + * `address`: The Ethereum address for which to get the proof. + * `storageKeys`: An array of storage keys (Hex) to fetch the storage proof. + * `block`: The block number (Hex or BigInt), tag ('latest', 'earliest', 'pending'), or hash at which to fetch the proof. + +## Returns + +`AccountProof`: An object containing: + +* `address`: The Ethereum address. +* `accountProof`: Array of hex strings forming the Merkle-Patricia proof of the account's existence and state. +* `balance`: Account's balance at the specified block. +* `nonce`: Account's nonce at the specified block. +* `storageHash`: Hash of the storage root. +* `storageProof`: Array of `StorageProof` objects for each requested storage key. + +## Examples + +### Retrieving Account Proof + +```ts +// Example demonstrating fetching account proof for a specific address +const proof = await getProof(client, { + address: '0x...', + storageKeys: ['0x...'], + block: 'latest' +}); +console.log(proof); +``` + +### Usage in Withdrawal Process + +```ts +// Example of using getProof in the context of proving a withdrawal +const proof = await getProof(client, { + address: opStackL2ChainContracts.l2ToL1MessagePasser.address, + storageKeys: [slot], + block: toHex(block.number), +}); +``` + +## Testing + +`getProof` has a dedicated test to ensure its functionality and correctness. The test checks if the utility can correctly retrieve proofs for a given Ethereum address, storage keys, and block number. + +### Test Overview + +* **Test Name:** 'correctly retrieves proof' +* **Purpose:** To verify that getProof correctly fetches the storage proof for specified storage keys of an Ethereum address at a given block. +* **Test Methodology:** + * A `PublicClient` is created with specific chain and transport settings. + * The `getProof` function is called with a predefined address, storage keys, and block number. + * The test asserts that the retrieved storage proof's value matches the expected result (`0x1`). + +### Example Test Case + + +```ts +import { createPublicClient, http, toHex } from 'viem'; +import { base } from 'viem/chains'; +import { expect, test } from 'vitest'; +import { getProof } from './getProof.js'; + +test('correctly retrieves proof', async () => { + const client = createPublicClient({ + chain: base, + transport: http(), + }); + + const result = await getProof(client, { + address: '0x4200000000000000000000000000000000000016', + storageKeys: ['0x4a932049252365b3eedbc5190e18949f2ec11f39d3bef2d259764799a1b27d99'], + block: toHex(3155269n), + }); + + expect(result.storageProof[0].value).toEqual('0x1'); +}); +``` +This test is crucial for ensuring the reliability of the getProof utility in real-world applications, particularly in scenarios requiring validation of blockchain state at a specific point in time. + +## Notes + +The function relies on the Ethereum node's support for the eth_getProof method. +It is used extensively in scenarios like validating withdrawal proofs from Layer 2 to Layer 1. From f433c1b0c7530d44aa94cbb36213ce8c2d5dc7b8 Mon Sep 17 00:00:00 2001 From: Alex Wagner Date: Wed, 3 Jan 2024 17:54:25 -0600 Subject: [PATCH 2/2] Made fixes based on comments in PR. --- ...tArgsFromTransactionDepositedOpaqueData.md | 39 +------ .../transactionSerializer.md | 26 +---- site/docs/utilities/withdrawals/getProof.md | 105 +++++------------- 3 files changed, 31 insertions(+), 139 deletions(-) diff --git a/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md b/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md index dfa86f96..78e1a4b0 100644 --- a/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md +++ b/site/docs/utilities/transactionHelpers/getArgsFromTransactionDepositedOpaqueData.md @@ -17,13 +17,13 @@ This function is a key component in the `getDepositTransaction` process, where i ## Import ```ts -import { parseOpaqueData } from './getArgsFromTransactionDepositedOpaqueData.js'; +import { parseOpaqueData } from './utils/getArgsFromTransactionDepositedOpaqueData.js'; ``` ## Usage ```ts -import { parseOpaqueData } from './getArgsFromTransactionDepositedOpaqueData.js'; +import { parseOpaqueData } from './utils/getArgsFromTransactionDepositedOpaqueData.js'; // ... within getDepositTransaction function const parsedOpaqueData = parseOpaqueData(event.args.opaqueData); @@ -41,37 +41,4 @@ Returns an object containing structured transaction data with fields such as min `opaqueData` **Type:** Hex -**Description:** The opaque data from the TransactionDepositedEvent event args. - -## Types - -`ParsedTransactionDepositedOpaqueData` - -* **Type:** object -* **Properties:** - * **mint:** Hex - Potentially represents the value to be minted on L2. - * **value:** Hex - The transaction value. - * **gas:** Hex - The gas used for the transaction. - * **isCreation:** boolean - Indicates whether the transaction is a creation transaction. - * **data:** Hex - Additional transaction data. - -## Integration with Other Systems - -This function is commonly used in conjunction with other components handling Ethereum transactions, such as the `writeContractDeposit` and `getDepositTransaction` functions. It extracts standardized transaction fields that these downstream components expect. - -## Error Handling - -The function expects well-formed hexadecimal data. If the data is malformed or does not follow the expected format, the function may return incomplete or incorrect results. Users are advised to ensure data integrity before passing it to this function. - -## Performance Considerations - -`getArgsFromTransactionDepositedOpaqueData` is designed to efficiently process typical transaction data sizes. However, performance may vary with large or complex data sets. Regular performance monitoring is recommended for high-volume applications. - -## Security Considerations - -While the function is secure for standard use cases, it does not implement additional security checks on the input data. Users should be cautious with data from untrusted sources and consider implementing additional validation layers as necessary. - -## Notes - -* This utility is essential for interpreting Ethereum transaction data, especially for transactions involving deposit events. -* The isCreation field is specifically determined by a unique value in the opaque data, aligning with Ethereum's transaction structure. \ No newline at end of file +**Description:** The opaque data from the TransactionDepositedEvent event args. \ No newline at end of file diff --git a/site/docs/utilities/transactionHelpers/transactionSerializer.md b/site/docs/utilities/transactionHelpers/transactionSerializer.md index de5e8554..83215481 100644 --- a/site/docs/utilities/transactionHelpers/transactionSerializer.md +++ b/site/docs/utilities/transactionHelpers/transactionSerializer.md @@ -17,14 +17,14 @@ This utility function takes transaction parameters and serializes them into a fo ## Import ```ts -import { serializeEip1559Transaction } from './transactionSerializer.js'; +import { serializeEip1559Transaction } from './utils/transactionSerializer.js'; ``` ## Usage ```ts // Example usage in an Ethereum transaction -import { serializeEip1559Transaction } from './transactionSerializer.js'; +import { serializeEip1559Transaction } from './utils/transactionSerializer.js'; // Additional imports... const serializedTx = serializeEip1559Transaction({ @@ -45,24 +45,4 @@ const serializedTx = serializeEip1559Transaction({ `TransactionSerializedEIP1559` **Type:** Object -**Description:** The serialized transaction data, formatted according to EIP-1559 standards. - -## Function Details - -The function internally calls `encodeFunctionData` to encode the ABI and function parameters. It then calls `serializeTransaction`, incorporating the encoded data and specifying the transaction type as 'eip1559'. The result is a transaction object that adheres to the EIP-1559 structure. - -## Error Handling - -No explicit error handling is described in the provided code. Users should handle potential errors related to data encoding and serialization in their implementation. - -## Performance Considerations - -As with any serialization function, performance may vary based on the complexity and size of the input data. Regular monitoring is advised in high-volume or performance-critical applications. - -## Security Considerations - -The function processes sensitive transaction data. Ensure that input data is validated and secure, and consider additional security measures as needed in the broader application context. - -## Integration with Other Systems - -This utility is used in conjunction with other components for Ethereum transaction processing, such as `readContract` for contract interactions and `estimateL1GasUsed` for gas usage estimations. The serialized output can be passed to functions like sendTransaction to broadcast the transaction on-chain. \ No newline at end of file +**Description:** The serialized transaction data, formatted according to EIP-1559 standards. \ No newline at end of file diff --git a/site/docs/utilities/withdrawals/getProof.md b/site/docs/utilities/withdrawals/getProof.md index b76ba2a2..36e29e9b 100644 --- a/site/docs/utilities/withdrawals/getProof.md +++ b/site/docs/utilities/withdrawals/getProof.md @@ -18,24 +18,38 @@ This function is crucial for verifying the state of an Ethereum account, particu ## Import ```ts -import { getProof } from './getProof.js'; +import { getProof } from './getProof.js' ``` ## Usage +This example, adapted from `getProof.test.js`, demonstrates fetching an account's state and storage proof for a specific Ethereum address at a given block. It illustrates a practical application of the `getProof` function. + ```ts -// Example usage in fetching account proof -import { getProof } from './getProof.js'; -// Additional imports... - -const proof = await getProof(client, { - address: '0x...', - storageKeys: ['0x...'], - block: 'latest' // or a specific block number/hash +import { createPublicClient, http, toHex } from 'viem'; +import { base } from 'viem/chains'; +import { getProof } from './getProof.js' + +// Setting up the client with base chain and HTTP transport +const client = createPublicClient({ + chain: base, + transport: http(), }); -// Use the proof for further processing... + +// Example usage of getProof to fetch account state and storage proof +const result = await getProof(client, { + address: '0x4200000000000000000000000000000000000016', // Ethereum address + storageKeys: [ + '0x4a932049252365b3eedbc5190e18949f2ec11f39d3bef2d259764799a1b27d99', // Storage key + ], + block: toHex(3155269n), // Block number in hexadecimal +}); + +// The result contains the storage proof for the specified address and block ``` +This approach not only provides a clear, practical example of how to use `getProof` but also shows the function in action in a scenario similar to what users might encounter in their own applications. + ## Parameters * `client`: An instance of PublicClient. Responsible for making the request to the Ethereum node. @@ -53,73 +67,4 @@ const proof = await getProof(client, { * `balance`: Account's balance at the specified block. * `nonce`: Account's nonce at the specified block. * `storageHash`: Hash of the storage root. -* `storageProof`: Array of `StorageProof` objects for each requested storage key. - -## Examples - -### Retrieving Account Proof - -```ts -// Example demonstrating fetching account proof for a specific address -const proof = await getProof(client, { - address: '0x...', - storageKeys: ['0x...'], - block: 'latest' -}); -console.log(proof); -``` - -### Usage in Withdrawal Process - -```ts -// Example of using getProof in the context of proving a withdrawal -const proof = await getProof(client, { - address: opStackL2ChainContracts.l2ToL1MessagePasser.address, - storageKeys: [slot], - block: toHex(block.number), -}); -``` - -## Testing - -`getProof` has a dedicated test to ensure its functionality and correctness. The test checks if the utility can correctly retrieve proofs for a given Ethereum address, storage keys, and block number. - -### Test Overview - -* **Test Name:** 'correctly retrieves proof' -* **Purpose:** To verify that getProof correctly fetches the storage proof for specified storage keys of an Ethereum address at a given block. -* **Test Methodology:** - * A `PublicClient` is created with specific chain and transport settings. - * The `getProof` function is called with a predefined address, storage keys, and block number. - * The test asserts that the retrieved storage proof's value matches the expected result (`0x1`). - -### Example Test Case - - -```ts -import { createPublicClient, http, toHex } from 'viem'; -import { base } from 'viem/chains'; -import { expect, test } from 'vitest'; -import { getProof } from './getProof.js'; - -test('correctly retrieves proof', async () => { - const client = createPublicClient({ - chain: base, - transport: http(), - }); - - const result = await getProof(client, { - address: '0x4200000000000000000000000000000000000016', - storageKeys: ['0x4a932049252365b3eedbc5190e18949f2ec11f39d3bef2d259764799a1b27d99'], - block: toHex(3155269n), - }); - - expect(result.storageProof[0].value).toEqual('0x1'); -}); -``` -This test is crucial for ensuring the reliability of the getProof utility in real-world applications, particularly in scenarios requiring validation of blockchain state at a specific point in time. - -## Notes - -The function relies on the Ethereum node's support for the eth_getProof method. -It is used extensively in scenarios like validating withdrawal proofs from Layer 2 to Layer 1. +* `storageProof`: Array of `StorageProof` objects for each requested storage key. \ No newline at end of file