feat: ZK as gateway token

[Raid5594]

What ❔

Why ❔

Checklist

• PR title corresponds to the body of PR (we generate changelog entries from PRs).
• Tests for the changes have been added / updated.
• Documentation comments have been added / updated.

[github-actions]

Changes to gas cost

Generated at commit: a65f2d638c7eb3dd668e5cb007a93edad8a122b2, compared to commit: 5b8b0785e4f7bae0b6d09d2dcd3d2b324204c16d

🧾 Summary (100% most significant diffs)

Contract	Method	Avg (+/-)	%
DummyBridgehubSetter	createNewChain requestL2TransactionDirect requestL2TransactionTwoBridges setPendingAdmin	-1,066 ✅ -1,051 ✅ -42 ✅ 0 ➖	-0.98% -1.09% -0.03% 0.00%
ChainAdmin	setUpgradeTimestamp	-153 ✅	-0.34%
DiamondProxy	finalizeEthWithdrawal requestL2Transaction	+237 ❌ +2 ❌	+0.30% +0.00%
L1NativeTokenVault	ensureTokenIsRegistered registerEthToken registerToken	+191 ❌ -11 ✅ +94 ❌	+0.17% -0.01% +0.08%
MerkleTest	calculateRoot(bytes32[],uint256,bytes32)	-2 ✅	-0.07%
TransparentUpgradeableProxy	registerEthToken registerToken setAllowedData	-11 ✅ +95 ❌ -19 ✅	-0.01% +0.06% -0.03%
DummyChainTypeManagerWBH	setZKChain	-1 ✅	-0.00%

---

Full diff report 👇

Contract	Deployment Cost (+/-)	Method	Min (+/-)	%	Avg (+/-)	%	Median (+/-)	%	Max (+/-)	%	# Calls (+/-)
DummyBridgehubSetter	4,313,059 (0)	addChainTypeManager createNewChain proveL1ToL2TransactionStatus proveL2LogInclusion proveL2MessageInclusion removeChainTypeManager requestL2TransactionDirect requestL2TransactionTwoBridges setAddresses setCTM setPendingAdmin setZKChain	23,895 (0) 28,889 (-168) 0 (0) 0 (0) 0 (0) 23,832 (0) 33,041 (+21) 31,017 (+12) 24,348 (0) 44,232 (0) 25,999 (-12) 111,339 (0)	0.00% -0.58% +∞% +∞% +∞% 0.00% +0.06% +0.04% 0.00% 0.00% -0.05% 0.00%	44,150 (+2) 108,034 (-1,066) 1,370 (-20) 1,493 (-20) 1,596 (-9) 25,471 (+2) 95,190 (-1,051) 148,992 (-42) 66,067 (+4) 44,268 (-1) 47,720 (0) 111,375 (-1)	+0.00% -0.98% -1.44% -1.32% -0.56% +0.01% -1.09% -0.03% +0.01% -0.00% 0.00% -0.00%	47,621 (0) 36,497 (-12) 985 (-6) 1,100 (-3) 1,191 (0) 25,832 (0) 76,103 (+34) 47,225 (+30) 71,205 (0) 44,280 (0) 49,885 (0) 111,387 (0)	0.00% -0.03% -0.61% -0.27% 0.00% 0.00% +0.04% +0.06% 0.00% 0.00% 0.00% 0.00%	47,621 (0) 876,434 (-14,021) 3,639 (+14) 3,873 (0) 4,055 (-14) 26,244 (0) 227,477 (+555) 425,942 (+303) 91,345 (0) 44,292 (0) 49,897 (0) 111,399 (0)	0.00% -1.57% +0.39% 0.00% -0.34% 0.00% +0.24% +0.07% 0.00% 0.00% 0.00% 0.00%	6,656 (0) 2,560 (0) 512 (0) 512 (0) 512 (0) 2,048 (0) 1,024 (0) 1,536 (0) 3,328 (0) 2,816 (0) 4,864 (0) 2,816 (0)
MailboxFacet	2,743,534 (0)	finalizeEthWithdrawal	8,251 (0)	0.00%	52,191 (+246)	+0.47%	52,735 (0)	0.00%	52,735 (0)	0.00%	257 (0)
ChainAdmin	784,876 (0)	setUpgradeTimestamp	25,361 (0)	0.00%	45,155 (-153)	-0.34%	45,321 (+12)	+0.03%	45,645 (0)	0.00%	256 (0)
DiamondProxy	2,405,277 (0)	finalizeEthWithdrawal requestL2Transaction util_setChainId	37,779 (0) 33,295 (0) 28,944 (0)	0.00% 0.00% 0.00%	79,512 (+237) 131,408 (+2) 33,784 (-31)	+0.30% +0.00% -0.09%	79,991 (-36) 170,024 (-12) 33,756 (0)	-0.04% -0.01% 0.00%	80,291 (0) 191,977 (0) 34,128 (0)	0.00% 0.00% 0.00%	257 (0) 771 (0) 519 (0)
L1NativeTokenVault	3,344,240 (+20,765)	bridgeBurn ensureTokenIsRegistered registerEthToken registerToken	12,777 (0) 731 (0) 94,973 (-11) 671 (0)	0.00% 0.00% -0.01% 0.00%	85,877 (+4) 113,993 (+191) 100,018 (-11) 122,000 (+94)	+0.00% +0.17% -0.01% +0.08%	100,649 (0) 116,177 (+195) 99,564 (-11) 122,453 (+95)	0.00% +0.17% -0.01% +0.08%	100,649 (0) 116,177 (+195) 106,695 (-11) 129,584 (+95)	0.00% +0.17% -0.01% +0.07%	1,299 (0) 261 (0) 880 (0) 881 (0)
MerkleTest	463,574 (0)	calculateRoot(bytes32[],uint256,bytes32)	571 (0)	0.00%	2,929 (-2)	-0.07%	2,982 (0)	0.00%	3,037 (+11)	+0.36%	265 (0)
TransparentUpgradeableProxy	846,950 (+202,575)	allowAdminImplementation registerEthToken registerToken setAllowedData setSelectorIsValidated	54,663 (0) 123,162 (-11) 29,007 (0) 55,427 (0) 54,738 (0)	0.00% -0.01% 0.00% 0.00% 0.00%	54,911 (+7) 128,207 (-11) 150,557 (+95) 56,462 (-19) 54,769 (-1)	+0.01% -0.01% +0.06% -0.03% -0.00%	55,035 (0) 127,753 (-11) 151,013 (+95) 56,096 (-12) 54,786 (0)	0.00% -0.01% +0.06% -0.02% 0.00%	55,035 (0) 134,884 (-11) 158,144 (+95) 58,247 (+24) 54,786 (0)	0.00% -0.01% +0.06% +0.04% 0.00%	258 (0) 880 (0) 881 (0) 257 (0) 258 (0)
PermanentRestriction	1,543,705 (0)	setAllowedData	26,818 (0)	0.00%	27,255 (-6)	-0.02%	27,089 (0)	0.00%	27,902 (0)	0.00%	257 (0)
TestnetERC20Token	640,427 (0)	approve mint transfer	24,272 (0) 34,031 (0) 46,377 (0)	0.00% 0.00% 0.00%	46,258 (-1) 61,798 (-1) 46,720 (+3)	-0.00% -0.00% +0.01%	46,220 (0) 68,255 (0) 46,641 (0)	0.00% 0.00% 0.00%	46,568 (0) 68,615 (0) 46,977 (0)	0.00% 0.00% 0.00%	1,527 (0) 1,704 (0) 257 (0)
MerkleTreeNoSort	534,636 (0)	getProof	2,594 (0)	0.00%	32,740 (+2)	+0.01%	33,193 (0)	0.00%	33,215 (0)	0.00%	277 (0)
AccessControlRestriction	1,329,782 (0)	grantRole setRequiredRoleForCall setRequiredRoleForFallback	51,166 (0) 48,687 (0) 48,037 (0)	0.00% 0.00% 0.00%	51,398 (-3) 49,934 (-1) 49,372 (+2)	-0.01% -0.00% +0.00%	51,538 (0) 49,059 (0) 48,409 (0)	0.00% 0.00% 0.00%	51,538 (0) 54,114 (0) 53,925 (0)	0.00% 0.00% 0.00%	1,024 (0) 1,280 (0) 1,280 (0)
DummyChainTypeManagerWBH	3,848,191 (0)	setZKChain	44,101 (0)	0.00%	44,138 (-1)	-0.00%	44,143 (-18)	-0.04%	44,161 (0)	0.00%	256 (0)
DeployL1Script	57,741,256 (+20,857)

[github-actions]

Coverage after merging ra/zk-as-gateway-token into release-v26-1 will be

83.70%

Coverage Report

File	Stmts	Branches	Funcs	Lines	Uncovered Lines
contracts/bridge
BridgeHelper.sol	76%	40%	100%	84.21%	29, 31, 34, 36, 39, 41
BridgedStandardERC20.sol	74.68%	25%	92.31%	77.59%	120–121, 126–127, 139–140, 163–164, 205, 205, 212, 212, 219, 219, 230, 62–63, 90–91
L1ERC20Bridge.sol	89.58%	66.67%	100%	91.43%	188–189, 207–208, 269
L1Nullifier.sol	77.97%	54.76%	86.21%	82.69%	115–116, 131, 131–132, 161–162, 222–223, 225–226, 235–236, 238–239, 248–249, 251–252, 418, 420–421, 421–422, 425–426, 426–427, 453–454, 519–520, 611–612, 649–652, 708, 711, 713, 726, 740, 745, 764–765
contracts/bridge/asset-router
AssetRouterBase.sol	90.24%	60%	100%	92.86%	58–59, 86–87
L1AssetRouter.sol	84.66%	62.50%	88.89%	89.23%	208–209, 245–247, 258, 260, 263, 361, 391–392, 435–437, 450–451, 553–554, 59–60, 654, 673, 75–76, 83–84
contracts/bridge/interfaces
AssetHandlerModifiers.sol	50%	0%	100%	50%	12–13
contracts/bridge/ntv
L1NativeTokenVault.sol	79.34%	62.07%	87.50%	84.21%	141, 144–145, 145, 145–147, 147, 147–149, 149, 149–150, 152, 207, 218, 220, 220, 220–221, 223, 236
NativeTokenVault.sol	83.87%	59.38%	92%	88.37%	101–102, 230–231, 235–236, 252–253, 270–271, 275–276, 290, 292, 310–311, 318–319, 483, 485, 499–500, 527–528, 562, 567, 73–74
contracts/bridgehub
Bridgehub.sol	77.65%	39.29%	93.18%	83.75%	115–116, 123–124, 130–131, 137, 137–138, 167, 182–183, 227–228, 230–231, 239–240, 249–250, 262–263, 277–278, 306–307, 330–331, 333–334, 399–400, 415–416, 446–447, 526–527, 608–609, 717–718, 722–723, 725–726, 730, 730–731, 735–736, 738–739, 778–779, 781–782, 796–797, 842–843, 845–846, 848–849, 883–884, 887–888, 890–891, 926, 931
CTMDeploymentTracker.sol	62.79%	0%	90%	69.23%	122–123, 128, 31–32, 39–40, 62–63, 89–90, 93–94, 97–98
MessageRoot.sol	88.89%	40%	100%	91.89%	121–122, 67–68, 88–89
contracts/common
ReentrancyGuard.sol	90%	66.67%	100%	92.86%	78–79
contracts/common/libraries
DataEncoding.sol	78.26%	50%	100%	81.48%	110, 118, 143, 156, 163, 172, 174, 177, 43, 45
DynamicIncrementalMerkle.sol	74.42%	100%	80%	72.22%	67–70, 72–74, 76–78
FullMerkle.sol	100%	100%	100%	100%
L2ContractHelper.sol	58.49%	0%	75%	67.57%	100–101, 106–107, 110–111, 125, 127, 127–128, 132, 132–133, 141, 71–72, 77–78, 81–82
Merkle.sol	96.43%	85.71%	100%	97.73%	81–82
MessageHashing.sol	100%	100%	100%	100%
SemVer.sol	100%	100%	100%	100%
SystemContractsCaller.sol	0%	0%	0%	0%	114, 122–125, 135–138, 138–139, 141, 141–142, 33, 33–34, 37, 45, 47, 49, 51, 53, 66, 66, 66, 69, 72, 75, 78, 89, 91, 93, 96, 98
UncheckedMath.sol	100%	100%	100%	100%
UnsafeBytes.sol	100%	100%	100%	100%
contracts/governance
AccessControlRestriction.sol	100%	100%	100%	100%
ChainAdmin.sol	95.24%	80%	100%	96.30%	38–39
ChainAdminOwnable.sol	39.29%	0%	40%	47.37%	27–28, 39–40, 47–48, 56–57, 63, 66, 78, 78–79, 81
Governance.sol	98.15%	94.74%	100%	98.55%	45–46
L2ProxyAdminDeployer.sol	0%	100%	0%	0%	17–18, 20
PermanentRestriction.sol	83.45%	67.86%	100%	85.57%	103–104, 111, 111–112, 200, 200–201, 204, 204–205, 208, 210, 210–211, 240, 242, 289–290, 311–312, 342–343
TransitionaryOwner.sol	0%	100%	0%	0%	17, 22–23
contracts/governance/restriction
Restriction.sol	100%	100%	100%	100%
RestrictionValidator.sol	100%	100%	100%	100%
contracts/state-transition
ChainTypeManager.sol	72.12%	22.22%	71.43%	80.36%	147–148, 150–151, 153–154, 156–157, 212–213, 243–244, 268, 292, 311, 318, 325, 333, 340, 348, 355, 371, 373, 434–435, 462–463, 469–470, 496–497, 544–545, 79, 94–95
TestnetVerifier.sol	77.78%	66.67%	100%	75%	16, 28
ValidatorTimelock.sol	92.06%	71.43%	100%	93.02%	186–187, 202, 78–79
Verifier.sol	89.90%	40%	96.30%	90.93%	1674–1675, 287–302, 305–308, 311–318, 321–328, 331–332, 335–336, 339, 383–384, 394–395, 405–406, 416–417, 427–428, 443–444, 453, 453–454, 905–906
contracts/state-transition/chain-deps
DiamondInit.sol	80.43%	50%	100%	88.24%	39–40, 42–43, 45–46, 48–49, 73
DiamondProxy.sol	92.31%	75%	100%	100%	19, 30
GatewayCTMDeployer.sol	0%	0%	0%	0%	156, 161–163, 165, 167, 169, 177, 179–180, 182–183, 185, 205, 208–209, 211, 217, 221–222, 235, 235, 235–236, 238, 255, 257, 259–260, 264, 266–268, 281, 284–286, 288–289, 295, 301, 307, 314, 324, 330, 332, 342, 349,