Enabling Bridging

Bridging moves assets between Ethereum L1 and a Prividium™ network. Enabling it requires configuration across three independent layers.

1. Permissions-API rules: function permissions on the L2 system contracts (and per-token L2 ERC-20 contracts) that the User Panel calls during bridging.
2. L1 Transaction Filterer: an optional L1 contract that controls which L1→L2 deposits are accepted.
3. Frontend settings: user-panel environment variables that show or hide the bridge UI.

How bridging uses permissions

Prividium™ applies its deny-by-default permission model to system contracts. After system-contract sync, every bridge function starts as Forbidden. Create the rules below to turn bridging on for a new environment.

Deposits and withdrawals use permissions differently:

• Deposits move funds in through an L1 transaction. The L2 crediting runs as an automatic priority-queue transaction that bypasses Prividium and needs no L2 write permission. Before it can start a deposit, though, the User Panel reads token metadata from L2NativeTokenVault on L2. If those reads are Forbidden, the User Panel cannot start the deposit. Deposits therefore require L2 read permissions.
• Withdrawals are user-signed L2 transactions. The User Panel needs both the read permissions (same token metadata) and write permissions on the withdrawal functions.

The three bridge system contracts are registered automatically:

Create the permission rules below from each contract's Function Permissions tab in the Admin Dashboard, or through the API.

Token-resolution read permissions

The User Panel reads token metadata from L2 before every deposit and withdrawal, for both ETH and ERC-20. Grant these reads as All Users (public) because they are read-only view calls. You can also gate them by role if your policy requires it.

L2NativeTokenVault at 0x0000000000000000000000000000000000010004 (read access):

Withdrawals also read one function on L2AssetRouter at 0x0000000000000000000000000000000000010003 (read access):

The User Panel reads the first four L2NativeTokenVault functions on every deposit and withdrawal, including plain ETH. Any user who lacks full sequencer access needs all four permitted to bridge in either direction.

Enabling deposits

A deposit requires:

1. The token-resolution read permissions above (the four common functions for ETH; add l2TokenAddress for ERC-20).
2. The L1 Transaction Filterer to allow the deposit (see Transaction Filterer).

The L2 execution of a deposit is a priority-queue transaction and needs no L2 write permission. The reads above are the only L2-side configuration a deposit needs.

Enabling withdrawals

A withdrawal requires the read permissions above plus the following write permissions. Grant as All Users (public) or Check Role.

Withdrawals must also be enabled in the frontend with VITE_WITHDRAWAL_ENABLED=true (see Frontend configuration).

ERC-20 considerations

• Per-token permissions are required. Each bridgeable ERC-20 has its own L2 address and needs its own rules: approve(address,uint256) (write) for withdrawals, and allowance(address,address) and balanceOf(address) as reads. Add a rule for every token you intend to bridge, because no wildcard covers them.
• Token registration. ensureTokenIsRegistered(address) registers the token in L2NativeTokenVault and returns its asset id; it must be permitted (write) before an ERC-20 withdrawal can be routed.
• Frontend token list. Additional ERC-20s shown in the user panel are configured with VITE_BRIDGE_TOKENS (JSON). The L2 token address for each entry must be resolved correctly; see the private user-panel environment variable docs for the schema.

Transaction Filterer

The Transaction Filterer is an optional L1 contract that gates which L1→L2 transactions (including deposits) are queued. It is the deposit-side admission control and is independent of the L2 permission rules above.

Key behaviors:

• setDepositsAllowed(bool) toggles whether non-whitelisted addresses may deposit.
• When deposits are allowed, a non-whitelisted EOA may deposit only to its own address.
• Whitelisted addresses (grantWhitelist / revokeWhitelist) may perform arbitrary L1→L2 transactions.
• L1 contract addresses are aliased during deposit, so L1 contracts cannot deposit unless explicitly whitelisted.

If deposits are rejected at L1 (no L2 priority transaction appears) even though permissions are correct, check the filterer's depositsAllowed flag and the sender's whitelist status. For deployment and the full method reference, see Transaction Filterer.

Frontend configuration

These user-panel environment variables control the bridge UI only. They do not create permission rules and do not affect the Transaction Filterer.

See the private user-panel environment variable docs for the full list.

Verification checklist

Confirm a permission rule exists for each (contract, function) below, that its access type matches, and that its rule is All Users (public) or a Check Role rule the user holds. None should remain Forbidden.

Deposit — ETH

• L2NativeTokenVault.L1_CHAIN_ID() — read
• L2NativeTokenVault.BASE_TOKEN_ASSET_ID() — read
• L2NativeTokenVault.WETH_TOKEN() — read
• L2NativeTokenVault.originChainId(bytes32) — read
• Transaction Filterer allows the sender

Deposit — ERC-20 (all of the above, plus)

• L2NativeTokenVault.l2TokenAddress(address) — read

Withdraw — ETH (the four common reads, plus)

• L2BaseToken.withdraw(address) — write
• VITE_WITHDRAWAL_ENABLED=true

Withdraw — ERC-20 (the four common reads, plus)

• L2AssetRouter.l1TokenAddress(address) — read
• L2NativeTokenVault.ensureTokenIsRegistered(address) — write
• <token>.approve(address,uint256) — write
• <token>.allowance(address,address) — read
• L2AssetRouter.withdraw(bytes32,bytes) — write
• VITE_WITHDRAWAL_ENABLED=true

Troubleshooting