Spin up a sovereign rollup locally

Initialize a fully functional L3 appchain boilerplate for sovereign rollups on localhost. This setup enables testing of custom EVM logic, gas dynamics, and chain configuration without mainnet exposure.

Follow these steps to initialize the environment and start the node.

1
Clone the repository
Run git clone https://github.com/l3boilerplate/sovereign-rollup.git to fetch the latest boilerplate code. This template includes pre-configured OP Stack or Arbitrum Nitro components, depending on the branch you select.
2
Install dependencies
Navigate into the directory and run npm install or yarn to download the required packages. Ensure your Node.js version matches the engine requirement specified in the package.json file to avoid compilation errors.
3
Configure local chain settings
Copy the .env.example file to .env and set your local RPC endpoint. You can customize the initial state, gas limits, and block time to simulate specific L3 appchain boilerplate conditions.
4
Start the local node
Execute npm run start to spin up the sequencer and execution layer. The terminal will display the local RPC URL, typically http://127.0.0.1:8545 , where your new sovereign rollup is listening.
5
Verify the deployment
Use a tool like curl or a local block explorer to query the chain ID and block height. Confirm that the node is producing blocks and accepting transactions locally.

Once the node is running, you have an isolated L3 appchain boilerplate ready for development. You can now deploy smart contracts, test state transitions, and validate your rollup’s economic model before any public deployment.

Configure the L2 Settlement Layer

Setting up your L3 appchain boilerplate requires a direct link to its L2 settlement layer. This connection allows your chain to read data synchronously, ensuring that state changes on Layer 2 are immediately visible to your Layer 3 nodes. Without this synchronous read capability, your appchain operates in isolation, missing critical updates from the settlement layer.

Follow these steps to configure the settlement layer connection in your boilerplate environment.

1
Locate the settlement configuration file

Open your project directory and navigate to the configuration folder. Look for the file named settlement.config.ts or l2-bridge.json. This file defines the RPC endpoints and contract addresses your L3 needs to monitor.

2
Insert the L2 RPC endpoint

In the configuration file, find the rpcUrl field. Paste the public or private RPC endpoint for your chosen L2 network (e.g., Arbitrum, Optimism, or Base). This endpoint is the primary channel through which your L3 queries block data from the settlement layer.

3
Add the bridge contract address

Locate the bridgeContractAddress field. Enter the deployed address of the L2 bridge contract that manages asset transfers and state roots. This address tells your L3 where to look for the canonical state roots that prove transaction validity.

4
Enable synchronous data reading

Set the syncMode flag to true. This critical setting forces your L3 nodes to poll the L2 RPC at every block height, rather than relying on asynchronous batch updates. Synchronous reading ensures your appchain’s state remains tightly coupled with the settlement layer, preventing data divergence.

5
Verify the connection

Run the boilerplate’s verification script, typically npm run verify-settlement. This command attempts a live read from the L2 RPC using the provided bridge address. A successful output confirms that your L3 appchain boilerplate can now read settlement data in real-time.

By following this sequence, you establish a reliable, synchronous link between your L3 and its L2 settlement layer. This configuration is foundational for any L3 appchain boilerplate aiming for real-time data consistency.

Select your L2 provider and bridge

An L3 appchain boilerplate requires a Layer 2 network to handle settlement and security. Your choice of L2 dictates your gas costs, finality speed, and available developer tooling. Most L3s settle on Ethereum via Optimistic Rollups or ZK-Rollups. You must also configure a bridge to move assets from the L2 to your new L3 instance.

Compare L2 settlement layers

Not all L2s support L3 deployment equally. Starknet is currently the most mature environment for L3 appchains, offering native support for rollup contracts and specific bridge infrastructure. Other L2s like Arbitrum or Optimism may require custom bridge logic or additional security audits to support L3 settlement. Use the comparison below to evaluate your options based on technical fit.

ProviderRollup TypeL3 ReadinessBridge Maturity
StarknetZK-RollupHigh (Native)High
ArbitrumOptimisticMedium (Custom)High
OptimismOptimisticMedium (Custom)High
BaseOptimisticLow (Experimental)Medium

Configure the asset bridge

Once you select an L2, you need to bridge assets to your L3. This involves deploying a bridge contract on the L2 and connecting it to your L3 instance. For Starknet, use the official Starknet bridge or community-maintained bridges like Meson if native support is not yet fully integrated into your boilerplate. Ensure your bridge supports the token standard you plan to use (ERC-20 or ERC-721). Test the bridge with small amounts before mainnet deployment to verify finality times and security checks.

Integrate DevRel kits for adoption

Your L3 appchain boilerplate provides the infrastructure, but DevRel kits supply the social layer required for adoption. These kits bundle the marketing assets, documentation templates, and community engagement tools needed to onboard developers and users without rebuilding foundational resources from scratch.

The integration process follows a clear sequence. Start by cloning the official DevRel repository linked within your boilerplate documentation. This ensures your branding assets align with the chain’s identity guidelines.

1
Customize brand assets

Replace the default logos, color codes, and domain names in the kit’s configuration file. Ensure all visual elements reflect your specific appchain’s niche and target audience.

2
Configure community channels

Link the kit’s social templates to your Discord, Telegram, or X accounts. Set up automated welcome messages and role assignment scripts to handle new member onboarding.

3
Deploy documentation hub

Push the pre-built documentation structure to your static site generator. Populate the guides with your chain’s specific RPC endpoints, contract addresses, and faucet links.

4
Launch developer incentives

Activate the grant application forms and bug bounty trackers included in the kit. This signals to the developer community that your L3 appchain is actively seeking contributors.

By standardizing these adoption tasks, you reduce the time-to-market for your L3 appchain boilerplate. Developers can focus on smart contract logic while the DevRel kit handles the repetitive work of community setup and resource distribution.

Check your deployment with a live demo

Verify that your L3 appchain boilerplate is functioning correctly by observing the on-chain state in real time. The most reliable proof of a successful deployment is a live demonstration that shows the L3 synchronously reading data from its L2 settlement layer.

We recommend reviewing the Spire First Based L3 Appchain demo. This walkthrough illustrates the exact data flow you should expect to see in your own environment, confirming that the settlement layer integration is active and responsive.

Verify your L3 appchain setup

Before going live, ensure the L3 appchain boilerplate is running correctly on your localhost. A quick verification prevents deployment failures and ensures your sovereign rollup is ready for production.

  • Check that the node is syncing and blocks are being produced.
  • Confirm the RPC endpoint responds to health checks.
  • Verify the bridge contract is deployed and accessible.
  • Test a sample transaction to ensure end-to-end functionality.
  • Node syncing and block production
  • RPC health check
  • Bridge contract deployment
  • Sample transaction test

If any step fails, review the logs and adjust your configuration before proceeding.

Common questions about L3 appchain boilerplates