Port docs to kl/sync-layer-reorg

[StanislavBreadless]

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: 85872b09bf73377266080cac5e5795d096111737, compared to commit: bc4674b4f1a295ce4bba157f6893e80eebaf5618

🧾 Summary (100% most significant diffs)

Contract	Method	Avg (+/-)	%
DummyBridgehubSetter	addChainTypeManager createNewChain requestL2TransactionDirect requestL2TransactionTwoBridges setZKChain	+3 ❌ -691 ✅ +3,847 ❌ +22 ❌ +30 ❌	+0.01% -0.64% +3.32% +0.01% +0.03%
ChainAdmin	setUpgradeTimestamp	+159 ❌	+0.35%
DiamondProxy	finalizeEthWithdrawal requestL2Transaction	-252 ✅ -1 ✅	-0.32% -0.00%
TransparentUpgradeableProxy	setAllowedAdminImplementation setAllowedData	-5 ✅ -41 ✅	-0.01% -0.07%
MerkleTest	calculateRoot(bytes32[],uint256,bytes32)	-2 ✅	-0.07%
TestnetERC20Token	approve transfer	+5 ❌ +15 ❌	+0.01% +0.03%
Bridgehub	createNewChain	+30 ❌	+0.00%

---

Full diff report 👇

Contract	Deployment Cost (+/-)	Method	Min (+/-)	%	Avg (+/-)	%	Median (+/-)	%	Max (+/-)	%	# Calls (+/-)
DummyBridgehubSetter	4,350,895 (+3,540)	addChainTypeManager createNewChain proveL1ToL2TransactionStatus proveL2LogInclusion proveL2MessageInclusion removeChainTypeManager requestL2TransactionDirect requestL2TransactionTwoBridges setAddresses setPendingAdmin setZKChain	23,907 (+12) 28,613 (-96) 0 (0) 0 (0) 0 (0) 23,854 (0) 33,044 (+24) 31,023 (-12) 24,370 (0) 25,999 (0) 111,369 (+30)	+0.05% -0.33% +∞% +∞% +∞% 0.00% +0.07% -0.04% 0.00% 0.00% +0.03%	44,150 (+3) 106,519 (-691) 1,407 (+3) 1,499 (-23) 1,592 (-23) 25,491 (+6) 119,695 (+3,847) 151,432 (+22) 66,088 (+3) 47,721 (+1) 111,406 (+30)	+0.01% -0.64% +0.21% -1.51% -1.42% +0.02% +3.32% +0.01% +0.00% +0.00% +0.03%	47,621 (0) 36,509 (0) 985 (-3) 1,100 (0) 1,194 (0) 25,854 (0) 96,715 (+4,071) 47,057 (+90) 71,227 (0) 49,885 (0) 111,417 (+30)	0.00% 0.00% -0.30% 0.00% 0.00% 0.00% +4.39% +0.19% 0.00% 0.00% +0.03%	47,621 (0) 871,479 (-2,880) 3,639 (0) 3,873 (0) 4,062 (+7) 26,266 (0) 298,752 (+3,494) 434,646 (+36) 91,367 (0) 49,897 (0) 111,429 (+30)	0.00% -0.33% 0.00% 0.00% +0.17% 0.00% +1.18% +0.01% 0.00% 0.00% +0.03%	6,656 (0) 2,560 (0) 512 (0) 512 (0) 512 (0) 2,048 (0) 1,024 (0) 1,536 (0) 3,328 (0) 4,864 (0) 2,816 (0)
MailboxFacet	2,681,325 (0)	finalizeEthWithdrawal	8,251 (0)	0.00%	52,191 (-247)	-0.47%	52,735 (0)	0.00%	52,735 (0)	0.00%	257 (0)
ChainAdmin	835,016 (0)	setUpgradeTimestamp	25,361 (0)	0.00%	45,314 (+159)	+0.35%	45,345 (+36)	+0.08%	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,511 (-252) 131,440 (-1) 33,789 (+19)	-0.32% -0.00% +0.06%	79,991 (-24) 170,024 (-12) 33,756 (0)	-0.03% -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)
TransparentUpgradeableProxy	644,397 (0)	setAllowedAdminImplementation setAllowedData setSelectorShouldBeValidated	54,675 (-12) 55,405 (0) 54,726 (0)	-0.02% 0.00% 0.00%	54,925 (-5) 56,491 (-41) 54,756 (+3)	-0.01% -0.07% +0.01%	55,047 (0) 56,098 (-84) 54,774 (0)	0.00% -0.15% 0.00%	55,047 (0) 58,213 (-12) 54,774 (0)	0.00% -0.02% 0.00%	258 (0) 257 (0) 258 (0)
MerkleTest	436,733 (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)
TestnetERC20Token	640,427 (0)	approve mint transfer	24,272 (0) 34,031 (0) 46,377 (0)	0.00% 0.00% 0.00%	46,263 (+5) 61,803 (+5) 46,735 (+15)	+0.01% +0.01% +0.03%	46,232 (+12) 68,255 (0) 46,689 (+36)	+0.03% 0.00% +0.08%	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,742 (+6)	+0.02%	33,193 (0)	0.00%	33,215 (0)	0.00%	277 (0)
L1NativeTokenVault	3,438,536 (0)	bridgeBurn	12,799 (0)	0.00%	89,762 (-16)	-0.02%	106,025 (0)	0.00%	106,025 (0)	0.00%	1,299 (0)
AccessControlRestriction	1,357,213 (0)	grantRole setRequiredRoleForCall setRequiredRoleForFallback	51,277 (0) 24,360 (0) 24,219 (0)	0.00% 0.00% 0.00%	51,512 (+1) 45,731 (-3) 45,238 (-8)	+0.00% -0.01% -0.02%	51,649 (0) 49,094 (0) 48,444 (0)	0.00% 0.00% 0.00%	51,649 (0) 54,114 (0) 53,925 (0)	0.00% 0.00% 0.00%	1,024 (0) 1,536 (0) 1,536 (0)
TestPermanentRestriction	1,450,178 (0)	setAllowedData	26,796 (0)	0.00%	27,253 (-2)	-0.01%	27,067 (0)	0.00%	27,880 (0)	0.00%	257 (0)
DummyChainTypeManagerWBH	3,803,370 (-13,602)	setZKChain	44,101 (0)	0.00%	44,139 (-1)	-0.00%	44,161 (0)	0.00%	44,161 (0)	0.00%	256 (0)
Bridgehub	4,320,479 (+2,351)	createNewChain	3,984,428 (+30)	+0.00%	3,984,428 (+30)	+0.00%	3,984,428 (+30)	+0.00%	3,984,428 (+30)	+0.00%	23 (0)
DummyChainTypeManager	3,801,620 (-13,604)
ChainTypeManager	3,781,333 (-13,628)
ValidatorTimelock	793,773 (-12)
DeployL1Script	58,577,335 (-11,335)
TestExecutorFacet	2,734,318 (-12)
TestBaseFacet	149,615 (+24)