From bfcff26883172babf04e991611f84830cd355edc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 23 Apr 2026 11:22:09 -0700 Subject: [PATCH 01/15] add stub arbos60 upgrade notice --- docs/notices/arbos60-upgrade-notice.mdx | 8 ++++++++ sidebars.js | 5 +++++ 2 files changed, 13 insertions(+) create mode 100644 docs/notices/arbos60-upgrade-notice.mdx diff --git a/docs/notices/arbos60-upgrade-notice.mdx b/docs/notices/arbos60-upgrade-notice.mdx new file mode 100644 index 0000000000..4ccc25c70d --- /dev/null +++ b/docs/notices/arbos60-upgrade-notice.mdx @@ -0,0 +1,8 @@ +--- +title: 'Upgrade notice for ArbOS 60' +description: Upgrade notices for ArbOS 60 activation on Arbitrum One, Arbitrum Nova, and Arbitrum Spolia +user_story: As an Arbitrum node operator, I want to keep my nodes in sync with Arbitrum One, Arbitrum Nova, and Arbitrum Sepolia after the ArbOS 60 activation. +content_type: notice +--- + +This is a stub article for the Arbos60 upgrade notice diff --git a/sidebars.js b/sidebars.js index 4beb53ec29..bc4cc21172 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1922,6 +1922,11 @@ const sidebars = { // Notices sidebar noticeSidebar: [ + { + type: 'doc', + id: 'notices/arbos60-upgrade-notice', + label: 'Upgrade notice for ArbOS 60', + }, { type: 'doc', id: 'notices/arbos51-upgrade-notice', From 8b46e49dbe67338559d45f1b915ed76b345764d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 23 Apr 2026 17:44:24 -0700 Subject: [PATCH 02/15] add compliance filtering chain-owner guide (TW-739) Ports content from PR #3131 with light structural cleanup: - heading hierarchy (## / ###) - deployment-considerations as pipe table - synchronization pipeline and burn-allowance constraints as bullets Targets the Arbos60 staging branch. --- .../advanced/compliance-filtering.mdx | 103 ++++++++++++++++++ sidebars.js | 5 + 2 files changed, 108 insertions(+) create mode 100644 docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx new file mode 100644 index 0000000000..818e383af0 --- /dev/null +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -0,0 +1,103 @@ +--- +title: 'Compliance Filtering' +description: '' +content_type: how-to +author: gmehta2 +sme: gmehta2 +target_audience: 'Developers who want to configure compliance rules on their chain' +--- + +New, optional components can be added to the Sequencer and State Transition Function (STF) to enable protocol-level transaction filtering for regulatory or compliance purposes, at the discretion of the chain owner. +The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox. + +## Rationale + +The Arbitrum platform must evolve alongside the needs of a new wave of teams looking to come onchain - specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. +This feature represents the first of many to ensure that the Arbitrum platform can serve the needs of enterprises and institutions looking to tap into internet-scale, blockchain technology to increase margins, reduce risk, and improve transparency across their businesses. + +While this feature is not intended or proposed to be used by Arbitrum One, its inclusion in ArbOS 60 Elara is intended to simplify the codebase and canonicalize this feature in the node software. +This feature is instead intended to be used by Arbitrum chains who have compliance and regulatory obligations to restrict on-chain activity from sanctioned entities or actors. + +## How it works + +Compliance Filtering operates across two layers: the Sequencer and the State Transition Function (STF). Together, these layers ensure that restricted activity is blocked regardless of how a transaction enters the system. + +### Restricted address list + +The chain owner configures an external compliance provider (e.g., TRM Labs, Chainalysis) to define which addresses are restricted. This produces a restricted address list, which is: + +1. Stored in-memory on any node performing compliance screening +2. Encoded as salted hashes in the form `sha256(salt || address)` to protect address privacy +3. Refreshed periodically via a synchronization pipeline + +When evaluating a transaction, the compliance engine hashes all relevant addresses and checks them against this list. + +### Sequencer-level filtering + +The Compliance Rules Engine runs inside the sequencer and simulates each transaction before it is sequenced. If a transaction violates any compliance rule, it is rejected at the sequencer level and never included in a block. +This is the primary enforcement layer and handles the vast majority of cases. + +### Compliance rules + +Specific rules can be defined by the chain owner for any address found on the restricted list. +These rules apply whether the transfer is direct or uses a delegated approval mechanism. + +### Delayed Inbox filtering (STF level) + +Transactions submitted via the Delayed Inbox cannot be filtered at the sequencer layer alone, since they are eligible for force inclusion after a timeout window. +To handle this, Compliance Filtering introduces two additional components: + +#### Transaction Guardian Precompile + +A new precompile allows authorized entities (e.g., the sequencer) to register the hash of a restricted transaction on-chain before it is force-included. When the STF processes a transaction from the delayed inbox, it checks whether that transaction's hash has been registered in the guardian. +If so, the transaction is forcibly failed on inclusion, consuming any gas attached to prevent spam. + +#### Delayed Inbox Sentinel + +The sentinel is responsible for monitoring the delayed inbox for restricted transactions. When a restricted transaction is detected, the sentinel: + +1. Submits the transaction's hash to the Transaction Guardian Precompile +2. Ensures this occurs before the force inclusion window closes +3. Allows the sequencer to then process the transaction, which will fail at the STF level as expected + +This ensures that even transactions submitted through the L1 → L2 messaging path are subject to compliance enforcement. + +### Exception rules (burn allowance) + +Certain DeFi protocols (e.g., lending protocols like Aave, Morpho) require the ability to liquidate or burn token balances associated with restricted accounts in order to maintain solvency and prevent exploits. +To support this, a narrow exception is available: +ERC-20, ERC-721, and ERC-1155 transfers where the `to` field of the Transfer event is the zero address (`0x0`) (a burn operation) are permitted even if the `from` address is restricted. + +Important constraints: + +- If a transaction includes any other compliance violation in addition to a burn, the entire transaction still fails. +- A restricted address cannot initiate a burn themselves — their `tx.origin` is blocked at the sequencer level regardless. + +This design allows third-party liquidators and protocol contracts (e.g., Paxos, Aave) to burn sanctioned balances while preventing the sanctioned address from taking any action on the chain. + +### Synchronization pipeline + +The restricted address list is distributed to sequencer and prechecker nodes via a cloud-based pipeline: + +- The compliance provider periodically publishes a new hash list to a designated S3 bucket. +- An SNS notification triggers ingestion into the chain operator's own S3 bucket. +- Nodes subscribe to updates and load the new list into memory, fully replacing the prior list once the new one is validated and complete. + +Nodes are expected to always have a valid list in memory. On startup or restart, a node will fetch the most recent list before beginning to sequence or precheck transactions. + +## Deployment considerations + +| Component | Availability | Notes | +| --- | --- | --- | +| Sequencer-level filtering | ArbOS 60 Elara | Opcode and event filtering | +| Transaction Guardian Precompile | ArbOS 60 Elara | Required for Delayed Inbox enforcement | +| Delayed Inbox Sentinel (STF) | ArbOS 60 Elara | Requires audit; must be activated at deployment | +| Burn exception rules | ArbOS 60 Elara | Covers Aave, Paxos, and similar protocols | + +Compliance Filtering is disabled by default. Chain owners must explicitly configure and enable each component. Activation after chain deployment may require an ArbOS upgrade. + +## Security considerations + +- **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. +- **L1 bridge deposits:** If a restricted address deposits ETH via `depositEth()` on L1, the ETH enters the L1 bridge contract before any L2 filtering occurs. If the corresponding L2 credit is dropped, the ETH may become locked in the bridge with no corresponding L2 asset. Chain owners should account for this in their compliance design and user communication strategy. +- **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned accounts. diff --git a/sidebars.js b/sidebars.js index bc4cc21172..0e764ba59c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -530,6 +530,11 @@ const sidebars = { id: 'launch-arbitrum-chain/configure-your-chain/advanced/da-api-integration-guide', label: `DA API integration guide`, }, + { + type: 'doc', + id: 'launch-arbitrum-chain/configure-your-chain/advanced/compliance-filtering', + label: 'Compliance filtering', + }, ], }, ], From 242ccefcf56dfe4553cc8096ed30091f478e62ac Mon Sep 17 00:00:00 2001 From: Allan Date: Thu, 21 May 2026 13:36:14 -0500 Subject: [PATCH 03/15] apply suggestions from code review Co-authored-by: Allan --- .../advanced/compliance-filtering.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index 818e383af0..c63507f943 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -8,11 +8,11 @@ target_audience: 'Developers who want to configure compliance rules on their cha --- New, optional components can be added to the Sequencer and State Transition Function (STF) to enable protocol-level transaction filtering for regulatory or compliance purposes, at the discretion of the chain owner. -The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox. +The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox on the parent chain. ## Rationale -The Arbitrum platform must evolve alongside the needs of a new wave of teams looking to come onchain - specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. +The Arbitrum platform must evolve to meet the needs of a new wave of teams looking to come onchain - specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. This feature represents the first of many to ensure that the Arbitrum platform can serve the needs of enterprises and institutions looking to tap into internet-scale, blockchain technology to increase margins, reduce risk, and improve transparency across their businesses. While this feature is not intended or proposed to be used by Arbitrum One, its inclusion in ArbOS 60 Elara is intended to simplify the codebase and canonicalize this feature in the node software. @@ -40,7 +40,7 @@ This is the primary enforcement layer and handles the vast majority of cases. ### Compliance rules Specific rules can be defined by the chain owner for any address found on the restricted list. -These rules apply whether the transfer is direct or uses a delegated approval mechanism. +These rules apply to direct transfers as well as delegated approval mechanisms. ### Delayed Inbox filtering (STF level) @@ -60,7 +60,7 @@ The sentinel is responsible for monitoring the delayed inbox for restricted tran 2. Ensures this occurs before the force inclusion window closes 3. Allows the sequencer to then process the transaction, which will fail at the STF level as expected -This ensures that even transactions submitted through the L1 → L2 messaging path are subject to compliance enforcement. +This ensures that even transactions submitted through the parent chain → child chain messaging path are subject to compliance enforcement. ### Exception rules (burn allowance) @@ -70,10 +70,10 @@ ERC-20, ERC-721, and ERC-1155 transfers where the `to` field of the Transfer eve Important constraints: -- If a transaction includes any other compliance violation in addition to a burn, the entire transaction still fails. +- If a "burn" transaction includes any other compliance violation, the entire transaction will fail. - A restricted address cannot initiate a burn themselves — their `tx.origin` is blocked at the sequencer level regardless. -This design allows third-party liquidators and protocol contracts (e.g., Paxos, Aave) to burn sanctioned balances while preventing the sanctioned address from taking any action on the chain. +This design allows third-party liquidators and protocol contracts (e.g., Paxos, Aave) to burn non-compliant balances while preventing the restricted address from taking any action on the chain. ### Synchronization pipeline @@ -100,4 +100,4 @@ Compliance Filtering is disabled by default. Chain owners must explicitly config - **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. - **L1 bridge deposits:** If a restricted address deposits ETH via `depositEth()` on L1, the ETH enters the L1 bridge contract before any L2 filtering occurs. If the corresponding L2 credit is dropped, the ETH may become locked in the bridge with no corresponding L2 asset. Chain owners should account for this in their compliance design and user communication strategy. -- **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned accounts. +- **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned addresses. From e1965b580a9651a15147d2151dc57ae012340461 Mon Sep 17 00:00:00 2001 From: Allan Date: Thu, 21 May 2026 13:40:35 -0500 Subject: [PATCH 04/15] update L1/L2 terminology to parent/child chain terminology --- .../02-configure-your-chain/advanced/compliance-filtering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index c63507f943..cb8a08862b 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -99,5 +99,5 @@ Compliance Filtering is disabled by default. Chain owners must explicitly config ## Security considerations - **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. -- **L1 bridge deposits:** If a restricted address deposits ETH via `depositEth()` on L1, the ETH enters the L1 bridge contract before any L2 filtering occurs. If the corresponding L2 credit is dropped, the ETH may become locked in the bridge with no corresponding L2 asset. Chain owners should account for this in their compliance design and user communication strategy. +- **Parent chain bridge deposits:** If a restricted address deposits ETH via `depositEth()` on the parent chain, the ETH enters the bridge contract on the parent chain before any filtering occurs on the child chain. If the corresponding credit is dropped on the child chain, the ETH may become locked in the bridge with no corresponding child chain asset. Chain owners should account for this in their compliance design and user communication strategy. - **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned addresses. From 44ed2de78718216782ad943ab00fbb538fdbf602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 21 May 2026 13:33:56 -0700 Subject: [PATCH 05/15] add quicklooks about prechecker node to glossary --- .../advanced/compliance-filtering.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index cb8a08862b..e60b297d50 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -77,7 +77,7 @@ This design allows third-party liquidators and protocol contracts (e.g., Paxos, ### Synchronization pipeline -The restricted address list is distributed to sequencer and prechecker nodes via a cloud-based pipeline: +The restricted address list is distributed to sequencer and prechecker nodes via a cloud-based pipeline: - The compliance provider periodically publishes a new hash list to a designated S3 bucket. - An SNS notification triggers ingestion into the chain operator's own S3 bucket. @@ -87,12 +87,12 @@ Nodes are expected to always have a valid list in memory. On startup or restart, ## Deployment considerations -| Component | Availability | Notes | -| --- | --- | --- | -| Sequencer-level filtering | ArbOS 60 Elara | Opcode and event filtering | -| Transaction Guardian Precompile | ArbOS 60 Elara | Required for Delayed Inbox enforcement | -| Delayed Inbox Sentinel (STF) | ArbOS 60 Elara | Requires audit; must be activated at deployment | -| Burn exception rules | ArbOS 60 Elara | Covers Aave, Paxos, and similar protocols | +| Component | Availability | Notes | +| ------------------------------- | -------------- | ----------------------------------------------- | +| Sequencer-level filtering | ArbOS 60 Elara | Opcode and event filtering | +| Transaction Guardian Precompile | ArbOS 60 Elara | Required for Delayed Inbox enforcement | +| Delayed Inbox Sentinel (STF) | ArbOS 60 Elara | Requires audit; must be activated at deployment | +| Burn exception rules | ArbOS 60 Elara | Covers Aave, Paxos, and similar protocols | Compliance Filtering is disabled by default. Chain owners must explicitly configure and enable each component. Activation after chain deployment may require an ArbOS upgrade. From 61748fc03233a9087ed1690c3d1cc7c3e75f4481 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 21 May 2026 13:34:39 -0700 Subject: [PATCH 06/15] fix ethers bug in VendingMachine component --- src/components/VendingMachine/VendingMachine.tsx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/components/VendingMachine/VendingMachine.tsx b/src/components/VendingMachine/VendingMachine.tsx index 01f15f9082..4987730802 100644 --- a/src/components/VendingMachine/VendingMachine.tsx +++ b/src/components/VendingMachine/VendingMachine.tsx @@ -1,5 +1,5 @@ import React, { useCallback, useEffect, useRef, useState } from 'react'; -import { BigNumber, ethers } from 'ethers'; +import { ethers } from 'ethers'; import VendingMachineContract from './VendingMachine.sol/VendingMachine.json'; function truncateAddress(text: string) { @@ -92,7 +92,7 @@ export const VendingMachine = (props: { id: string; type: string }) => { console.log(`getting cupcake balance for ${identity} on ${vendingMachineContractAddress}`); const contract = await this.initContract(vendingMachineContractAddress); const cupcakeBalance = await contract.getCupcakeBalanceFor(identity); - return BigNumber.from(cupcakeBalance).toNumber(); + return Number(cupcakeBalance); } async requestAccount() { @@ -116,8 +116,8 @@ export const VendingMachine = (props: { id: string; type: string }) => { if (this.ethereumAvailable()) { // "hey metamask, let's prepare to sign transactions with the account the user has selected" await this.requestAccount(); - const metamaskProvider = new ethers.providers.Web3Provider(window.ethereum); - const signer = metamaskProvider.getSigner(); + const metamaskProvider = new ethers.BrowserProvider(window.ethereum); + const signer = await metamaskProvider.getSigner(); return signer; } } From 6bbb9f39bdbbd08584a337a7fcf5f3d371b73a53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 21 May 2026 13:36:48 -0700 Subject: [PATCH 07/15] Update docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx Co-authored-by: Allan --- .../advanced/compliance-filtering.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index e60b297d50..4e6de09cb0 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -40,7 +40,11 @@ This is the primary enforcement layer and handles the vast majority of cases. ### Compliance rules Specific rules can be defined by the chain owner for any address found on the restricted list. -These rules apply to direct transfers as well as delegated approval mechanisms. +These rules apply to direct transfers as well as delegated approval mechanisms. A few examples: +- Block any transaction originating from or to a restricted address +- Block execution of ERC20 / ERC721 / ERC1155 transfers from or to a restricted address +- Block execution of the following opcodes targeting a restricted address: `CALL`, `CREATE`, `CREATE2`, `SELFDESTRUCT` + ### Delayed Inbox filtering (STF level) From 562209b62ef9e4504aa61da2783b8215201835c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 21 May 2026 13:56:17 -0700 Subject: [PATCH 08/15] edit prechecker node definition with Nitro codebase as unique source of truth --- docs/partials/_glossary-partial.mdx | 8 +++++++- static/glossary.json | 4 ++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/partials/_glossary-partial.mdx b/docs/partials/_glossary-partial.mdx index be89c7663e..fdb335d646 100644 --- a/docs/partials/_glossary-partial.mdx +++ b/docs/partials/_glossary-partial.mdx @@ -3,7 +3,7 @@ partial_type: glossary title: 'Arbitrum Glossary Definitions' description: 'Comprehensive glossary of Arbitrum terminology and definitions' author: anegg0 -last_reviewed: 2026-02-17 +last_reviewed: 2026-05-21 --- ### Active Validator {#active-validator} @@ -342,6 +342,12 @@ Anyone can become a validator by running an Arbitrum node, without permission. A web application maintained by [Offchain Labs](/intro/glossary#offchain-labs) showcasing the Arbitrum ecosystem; visit it [here](https://portal.arbitrum.io/). +### Prechecker Node {#prechecker-node} + +An [Arbitrum full node](/intro/glossary#arbitrum-full-node) configured to pre-validate transactions before forwarding `eth_sendRawTransaction` to the [Sequencer](/intro/glossary#sequencer), insulating it from transactions that would fail. + +At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any `eth_sendRawTransactionConditional` storage conditions. When [compliance filtering](/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering) is enabled, it also rejects transactions that touch restricted addresses. + ### Precompile {#precompile} A precompile is a predefined smart contract with a special address that provides specific functionality executed natively by the Arbitrum client, rather than at the EVM bytecode level. Precompiles are used to introduce functions that would be computationally expensive if run in EVM bytecode, or to facilitate interactions between the parent and child chains. Arbitrum supports all Ethereum precompiles and also provides additional precompiles specific to Arbitrum chains, which can be called from smart contracts like regular Solidity functions[(1)](https://docs.arbitrum.io/build-decentralized-apps/precompiles/overview). diff --git a/static/glossary.json b/static/glossary.json index d7cf817062..be0fc7e2e6 100644 --- a/static/glossary.json +++ b/static/glossary.json @@ -319,6 +319,10 @@ "title": "Portal", "text": "

A web application maintained by Offchain Labs showcasing the Arbitrum ecosystem; visit it here.

\n" }, + "prechecker-node": { + "title": "Prechecker Node", + "text": "

An Arbitrum full node configured to pre-validate transactions before forwarding eth_sendRawTransaction to the Sequencer, insulating it from transactions that would fail.

\n

At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any eth_sendRawTransactionConditional storage conditions. When compliance filtering is enabled, it also rejects transactions that touch restricted addresses.

\n" + }, "precompile": { "title": "Precompile", "text": "

A precompile is a predefined smart contract with a special address that provides specific functionality executed natively by the Arbitrum client, rather than at the EVM bytecode level. Precompiles are used to introduce functions that would be computationally expensive if run in EVM bytecode, or to facilitate interactions between the parent and child chains. Arbitrum supports all Ethereum precompiles and also provides additional precompiles specific to Arbitrum chains, which can be called from smart contracts like regular Solidity functions(1).

\n" From 41f2b95e99cc1bb928504a63931bd5db4e735e67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 21 May 2026 14:06:01 -0700 Subject: [PATCH 09/15] fix glossary --- docs/partials/_glossary-partial.mdx | 2 +- static/glossary.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/partials/_glossary-partial.mdx b/docs/partials/_glossary-partial.mdx index fdb335d646..b54222128b 100644 --- a/docs/partials/_glossary-partial.mdx +++ b/docs/partials/_glossary-partial.mdx @@ -346,7 +346,7 @@ A web application maintained by [Offchain Labs](/intro/glossary#offchain-labs) s An [Arbitrum full node](/intro/glossary#arbitrum-full-node) configured to pre-validate transactions before forwarding `eth_sendRawTransaction` to the [Sequencer](/intro/glossary#sequencer), insulating it from transactions that would fail. -At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any `eth_sendRawTransactionConditional` storage conditions. When [compliance filtering](/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering) is enabled, it also rejects transactions that touch restricted addresses. +At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any `eth_sendRawTransactionConditional` storage conditions. When [compliance filtering](/launch-arbitrum-chain/configure-your-chain/advanced/compliance-filtering) is enabled, it also rejects transactions that touch restricted addresses. ### Precompile {#precompile} diff --git a/static/glossary.json b/static/glossary.json index be0fc7e2e6..2ea927f5e0 100644 --- a/static/glossary.json +++ b/static/glossary.json @@ -321,7 +321,7 @@ }, "prechecker-node": { "title": "Prechecker Node", - "text": "

An Arbitrum full node configured to pre-validate transactions before forwarding eth_sendRawTransaction to the Sequencer, insulating it from transactions that would fail.

\n

At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any eth_sendRawTransactionConditional storage conditions. When compliance filtering is enabled, it also rejects transactions that touch restricted addresses.

\n" + "text": "

An Arbitrum full node configured to pre-validate transactions before forwarding eth_sendRawTransaction to the Sequencer, insulating it from transactions that would fail.

\n

At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any eth_sendRawTransactionConditional storage conditions. When compliance filtering is enabled, it also rejects transactions that touch restricted addresses.

\n" }, "precompile": { "title": "Precompile", From fcf86547cf9e0fee594becfb39e8a9b71fcf245e Mon Sep 17 00:00:00 2001 From: Chris Cordle Date: Fri, 22 May 2026 21:59:52 -0500 Subject: [PATCH 10/15] Adding configuration info --- .../advanced/compliance-filtering.mdx | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index 4e6de09cb0..f73df2a1b2 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -105,3 +105,78 @@ Compliance Filtering is disabled by default. Chain owners must explicitly config - **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. - **Parent chain bridge deposits:** If a restricted address deposits ETH via `depositEth()` on the parent chain, the ETH enters the bridge contract on the parent chain before any filtering occurs on the child chain. If the corresponding credit is dropped on the child chain, the ETH may become locked in the bridge with no corresponding child chain asset. Chain owners should account for this in their compliance design and user communication strategy. - **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned addresses. + +## Configuration + +To set up transaction filters, Arbitrum Nitro nodes provide a few configuration options for both address level filtering and event filtering. Event filters are optional, but address filters must both be enabled and configured properly before transactions will be properly filtered. + +### Address filter + +To define the addresses that are to be restricted from executing or receiving onchain transactions, an S3-compatible file store must be used. When address filtering is enabled, Arbitrum Nitro will poll and read the latest file from the S3 bucket. The addresses are defined as hashes where `hashed_address = SHA256(salt16Byte || address20Byte)`. + +- `--execution.transaction-filtering.address-filter.enable`: true/false value that enables address filtering +- `--execution.transaction-filtering.address-filter.poll-interval`: how often to resync from S3 (e.g. `60m`) +- `--execution.transaction-filtering.address-filter.s3.bucket`: S3 bucket holding the hashed list +- `--execution.transaction-filtering.address-filter.s3.object-key`: S3 object key for the hash list +- `--execution.transaction-filtering.address-filter.s3.region`: AWS region where S3 bucket is hosted (e.g. `us-east-1`) +- `--execution.address-filter.s3.access-key`: AWS access key +- `--execution.address-filter.s3.secret-key`: AWS secret key +- `--execution.address-filter.s3.endpoint`: S3-compatible endpoint where file is hosted (if not using AWS S3) + +The hash list of restricted addresses should be provided as a JSON file with the following format: + +```json +{ + salt: string, # UUID + hashes: [string], # list of 32-byte hashes as hex encoded strings + issued_at: string, # timestamp + hashing_scheme: string # sha256-stringinput or sha256-rawbytesinput. +} +``` + +Note: `sha256-stringinput` assumes that the string-based representation of the UUID salt is concatenated with the string-based version of the hex-encoded address (e.g. `sha256("d35e8ac5-9775-44af-878e-bad86409e80c" || "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")`). Raw bytes uses the raw 16 bytes of the UUID and raw 20 bytes of the address concatenated as input to the sha256 function to produce the 32-byte hash. + +### Event filters + +Event filters allow for chain owners to filter out transactions based on an arbitrary list of emitted events. For example, a chain owner might want to block all ERC20 transfers involving a restricted address. A chain owner can setup their nodes to listen for `Transfer(address,address,uint256)` events and block any transactions that target a restricted address in either the `from` or `to` field. To setup event filters, two CLI flags are provided: + +- `--execution.transaction-filtering.event-filter.rules`: optional inline list of event rules (passed as a JSON string) +- `--execution.transaction-filtering.event-filter.path`: optional path to a JSON file containing event filter rules. If both `path` and `rules` are provided, the file rules are loaded first and then inline rules are appended after them. Generally, path-based JSON rules should be preferred. + +Each entry in the rules is an `EventRule` with the following shape: + +- `event`: human-readable event signature (e.g. `Transfer(address,address,uint256)` +- `selector`: hex string of the first 4 bytes of `keccak256(event)`; the canonical signature of the event type +- `topicAddresses`: list of 1-indexed topic positions (1-3) whose values should be treated as addresses for filtering +- `bypass`: defines an optional exception condition that allows the transaction to execute if a specific value is true (example would be transfers to `0x0` burn address). It is a nested object with: + - `topicIndex`: 1-indexed topic position (1-3) + - `equals`: conditional value for the exception at the topic position defined + +An example JSON file to provide to `--execution.transaction-filtering.event-filter.path`: + +```json +{ + "rules":[ + { + "event":"Transfer(address,address,uint256)", + "selector":"0xddf252ad", + "topicAddresses":[ + 1, + 2 + ], + "bypass":{ + "topicIndex":2, + "equals":"0x0000000000000000000000000000000000000000" + } + }, + { + "event":"Approval(address,address,uint256)", + "selector":"0x8c5be1e5", + "topicAddresses":[ + 1, + 2 + ] + } + ] +} +``` From 784136f0ea691f6466b6b17eb2267098017f6b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 16 Jun 2026 17:56:19 -0700 Subject: [PATCH 11/15] add prechecker node to glossary --- docs/partials/_glossary-partial.mdx | 2 +- docs/partials/glossary/_prechecker-node.mdx | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 docs/partials/glossary/_prechecker-node.mdx diff --git a/docs/partials/_glossary-partial.mdx b/docs/partials/_glossary-partial.mdx index b54222128b..be5ef0e01f 100644 --- a/docs/partials/_glossary-partial.mdx +++ b/docs/partials/_glossary-partial.mdx @@ -3,7 +3,7 @@ partial_type: glossary title: 'Arbitrum Glossary Definitions' description: 'Comprehensive glossary of Arbitrum terminology and definitions' author: anegg0 -last_reviewed: 2026-05-21 +last_reviewed: 2026-06-17 --- ### Active Validator {#active-validator} diff --git a/docs/partials/glossary/_prechecker-node.mdx b/docs/partials/glossary/_prechecker-node.mdx new file mode 100644 index 0000000000..ca4bb08add --- /dev/null +++ b/docs/partials/glossary/_prechecker-node.mdx @@ -0,0 +1,9 @@ +--- +title: Prechecker Node +key: prechecker-node +titleforSort: Prechecker Node +--- + +An [Arbitrum full node](/intro/glossary#arbitrum-full-node) configured to pre-validate transactions before forwarding `eth_sendRawTransaction` to the [Sequencer](/intro/glossary#sequencer), insulating it from transactions that would fail. + +At a configurable strictness level, a prechecker verifies the transaction type, signature, intrinsic gas (including L1 calldata gas), fee cap, nonce, sender balance, and any `eth_sendRawTransactionConditional` storage conditions. When [compliance filtering](/launch-arbitrum-chain/configure-your-chain/advanced/compliance-filtering) is enabled, it also rejects transactions that touch restricted addresses. From 8bff28cc9b02e7472554be361f644e7d4229833a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 16 Jun 2026 17:56:32 -0700 Subject: [PATCH 12/15] apply Offchain's pattern guide to compliance filtering article --- .../advanced/compliance-filtering.mdx | 68 +++++++++---------- 1 file changed, 32 insertions(+), 36 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index f73df2a1b2..b67bc83f42 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -1,22 +1,24 @@ --- -title: 'Compliance Filtering' -description: '' +title: 'Compliance filtering' +sidebar_label: 'Compliance filtering' +description: 'How chain owners configure protocol-level transaction filtering to restrict sanctioned addresses on their Arbitrum chain.' +user_story: 'As a chain owner, I want to configure compliance rules so that transactions involving restricted addresses are filtered before execution.' content_type: how-to author: gmehta2 sme: gmehta2 target_audience: 'Developers who want to configure compliance rules on their chain' --- -New, optional components can be added to the Sequencer and State Transition Function (STF) to enable protocol-level transaction filtering for regulatory or compliance purposes, at the discretion of the chain owner. -The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox on the parent chain. +New, optional components can be added to the Sequencer and State Transition Function (STF) to enable protocol-level transaction filtering for regulatory or compliance purposes, at the discretion of the chain owner. +The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox on the parent chain. ## Rationale -The Arbitrum platform must evolve to meet the needs of a new wave of teams looking to come onchain - specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. +The Arbitrum platform must evolve to meet the needs of a new wave of teams looking to come onchain—specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. This feature represents the first of many to ensure that the Arbitrum platform can serve the needs of enterprises and institutions looking to tap into internet-scale, blockchain technology to increase margins, reduce risk, and improve transparency across their businesses. While this feature is not intended or proposed to be used by Arbitrum One, its inclusion in ArbOS 60 Elara is intended to simplify the codebase and canonicalize this feature in the node software. -This feature is instead intended to be used by Arbitrum chains who have compliance and regulatory obligations to restrict on-chain activity from sanctioned entities or actors. +This feature is instead intended to be used by Arbitrum chains who have compliance and regulatory obligations to restrict onchain activity from sanctioned entities or actors. ## How it works @@ -34,26 +36,26 @@ When evaluating a transaction, the compliance engine hashes all relevant address ### Sequencer-level filtering -The Compliance Rules Engine runs inside the sequencer and simulates each transaction before it is sequenced. If a transaction violates any compliance rule, it is rejected at the sequencer level and never included in a block. +The Compliance Rules Engine runs inside the Sequencer and simulates each transaction before it is sequenced. If a transaction violates any compliance rule, it is rejected at the Sequencer level and never included in a block. This is the primary enforcement layer and handles the vast majority of cases. ### Compliance rules Specific rules can be defined by the chain owner for any address found on the restricted list. These rules apply to direct transfers as well as delegated approval mechanisms. A few examples: + - Block any transaction originating from or to a restricted address -- Block execution of ERC20 / ERC721 / ERC1155 transfers from or to a restricted address +- Block execution of ERC-20, ERC-721, and ERC-1155 transfers from or to a restricted address - Block execution of the following opcodes targeting a restricted address: `CALL`, `CREATE`, `CREATE2`, `SELFDESTRUCT` - ### Delayed Inbox filtering (STF level) -Transactions submitted via the Delayed Inbox cannot be filtered at the sequencer layer alone, since they are eligible for force inclusion after a timeout window. +Transactions submitted via the Delayed Inbox cannot be filtered at the Sequencer layer alone, since they are eligible for force inclusion after a timeout window. To handle this, Compliance Filtering introduces two additional components: #### Transaction Guardian Precompile -A new precompile allows authorized entities (e.g., the sequencer) to register the hash of a restricted transaction on-chain before it is force-included. When the STF processes a transaction from the delayed inbox, it checks whether that transaction's hash has been registered in the guardian. +A new precompile allows authorized entities (e.g., the Sequencer) to register the hash of a restricted transaction onchain before it is force-included. When the STF processes a transaction from the delayed inbox, it checks whether that transaction's hash has been registered in the guardian. If so, the transaction is forcibly failed on inclusion, consuming any gas attached to prevent spam. #### Delayed Inbox Sentinel @@ -62,7 +64,7 @@ The sentinel is responsible for monitoring the delayed inbox for restricted tran 1. Submits the transaction's hash to the Transaction Guardian Precompile 2. Ensures this occurs before the force inclusion window closes -3. Allows the sequencer to then process the transaction, which will fail at the STF level as expected +3. Allows the Sequencer to then process the transaction, which will fail at the STF level as expected This ensures that even transactions submitted through the parent chain → child chain messaging path are subject to compliance enforcement. @@ -75,13 +77,13 @@ ERC-20, ERC-721, and ERC-1155 transfers where the `to` field of the Transfer eve Important constraints: - If a "burn" transaction includes any other compliance violation, the entire transaction will fail. -- A restricted address cannot initiate a burn themselves — their `tx.origin` is blocked at the sequencer level regardless. +- A restricted address cannot initiate a burn themselves — their `tx.origin` is blocked at the Sequencer level regardless. This design allows third-party liquidators and protocol contracts (e.g., Paxos, Aave) to burn non-compliant balances while preventing the restricted address from taking any action on the chain. ### Synchronization pipeline -The restricted address list is distributed to sequencer and prechecker nodes via a cloud-based pipeline: +The restricted address list is distributed to Sequencer and prechecker nodes via a cloud-based pipeline: - The compliance provider periodically publishes a new hash list to a designated S3 bucket. - An SNS notification triggers ingestion into the chain operator's own S3 bucket. @@ -102,7 +104,7 @@ Compliance Filtering is disabled by default. Chain owners must explicitly config ## Security considerations -- **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. +- **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass Sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. - **Parent chain bridge deposits:** If a restricted address deposits ETH via `depositEth()` on the parent chain, the ETH enters the bridge contract on the parent chain before any filtering occurs on the child chain. If the corresponding credit is dropped on the child chain, the ETH may become locked in the bridge with no corresponding child chain asset. Chain owners should account for this in their compliance design and user communication strategy. - **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned addresses. @@ -156,27 +158,21 @@ An example JSON file to provide to `--execution.transaction-filtering.event-filt ```json { - "rules":[ - { - "event":"Transfer(address,address,uint256)", - "selector":"0xddf252ad", - "topicAddresses":[ - 1, - 2 - ], - "bypass":{ - "topicIndex":2, - "equals":"0x0000000000000000000000000000000000000000" - } - }, - { - "event":"Approval(address,address,uint256)", - "selector":"0x8c5be1e5", - "topicAddresses":[ - 1, - 2 - ] + "rules": [ + { + "event": "Transfer(address,address,uint256)", + "selector": "0xddf252ad", + "topicAddresses": [1, 2], + "bypass": { + "topicIndex": 2, + "equals": "0x0000000000000000000000000000000000000000" } - ] + }, + { + "event": "Approval(address,address,uint256)", + "selector": "0x8c5be1e5", + "topicAddresses": [1, 2] + } + ] } ``` From 107c04e5f2b20e01800fce708f4ebf314aaf46cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 25 Jun 2026 16:49:24 -0700 Subject: [PATCH 13/15] Update compliance filtering components to ArbOS 61 Updated availability version for compliance filtering components to ArbOS 61 Elara. --- .../advanced/compliance-filtering.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx index b67bc83f42..0cb03fe099 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx @@ -95,10 +95,10 @@ Nodes are expected to always have a valid list in memory. On startup or restart, | Component | Availability | Notes | | ------------------------------- | -------------- | ----------------------------------------------- | -| Sequencer-level filtering | ArbOS 60 Elara | Opcode and event filtering | -| Transaction Guardian Precompile | ArbOS 60 Elara | Required for Delayed Inbox enforcement | -| Delayed Inbox Sentinel (STF) | ArbOS 60 Elara | Requires audit; must be activated at deployment | -| Burn exception rules | ArbOS 60 Elara | Covers Aave, Paxos, and similar protocols | +| Sequencer-level filtering | ArbOS 61 Elara | Opcode and event filtering | +| Transaction Guardian Precompile | ArbOS 61 Elara | Required for Delayed Inbox enforcement | +| Delayed Inbox Sentinel (STF) | ArbOS 61 Elara | Requires audit; must be activated at deployment | +| Burn exception rules | ArbOS 61 Elara | Covers Aave, Paxos, and similar protocols | Compliance Filtering is disabled by default. Chain owners must explicitly configure and enable each component. Activation after chain deployment may require an ArbOS upgrade. From 221943b8a3fe4b36d5bd47f92080aebd8d82cdd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 26 Jun 2026 11:27:07 -0700 Subject: [PATCH 14/15] Delete docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx --- .../advanced/compliance-filtering.mdx | 178 ------------------ 1 file changed, 178 deletions(-) delete mode 100644 docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx deleted file mode 100644 index 0cb03fe099..0000000000 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced/compliance-filtering.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: 'Compliance filtering' -sidebar_label: 'Compliance filtering' -description: 'How chain owners configure protocol-level transaction filtering to restrict sanctioned addresses on their Arbitrum chain.' -user_story: 'As a chain owner, I want to configure compliance rules so that transactions involving restricted addresses are filtered before execution.' -content_type: how-to -author: gmehta2 -sme: gmehta2 -target_audience: 'Developers who want to configure compliance rules on their chain' ---- - -New, optional components can be added to the Sequencer and State Transition Function (STF) to enable protocol-level transaction filtering for regulatory or compliance purposes, at the discretion of the chain owner. -The chain owner may configure an external compliance service (e.g., TRM or Chainalysis) to define address-level policies. Any transaction that originates from, targets, or otherwise involves a restricted address is filtered prior to execution, including transactions submitted via the Delayed Inbox on the parent chain. - -## Rationale - -The Arbitrum platform must evolve to meet the needs of a new wave of teams looking to come onchain—specifically teams who have an obligation to comply with regulatory frameworks and rules in their respective jurisdictions. -This feature represents the first of many to ensure that the Arbitrum platform can serve the needs of enterprises and institutions looking to tap into internet-scale, blockchain technology to increase margins, reduce risk, and improve transparency across their businesses. - -While this feature is not intended or proposed to be used by Arbitrum One, its inclusion in ArbOS 60 Elara is intended to simplify the codebase and canonicalize this feature in the node software. -This feature is instead intended to be used by Arbitrum chains who have compliance and regulatory obligations to restrict onchain activity from sanctioned entities or actors. - -## How it works - -Compliance Filtering operates across two layers: the Sequencer and the State Transition Function (STF). Together, these layers ensure that restricted activity is blocked regardless of how a transaction enters the system. - -### Restricted address list - -The chain owner configures an external compliance provider (e.g., TRM Labs, Chainalysis) to define which addresses are restricted. This produces a restricted address list, which is: - -1. Stored in-memory on any node performing compliance screening -2. Encoded as salted hashes in the form `sha256(salt || address)` to protect address privacy -3. Refreshed periodically via a synchronization pipeline - -When evaluating a transaction, the compliance engine hashes all relevant addresses and checks them against this list. - -### Sequencer-level filtering - -The Compliance Rules Engine runs inside the Sequencer and simulates each transaction before it is sequenced. If a transaction violates any compliance rule, it is rejected at the Sequencer level and never included in a block. -This is the primary enforcement layer and handles the vast majority of cases. - -### Compliance rules - -Specific rules can be defined by the chain owner for any address found on the restricted list. -These rules apply to direct transfers as well as delegated approval mechanisms. A few examples: - -- Block any transaction originating from or to a restricted address -- Block execution of ERC-20, ERC-721, and ERC-1155 transfers from or to a restricted address -- Block execution of the following opcodes targeting a restricted address: `CALL`, `CREATE`, `CREATE2`, `SELFDESTRUCT` - -### Delayed Inbox filtering (STF level) - -Transactions submitted via the Delayed Inbox cannot be filtered at the Sequencer layer alone, since they are eligible for force inclusion after a timeout window. -To handle this, Compliance Filtering introduces two additional components: - -#### Transaction Guardian Precompile - -A new precompile allows authorized entities (e.g., the Sequencer) to register the hash of a restricted transaction onchain before it is force-included. When the STF processes a transaction from the delayed inbox, it checks whether that transaction's hash has been registered in the guardian. -If so, the transaction is forcibly failed on inclusion, consuming any gas attached to prevent spam. - -#### Delayed Inbox Sentinel - -The sentinel is responsible for monitoring the delayed inbox for restricted transactions. When a restricted transaction is detected, the sentinel: - -1. Submits the transaction's hash to the Transaction Guardian Precompile -2. Ensures this occurs before the force inclusion window closes -3. Allows the Sequencer to then process the transaction, which will fail at the STF level as expected - -This ensures that even transactions submitted through the parent chain → child chain messaging path are subject to compliance enforcement. - -### Exception rules (burn allowance) - -Certain DeFi protocols (e.g., lending protocols like Aave, Morpho) require the ability to liquidate or burn token balances associated with restricted accounts in order to maintain solvency and prevent exploits. -To support this, a narrow exception is available: -ERC-20, ERC-721, and ERC-1155 transfers where the `to` field of the Transfer event is the zero address (`0x0`) (a burn operation) are permitted even if the `from` address is restricted. - -Important constraints: - -- If a "burn" transaction includes any other compliance violation, the entire transaction will fail. -- A restricted address cannot initiate a burn themselves — their `tx.origin` is blocked at the Sequencer level regardless. - -This design allows third-party liquidators and protocol contracts (e.g., Paxos, Aave) to burn non-compliant balances while preventing the restricted address from taking any action on the chain. - -### Synchronization pipeline - -The restricted address list is distributed to Sequencer and prechecker nodes via a cloud-based pipeline: - -- The compliance provider periodically publishes a new hash list to a designated S3 bucket. -- An SNS notification triggers ingestion into the chain operator's own S3 bucket. -- Nodes subscribe to updates and load the new list into memory, fully replacing the prior list once the new one is validated and complete. - -Nodes are expected to always have a valid list in memory. On startup or restart, a node will fetch the most recent list before beginning to sequence or precheck transactions. - -## Deployment considerations - -| Component | Availability | Notes | -| ------------------------------- | -------------- | ----------------------------------------------- | -| Sequencer-level filtering | ArbOS 61 Elara | Opcode and event filtering | -| Transaction Guardian Precompile | ArbOS 61 Elara | Required for Delayed Inbox enforcement | -| Delayed Inbox Sentinel (STF) | ArbOS 61 Elara | Requires audit; must be activated at deployment | -| Burn exception rules | ArbOS 61 Elara | Covers Aave, Paxos, and similar protocols | - -Compliance Filtering is disabled by default. Chain owners must explicitly configure and enable each component. Activation after chain deployment may require an ArbOS upgrade. - -## Security considerations - -- **Force inclusion protection:** Without STF-level enforcement via the Transaction Guardian, a restricted user could bypass Sequencer filtering by waiting for the force inclusion window. The sentinel + precompile combination closes this gap. -- **Parent chain bridge deposits:** If a restricted address deposits ETH via `depositEth()` on the parent chain, the ETH enters the bridge contract on the parent chain before any filtering occurs on the child chain. If the corresponding credit is dropped on the child chain, the ETH may become locked in the bridge with no corresponding child chain asset. Chain owners should account for this in their compliance design and user communication strategy. -- **Address privacy:** Restricted addresses are never stored in plaintext. Salted hashing ensures that the list cannot be trivially reversed to enumerate sanctioned addresses. - -## Configuration - -To set up transaction filters, Arbitrum Nitro nodes provide a few configuration options for both address level filtering and event filtering. Event filters are optional, but address filters must both be enabled and configured properly before transactions will be properly filtered. - -### Address filter - -To define the addresses that are to be restricted from executing or receiving onchain transactions, an S3-compatible file store must be used. When address filtering is enabled, Arbitrum Nitro will poll and read the latest file from the S3 bucket. The addresses are defined as hashes where `hashed_address = SHA256(salt16Byte || address20Byte)`. - -- `--execution.transaction-filtering.address-filter.enable`: true/false value that enables address filtering -- `--execution.transaction-filtering.address-filter.poll-interval`: how often to resync from S3 (e.g. `60m`) -- `--execution.transaction-filtering.address-filter.s3.bucket`: S3 bucket holding the hashed list -- `--execution.transaction-filtering.address-filter.s3.object-key`: S3 object key for the hash list -- `--execution.transaction-filtering.address-filter.s3.region`: AWS region where S3 bucket is hosted (e.g. `us-east-1`) -- `--execution.address-filter.s3.access-key`: AWS access key -- `--execution.address-filter.s3.secret-key`: AWS secret key -- `--execution.address-filter.s3.endpoint`: S3-compatible endpoint where file is hosted (if not using AWS S3) - -The hash list of restricted addresses should be provided as a JSON file with the following format: - -```json -{ - salt: string, # UUID - hashes: [string], # list of 32-byte hashes as hex encoded strings - issued_at: string, # timestamp - hashing_scheme: string # sha256-stringinput or sha256-rawbytesinput. -} -``` - -Note: `sha256-stringinput` assumes that the string-based representation of the UUID salt is concatenated with the string-based version of the hex-encoded address (e.g. `sha256("d35e8ac5-9775-44af-878e-bad86409e80c" || "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")`). Raw bytes uses the raw 16 bytes of the UUID and raw 20 bytes of the address concatenated as input to the sha256 function to produce the 32-byte hash. - -### Event filters - -Event filters allow for chain owners to filter out transactions based on an arbitrary list of emitted events. For example, a chain owner might want to block all ERC20 transfers involving a restricted address. A chain owner can setup their nodes to listen for `Transfer(address,address,uint256)` events and block any transactions that target a restricted address in either the `from` or `to` field. To setup event filters, two CLI flags are provided: - -- `--execution.transaction-filtering.event-filter.rules`: optional inline list of event rules (passed as a JSON string) -- `--execution.transaction-filtering.event-filter.path`: optional path to a JSON file containing event filter rules. If both `path` and `rules` are provided, the file rules are loaded first and then inline rules are appended after them. Generally, path-based JSON rules should be preferred. - -Each entry in the rules is an `EventRule` with the following shape: - -- `event`: human-readable event signature (e.g. `Transfer(address,address,uint256)` -- `selector`: hex string of the first 4 bytes of `keccak256(event)`; the canonical signature of the event type -- `topicAddresses`: list of 1-indexed topic positions (1-3) whose values should be treated as addresses for filtering -- `bypass`: defines an optional exception condition that allows the transaction to execute if a specific value is true (example would be transfers to `0x0` burn address). It is a nested object with: - - `topicIndex`: 1-indexed topic position (1-3) - - `equals`: conditional value for the exception at the topic position defined - -An example JSON file to provide to `--execution.transaction-filtering.event-filter.path`: - -```json -{ - "rules": [ - { - "event": "Transfer(address,address,uint256)", - "selector": "0xddf252ad", - "topicAddresses": [1, 2], - "bypass": { - "topicIndex": 2, - "equals": "0x0000000000000000000000000000000000000000" - } - }, - { - "event": "Approval(address,address,uint256)", - "selector": "0x8c5be1e5", - "topicAddresses": [1, 2] - } - ] -} -``` From 502691fa185d612b64ffa89f11187f43b6d0988c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 26 Jun 2026 11:28:31 -0700 Subject: [PATCH 15/15] Remove compliance filtering from sidebar Removed compliance filtering documentation from sidebar. --- sidebars.js | 5 ----- 1 file changed, 5 deletions(-) diff --git a/sidebars.js b/sidebars.js index f7a1c0bc27..f850fdfeec 100644 --- a/sidebars.js +++ b/sidebars.js @@ -530,11 +530,6 @@ const sidebars = { id: 'launch-arbitrum-chain/configure-your-chain/advanced/da-api-integration-guide', label: `DA API integration guide`, }, - { - type: 'doc', - id: 'launch-arbitrum-chain/configure-your-chain/advanced/compliance-filtering', - label: 'Compliance filtering', - }, ], }, ],