Make L2 predeploys configurable via --l2-predeploy-json for opstack genesis #218

rayyan224 · 2025-12-01T16:26:55Z

Description 👨‍💻 ;

This PR adds support for passing in JSON files that define contracts you want predeployed at genesis. For the opstack recipe, we sometimes need to inject contract bytecode + metadata directly into the L2 alloc, and this gives us a simple, configurable way to do that.

We now have a generic JSON-driven predeploy flow, and the existing EntryPoint v0.7 JSON is wired through this new path. Anyone who needs things like ERC-4337 EntryPoint, paymasters, or other system contracts can just pass in JSON paths and have them included deterministically during genesis.

Copilot

Pull request overview

This PR adds a configurable mechanism for deploying contracts at genesis via JSON files for the opstack recipe. It replaces the previous --enable-entrypoint flag with a more generic and extensible --l2-predeploy-json flag that accepts JSON file paths describing L2 predeploy accounts.

Key changes:

Introduces a JSON-driven predeploy mechanism allowing users to inject custom contracts into L2 genesis
Adds PredeployAlloc struct and loadPredeployAlloc() function to parse and validate JSON predeploy configurations
Wires the existing ERC-4337 EntryPoint v0.7 JSON through this new mechanism

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
`playground/utils/entrypoint_v0.7.json`	Adds JSON configuration for ERC-4337 EntryPoint v0.7 contract to be deployed at genesis
`playground/artifacts.go`	Implements `PredeployAlloc` type, `loadPredeployAlloc()` parser, and integrates predeploy JSON files into L2 genesis alloc
`playground/recipe_opstack.go`	Adds `--l2-predeploy-json` flag and wires it to the artifacts builder
`README.md`	Documents the new `--l2-predeploy-json` flag with usage examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

Copilot · 2025-12-01T16:31:23Z

playground/artifacts.go

+	}
+	if p.Address == "" {
+		return "", nil, fmt.Errorf("predeploy JSON missing address")
+	}


The address field should be validated to ensure it's a valid Ethereum address. Currently, any string can be passed and will be directly inserted into the genesis alloc, which could lead to invalid genesis configuration if an improperly formatted address is provided.

Consider adding validation:

if !gethcommon.IsHexAddress(p.Address) { return "", nil, fmt.Errorf("predeploy JSON has invalid address format: %q", p.Address) }

Suggested change

}

}

if !gethcommon.IsHexAddress(p.Address) {

return "", nil, fmt.Errorf("predeploy JSON has invalid address format: %q", p.Address)

}

Copilot · 2025-12-01T16:31:24Z

playground/artifacts.go

+	account := map[string]interface{}{
+		"balance": p.Balance,
+		"nonce":   p.Nonce,


The Balance and Nonce fields are always included in the genesis alloc account, even when they're empty strings. This could potentially lead to invalid genesis data. Consider handling empty values more explicitly:

account := map[string]interface{}{} if p.Balance != "" { account["balance"] = p.Balance } if p.Nonce != "" { account["nonce"] = p.Nonce }

Or set default values if these fields should always be present:

account := map[string]interface{}{ "balance": p.Balance, "nonce": p.Nonce, } if p.Balance == "" { account["balance"] = "0x0" } if p.Nonce == "" { account["nonce"] = "0x0" }

Suggested change

account := map[string]interface{}{

"balance": p.Balance,

"nonce": p.Nonce,

balance := p.Balance

if balance == "" {

balance = "0x0"

}

nonce := p.Nonce

if nonce == "" {

nonce = "0x0"

}

account := map[string]interface{}{

"balance": balance,

"nonce": nonce,

Copilot · 2025-12-01T16:31:24Z

playground/artifacts.go

+	var p PredeployAlloc
+	if err := json.Unmarshal(raw, &p); err != nil {
+		return "", nil, fmt.Errorf("failed to unmarshal predeploy JSON: %w", err)
+	}
+	if p.Address == "" {
+		return "", nil, fmt.Errorf("predeploy JSON missing address")
+	}
+
+	account := map[string]interface{}{
+		"balance": p.Balance,
+		"nonce":   p.Nonce,
+	}
+	if p.Code != "" {
+		account["code"] = p.Code
+	}
+	if len(p.Storage) > 0 {
+		account["storage"] = p.Storage
+	}
+
+	return p.Address, account, nil


The hex values (balance, nonce, code) from the JSON are not validated to ensure they're properly formatted hex strings. Invalid hex values would be silently passed through to the genesis alloc, which could cause issues when the genesis is processed.

Consider adding validation for hex string fields:

// After unmarshaling if p.Balance != "" && !isValidHex(p.Balance) { return "", nil, fmt.Errorf("predeploy JSON has invalid balance hex format: %q", p.Balance) } if p.Nonce != "" && !isValidHex(p.Nonce) { return "", nil, fmt.Errorf("predeploy JSON has invalid nonce hex format: %q", p.Nonce) } if p.Code != "" && !isValidHex(p.Code) { return "", nil, fmt.Errorf("predeploy JSON has invalid code hex format: %q", p.Code) }

Where isValidHex checks for "0x" prefix and valid hex characters.

Copilot · 2025-12-01T16:31:24Z

playground/artifacts.go

+			if err != nil {
+				return nil, fmt.Errorf("failed to load L2 predeploy from %q: %w", path, err)
+			}
+


If multiple predeploy JSON files specify the same address, the later file will silently overwrite the earlier one without any warning. This could lead to unexpected behavior where one predeploy contract unintentionally replaces another.

Consider adding a check for duplicate addresses:

for _, path := range b.predeployJSONFiles { data, err := os.ReadFile(path) if err != nil { return nil, fmt.Errorf("failed to read L2 predeploy JSON %q: %w", path, err) } addr, account, err := loadPredeployAlloc(data) if err != nil { return nil, fmt.Errorf("failed to load L2 predeploy from %q: %w", path, err) } if _, exists := allocs[addr]; exists { return nil, fmt.Errorf("duplicate predeploy address %s found in %q", addr, path) } allocs[addr] = account }

Suggested change

if _, exists := allocs[addr]; exists {

return nil, fmt.Errorf("duplicate predeploy address %s found in %q", addr, path)

}

chunter-cb · 2025-12-01T17:14:48Z

playground/utils/entrypoint_v0.7.json

@@ -0,0 +1,7 @@
+{


Would be great if we could deploy v06 - v09, and either a factory or an account to test on for each.

My thinking is users, can have there own jsons that they pass the path in via params on startup.
WDYT ?

chunter-cb · 2025-12-01T17:15:44Z

README.md


 - `--external-builder`: URL of an external builder to use (enables rollup-boost)
 - `--enable-latest-fork` (int): Enables the latest fork (isthmus) at startup (0) or n blocks after genesis.
+- `--l2-predeploy-json` (string[]): One or more paths to JSON files describing L2 predeploy accounts to inject into the L2 genesis (e.g. EntryPoint, paymasters, custom system contracts).


I think just calling it use-predeploys or something (L2 seems irrelevant)

hmm, main thinking was because this adds it to the genesis of the l2 config, not l1. The repo deploys both an L1 and an L2. This mechanism only affects the L2 genesis config

But since this flag is unique for the L2 recipe, that already includes the context that this flag only runs there so it makes more sense to me to call it --predeploy-json only and remove that namespace since it is inferred.

Hmmm ok, sure!

ferranbt · 2025-12-02T11:24:01Z

playground/artifacts.go


+// PredeployAlloc is a generic JSON schema for describing a single L2
+// predeploy account to be injected into the L2 genesis alloc.
+type PredeployAlloc struct {


There is already an alloc.GeneissAccount object in the go-ethereum repo with this data and the unmarshal/marshal methods. Ideally we can use that instead of this custom format.

Ahhh didn't know about that one, nice find catch

ferranbt · 2025-12-05T16:00:42Z

playground/utils/entrypoint_v07.json

@@ -0,0 +1,9 @@
+{


What is this file?

This a config for launching an entry point v07 contract for 4437

Rayyan Alam added 6 commits December 1, 2025 09:55

feat: create flag for entry point

7649ed1

feat: create entry point v0.7 entry point byte code

f994fbf

feat: create artificats go

817543f

chore: update read me

a2e12c8

chore: hide json

a517f4a

chore: clean up

7832dad

Copilot AI review requested due to automatic review settings December 1, 2025 16:26

Copilot started reviewing on behalf of rayyan224 December 1, 2025 16:27 View session

chore: cleanup

1b95840

Copilot finished reviewing on behalf of rayyan224 December 1, 2025 16:29

Copilot AI reviewed Dec 1, 2025

View reviewed changes

Rayyan Alam added 3 commits December 1, 2025 11:41

chore: add check for dupplicates

17f732e

chore: update artifiacts

17f990e

chore: update artificats go

e4ebdb8

chunter-cb reviewed Dec 1, 2025

View reviewed changes

chore: remove entry point json

115a0d4

ferranbt reviewed Dec 2, 2025

View reviewed changes

feat: update to use geneis alloc and op stack

a9a7dd4

rayyan224 requested a review from ferranbt December 3, 2025 14:52

ferranbt reviewed Dec 5, 2025

View reviewed changes

ferranbt mentioned this pull request Dec 5, 2025

Adding possibility to add more prefunded accounts #221

Open

-	}
+	}
+	if !gethcommon.IsHexAddress(p.Address) {
+		return "", nil, fmt.Errorf("predeploy JSON has invalid address format: %q", p.Address)
+	}

-	account := map[string]interface{}{
-		"balance": p.Balance,
-		"nonce":   p.Nonce,
+	balance := p.Balance
+	if balance == "" {
+		balance = "0x0"
+	}
+	nonce := p.Nonce
+	if nonce == "" {
+		nonce = "0x0"
+	}
+	account := map[string]interface{}{
+		"balance": balance,
+		"nonce":   nonce,

+			if _, exists := allocs[addr]; exists {
+				return nil, fmt.Errorf("duplicate predeploy address %s found in %q", addr, path)
+			}

Make L2 predeploys configurable via --l2-predeploy-json for opstack genesis #218

Are you sure you want to change the base?

Make L2 predeploys configurable via --l2-predeploy-json for opstack genesis #218

Conversation

rayyan224 commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description 👨‍💻 ;

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rayyan224 Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rayyan224 Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rayyan224 commented Dec 1, 2025 •

edited

Loading

rayyan224 Dec 1, 2025 •

edited

Loading

rayyan224 Dec 3, 2025 •

edited

Loading