Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added docs for getProof, transactionSerializer, and getArgsFromTransactionDepositedOpaqueData. #173

Merged
merged 2 commits into from
Feb 6, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions site/docs/utilities/deposits/getL2HashFromL1DepositInfo.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
68 changes: 68 additions & 0 deletions site/docs/utilities/transactionHelpers/transactionSerializer.md
Original file line number Diff line number Diff line change
@@ -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.
125 changes: 125 additions & 0 deletions site/docs/utilities/withdrawals/getProof.md
Original file line number Diff line number Diff line change
@@ -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.
Loading