Skip to content

Commit

Permalink
feat: add Transaction filtering info (#134)
Browse files Browse the repository at this point in the history
<!--

Thank you for contributing to the ZKsync Docs!

Before submitting the PR, please make sure you do the following:

- Update your PR title to follow [Conventional
Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- Read the [Contributing
Guide](https://github.com/matter-labs/zksync-docs/blob/main/CONTRIBUTING.md).
- Understand our [Code of
Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md)
- Please delete any unused parts of the template when submitting your PR

-->

# Description

Add the Transaction Filtering documentation

## Additional context

Add a new block to the transaction lifecycle doc that explains the
possible options to filter the transactions coming from either L1
contracts or API.
  • Loading branch information
dimazhornyk authored Jun 17, 2024
1 parent 9727362 commit f395ed3
Showing 1 changed file with 38 additions and 0 deletions.
38 changes: 38 additions & 0 deletions content/10.zk-stack/10.components/110.transaction-filtering.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: Transaction filtering
description: Learn how to filter transactions on the ZK chain, including L1→L2 and L2 transactions.
---

The ZK Chain operators can filter both the transactions initiated from L1 and the ones submitted via API directly to L2.

## L1->L2 Transactions
To filter L1→L2 transactions coming through the Diamond proxy, operators shall:

1. Implement & deploy the `TransactionFilterer` contract which implement the
[`ITransactionFilterer`](https://github.com/matter-labs/era-contracts/blob/dev/l1-contracts/contracts/state-transition/chain-interfaces/ITransactionFilterer.sol#L8)
2. Have the `TransactionFilterer` address set in the state transition
[storage](https://github.com/matter-labs/era-contracts/blob/dev/l1-contracts/contracts/state-transition/chain-deps/ZkSyncHyperchainStorage.sol)
(by using [this function](https://github.com/matter-labs/era-contracts/blob/dev/l1-contracts/contracts/state-transition/chain-deps/facets/Admin.sol#L95)).

If the filterer exists, it will be called by the
[Mailbox facet](https://github.com/matter-labs/era-contracts/blob/994897b14eb1d8e77c809da2db3379e7b58125b5/l1-contracts/contracts/state-transition/chain-deps/facets/Mailbox.sol#L239)
with the tx details, and will return whether the transaction can be executed.
To disable L1→L2 filtering, the same function that registers the filtered to the storage can be used with `0x0` address.

## L2 Transactions

To filter the transactions sent via the API, operators shall include filtering logic before txs get to the mempool.

To do this, an alternative [`TxSinkLayer`](https://github.com/matter-labs/zksync-era/blob/main/core/node/node_framework/src/implementations/layers/web3_api/tx_sink.rs)
must be implemented and used by the `node framework` by modifying the code
[here](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/node_builder.rs#L230).
For reference,

- See [Node Framework example](https://github.com/matter-labs/zksync-era/blob/main/core/node/node_framework/examples/main_node.rs#L416)
- See [example implementation](https://github.com/matter-labs/zksync-era/pull/1782)

#### Note on Withdrawals

Imagine a case where a user deposited funds and then was added to the denylist or removed from the allowlist.
In that scenario, the user may have their funds locked on the L2 or potentially even in a contract on the L2.
Please think about handling such cases and ensuring that the user can still withdraw their funds.

0 comments on commit f395ed3

Please sign in to comment.