docs: tw320-arbitrum-chain-increase-smart-contract-size-limit

docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/11-smart-contract-size-limit.mdx

@@ -7,3 +7,42 @@ content_type: how-to
 tags: ['hide-from-search']
 unlisted: true
 ---
+
+For standard public Arbitrum chains (such as Arbitrum One or Nova), the smart contract code size limit has been set at 24 kB, as enforced by [EIP-170](https://eips.ethereum.org/EIPS/eip-170). This limit is not configurable for end-users or developers deploying contracts on these chains.
+
+However, if you're launching a custom Arbitrum chain (L2/L3), the limit can be increased up to 96 kB.
+
+## Why the limit?
+
+The limit exists because larger contracts require more resources to process and verify, making them potential vectors for denial-of-service (DoS) attacks if not properly constrained. EIP-170, which addressed the issue of smart contract size, was designed with this in mind.
+
+## Benefits of increasing the smart contract size limit
+
+Increasing the smart contract code size limit (from the default 24 kB up to 96 kB) enables greater flexibility in development, particularly for complex applications. Key benefits include:
+
+<!-- these benefits seem to be targeted towards the developer team not the chain owner, who is the target audience -->
+
+- **Support for more complex and feature-rich contracts**: Larger contracts can incorporate extensive logic, libraries, and functionality without the need to split code across multiple contracts. This consolidation is helpful for applications such as DeFi protocols, games, or enterprise solutions that require intricate computations or integrations, thereby reducing the need for workarounds like proxy patterns.
+- **Reduced gas costs for execution**: By consolidating code into a single contract, you avoid expensive inter-contract calls (e.g., via proxies or delegates), which can lower overall runtime gas consumption. Proxy patterns, often used to bypass size limits, add overhead and increase the cost of calls.
+- **Simplified development and maintenance**: Developers can write cleaner, more modular code without artificial splitting, making it easier to audit, debug, and upgrade contracts. Cleaner code streamlines the development process and reduces complexity in reasoning about the codebase.
+- **Enhanced customization for specific use cases**: On Arbitrum (Orbit) chains, this aligns with other customizations (e.g., gas tokens or block times), enabling tailored environments for high-throughput needs, such as gaming or AI-driven apps, where larger contracts can handle domain-specific logic efficiently.
+
+## Drawbacks of increasing the smart contract size limit
+
+While beneficial for complexity, raising the limit introduces trade-offs, particularly in costs, security, and performance. These are more pronounced in Rollup environments, such as Arbitrum, where transactions get posted to the Ethereum Layer 1.
+
+- **Performance and network efficiency concerns**: Although EVM execution charges gas per opcode (not code size), large contracts could lead to slower node processing or higher resource demands on validators/sequencers. This slower processing might exacerbate DoS risks on your chain, as the purpose of the EIP-170 limit was to mitigate such issues.
+- **Compatibility and portability issues**: Contracts exceeding the standard 24 kB limit (enforced on public chains like Arbitrum One or Ethereum) cannot be deployed elsewhere without modifications. This restriction limits interoperability and could lock you into your Arbitrum (Orbit) chain, reducing flexibility if you need to migrate in the future.
+- **Irreversibility**: The limit must be set during initial chain configuration and cannot be changed post-deployment, so poor choices could lead to long-term inefficiencies.
+  Overall, increasing the limit is ideal for specialized Arbitrum chains where complexity outweighs costs, but we recommend sticking to defaults unless necessary.
+- **Higher contract deployment costs (users)**: Larger contracts require more bytecode in the initialization code, which increases the transaction size and, consequently, the calldata costs posted to Ethereum L1. In Rollups, this can significantly raise deployment fees, as costs scale with data size for users.
+
+## How to configure
+
+1. Use the [Arbitrum chain (Orbit) SDK](https://github.com/OffchainLabs/arbitrum-orbit-sdk) to prepare your chain's configuration.
+2. When calling the `prepareNodeConfig` function, modify the relevant parameters: [`MaxCodeSize`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/9fd3d39504832f94a31d9c5773f4514bd7be6eee/src/prepareChainConfig.ts#L29) for deployed contract code size, and [`MaxInitCodeSize`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/9fd3d39504832f94a31d9c5773f4514bd7be6eee/src/prepareChainConfig.ts#L30) for initialization code size during deployment.
+3. These parameters are defined in the SDK's [`prepareChainConfig.ts`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29) file. An example implementation is available in the SDK's [`examples/prepare-node-config/index.ts`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/examples/prepare-node-config/index.ts).
+<!-- I'm not sure this example above in #3 is correct -->
+4. Note that once the chain deploys, the smart contract limits are unchangeable via upgrades—you must set them during initial configuration.
+
+This customization applies to both EVM-compatible contracts and Stylus (WebAssembly-based) contracts on Arbitrum chains. However, Stylus contracts must also adhere to compression limits (e.g., 24 kB Brotli-compressed in some cases, with potentially higher uncompressed equivalents of ~128 kB, depending on the setup). You can learn more about [Stylus in this section](/stylus/gentle-introduction.mdx).

sidebars.js

@@ -315,6 +315,11 @@ const sidebars = {
                   id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/enable-post-4844-blobs',
                   label: `Enable blob transactions`,
                 },
+                {
+                  type: 'doc',
+                  id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/smart-contract-size-limit',
+                  label: `Configure the smart contract size limit`,
+                },
                 {
                   type: 'doc',
                   id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/arbitrum-chain-finality',