feat(init): support nitro contracts source overrides

README.md

@@ -180,6 +180,22 @@ pnpm dev bake \
   --push            # optional; docker login is your responsibility
 ```
 
+When rebuilding, `init` and `bake` can build the contract-deployer image from a
+nitro-contracts branch, tag, or commit instead of the Dockerfile's pinned commit:
+
+```bash
+pnpm dev init --rebuild --nitro-contracts-branch feature/my-change
+pnpm dev bake --rebuild \
+  --nitro-contracts-branch feature/my-change \
+  --setup-command "./scripts/deploy-and-seed.sh" \
+  --image-ref ghcr.io/acme/arbitrum-testnode:governance
+```
+
+For local development, set `NITRO_CONTRACTS_LOCAL_DIR` to a nitro-contracts checkout.
+The local checkout takes precedence over `--nitro-contracts-branch`. The
+`--nitro-contracts-version` option still selects the v2.1 or v3.2 deployer recipe;
+the source override only replaces the checkout used by that recipe.
+
 To bake straight from an existing snapshot (no setup step), use the à-la-carte
 subcommand:
 
@@ -208,7 +224,8 @@ job — log in before invoking it:
 ```
 
 By default the action installs a base snapshot release (via `github-token`) and
-restores it; set `rebuild: true` to run a full init instead.
+restores it; set `rebuild: true` to run a full init instead. Rebuilds also accept
+`nitro-contracts-branch`, `nitro-contracts-version`, and `fee-token-decimals`.
 
 ### Booting a custom image
 

apps/cli/src/commands/bake.ts

@@ -56,13 +56,35 @@ const bakeOptions = z.object({
 		.string()
 		.optional()
 		.describe("Nitro contracts version for a rebuild init (e.g. v2.1, v3.2)"),
+	nitroContractsBranch: z
+		.string()
+		.optional()
+		.describe(
+			"Build the core rollup contracts from this nitro-contracts branch, tag, or commit for a rebuild init",
+		),
 	feeTokenDecimals: z
 		.number()
 		.optional()
 		.describe("Custom fee token decimals (6, 16, 18, or 20) for a rebuild init"),
 	timeboostEnabled: z.boolean().optional().describe("Enable Timeboost for a rebuild init"),
 });
 
+function rebuildInitOptions(options: z.infer<typeof bakeOptions>) {
+	return {
+		rebuild: true,
+		...(options.nitroContractsBranch ? { nitroContractsBranch: options.nitroContractsBranch } : {}),
+		...(options.nitroContractsVersion
+			? { nitroContractsVersion: options.nitroContractsVersion }
+			: {}),
+		...(options.feeTokenDecimals !== undefined
+			? { feeTokenDecimals: options.feeTokenDecimals }
+			: {}),
+		...(options.timeboostEnabled !== undefined
+			? { timeboostEnabled: options.timeboostEnabled }
+			: {}),
+	};
+}
+
 /**
  * Boot the base stack the customization runs against. `--rebuild` runs a full
  * init; otherwise the installed base snapshot is restored and started, mirroring
@@ -75,21 +97,7 @@ async function ensureBaseStack(
 	options: z.infer<typeof bakeOptions>,
 ): Promise<void> {
 	if (options.rebuild) {
-		await runInitCommand(
-			{
-				rebuild: true,
-				...(options.nitroContractsVersion
-					? { nitroContractsVersion: options.nitroContractsVersion }
-					: {}),
-				...(options.feeTokenDecimals !== undefined
-					? { feeTokenDecimals: options.feeTokenDecimals }
-					: {}),
-				...(options.timeboostEnabled !== undefined
-					? { timeboostEnabled: options.timeboostEnabled }
-					: {}),
-			},
-			createInitContext(root),
-		);
+		await runInitCommand(rebuildInitOptions(options), createInitContext(root));
 		return;
 	}
 

apps/cli/src/commands/init.ts

@@ -18,6 +18,12 @@ export const initCli = Cli.create("init", {
 			.optional()
 			.describe("Deploy a custom fee token ERC20 on L2 with this many decimals (6, 16, 18, or 20)"),
 		foreground: z.boolean().optional().describe("Internal worker mode for detached init runs"),
+		nitroContractsBranch: z
+			.string()
+			.optional()
+			.describe(
+				"Build the core rollup contracts from this nitro-contracts branch, tag, or commit instead of the pinned default",
+			),
 		nitroContractsVersion: z
 			.string()
 			.optional()

bake/action.yml

@@ -41,6 +41,18 @@ inputs:
     required: false
     default: "v3.2"
     description: "Nitro contracts version passed through to a rebuild init"
+  nitro-contracts-branch:
+    required: false
+    default: ""
+    description: >-
+      Build the core rollup contracts from this nitro-contracts branch/commit
+      (instead of the pinned default) during a rebuild init. Empty = pinned default.
+  fee-token-decimals:
+    required: false
+    default: ""
+    description: >-
+      Custom L3 fee-token decimals (6, 16, 18, or 20) for a rebuild init.
+      Empty = ETH-fee (no custom fee token).
   github-token:
     required: false
     default: ""
@@ -92,6 +104,10 @@ runs:
       shell: bash
       working-directory: ${{ github.action_path }}/..
       env:
+        BASE_SNAPSHOT_ID_INPUT: ${{ inputs.base-snapshot-id }}
+        FEE_TOKEN_DECIMALS_INPUT: ${{ inputs.fee-token-decimals }}
+        NITRO_CONTRACTS_BRANCH_INPUT: ${{ inputs.nitro-contracts-branch }}
+        NITRO_CONTRACTS_VERSION_INPUT: ${{ inputs.nitro-contracts-version }}
         TOKEN_BRIDGE_COMMIT: 5975d8f7360816341be7f94fd333ef240f4aec23
         TOKEN_BRIDGE_LOCAL_DIR: ${{ runner.temp }}/token-bridge-contracts
       run: |
@@ -109,10 +125,17 @@ runs:
             yarn build
           )
         fi
-        base="${{ inputs.base-snapshot-id }}"
+        base="$BASE_SNAPSHOT_ID_INPUT"
+        init_args=(--rebuild --capture-id "$base" --skip-post-capture-verify)
+        init_args+=(--nitro-contracts-version "$NITRO_CONTRACTS_VERSION_INPUT")
+        if [ -n "$NITRO_CONTRACTS_BRANCH_INPUT" ]; then
+          init_args+=(--nitro-contracts-branch "$NITRO_CONTRACTS_BRANCH_INPUT")
+        fi
+        if [ -n "$FEE_TOKEN_DECIMALS_INPUT" ]; then
+          init_args+=(--fee-token-decimals "$FEE_TOKEN_DECIMALS_INPUT")
+        fi
         for attempt in 1 2 3; do
-          if node apps/cli/dist/index.js init --rebuild --capture-id "$base" \
-               --skip-post-capture-verify \
+          if node apps/cli/dist/index.js init "${init_args[@]}" \
              && test -f "config/snapshots/$base/manifest.json"; then
             echo "base snapshot '$base' captured"
             exit 0

docker/contract-deployer-v2.1.Dockerfile

@@ -1,5 +1,35 @@
+# Nitro-contracts source is selectable so consumers can bake an image against
+# their own branch/commit (NITRO_CONTRACTS_BRANCH) or a local checkout
+# (NITRO_CONTRACTS_SOURCE=local + `--build-context nitrocontracts=<dir>`).
+# Defaults reproduce the pinned upstream v2.1 commit.
+ARG NITRO_CONTRACTS_SOURCE=git
+ARG NITRO_CONTRACTS_BRANCH=f9cd1aa4b5bba209211e8df9993e0eba89eaedda
+
 FROM ghcr.io/foundry-rs/foundry:v1.3.1 AS foundry
 
+# Source stage: fetch nitro-contracts from git at the requested ref.
+FROM node:20-trixie-slim AS nitro-src-git
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+WORKDIR /workspace/nitro-contracts
+ARG NITRO_CONTRACTS_BRANCH
+RUN git init . \
+    && git remote add origin https://github.com/OffchainLabs/nitro-contracts.git \
+    && git fetch --depth 1 origin "$NITRO_CONTRACTS_BRANCH" \
+    && git checkout --detach FETCH_HEAD \
+    && git submodule update --init --recursive --depth 1
+
+# Fallback for builds without a named context. Passing
+# `--build-context nitrocontracts=<dir>` overrides this same-named stage.
+FROM scratch AS nitrocontracts
+
+# Source stage: use a local checkout supplied via `--build-context nitrocontracts=<dir>`.
+FROM node:20-trixie-slim AS nitro-src-local
+WORKDIR /workspace/nitro-contracts
+COPY --from=nitrocontracts . /workspace/nitro-contracts
+
+# Select the active source (git by default, local when NITRO_CONTRACTS_SOURCE=local).
+FROM nitro-src-${NITRO_CONTRACTS_SOURCE} AS nitro-src
+
 FROM node:20-trixie-slim AS nitro-builder
 
 COPY --from=foundry /usr/local/bin/forge /usr/local/bin/forge
@@ -8,11 +38,7 @@ RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /workspace/nitro-contracts
 
-RUN git init . \
-    && git remote add origin https://github.com/OffchainLabs/nitro-contracts.git \
-    && git fetch --depth 1 origin f9cd1aa4b5bba209211e8df9993e0eba89eaedda \
-    && git checkout --detach FETCH_HEAD \
-    && git submodule update --init --recursive --depth 1
+COPY --from=nitro-src /workspace/nitro-contracts /workspace/nitro-contracts
 
 RUN cp scripts/config.ts.example scripts/config.ts
 RUN yarn install --frozen-lockfile

docker/contract-deployer.Dockerfile

@@ -1,5 +1,35 @@
+# Nitro-contracts source is selectable so consumers can bake an image against
+# their own branch/commit (NITRO_CONTRACTS_BRANCH) or a local checkout
+# (NITRO_CONTRACTS_SOURCE=local + `--build-context nitrocontracts=<dir>`).
+# Defaults reproduce the pinned upstream commit.
+ARG NITRO_CONTRACTS_SOURCE=git
+ARG NITRO_CONTRACTS_BRANCH=cd4eb69e3c4cb87161b1433ad238902ea5c32ebd
+
 FROM ghcr.io/foundry-rs/foundry:v1.3.1 AS foundry
 
+# Source stage: fetch nitro-contracts from git at the requested ref.
+FROM node:20-trixie-slim AS nitro-src-git
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+WORKDIR /workspace/nitro-contracts
+ARG NITRO_CONTRACTS_BRANCH
+RUN git init . \
+    && git remote add origin https://github.com/OffchainLabs/nitro-contracts.git \
+    && git fetch --depth 1 origin "$NITRO_CONTRACTS_BRANCH" \
+    && git checkout --detach FETCH_HEAD \
+    && git submodule update --init --recursive --depth 1
+
+# Fallback for builds without a named context. Passing
+# `--build-context nitrocontracts=<dir>` overrides this same-named stage.
+FROM scratch AS nitrocontracts
+
+# Source stage: use a local checkout supplied via `--build-context nitrocontracts=<dir>`.
+FROM node:20-trixie-slim AS nitro-src-local
+WORKDIR /workspace/nitro-contracts
+COPY --from=nitrocontracts . /workspace/nitro-contracts
+
+# Select the active source (git by default, local when NITRO_CONTRACTS_SOURCE=local).
+FROM nitro-src-${NITRO_CONTRACTS_SOURCE} AS nitro-src
+
 FROM node:20-trixie-slim AS nitro-builder
 
 COPY --from=foundry /usr/local/bin/forge /usr/local/bin/forge
@@ -8,11 +38,7 @@ RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /workspace/nitro-contracts
 
-RUN git init . \
-    && git remote add origin https://github.com/OffchainLabs/nitro-contracts.git \
-    && git fetch --depth 1 origin cd4eb69e3c4cb87161b1433ad238902ea5c32ebd \
-    && git checkout --detach FETCH_HEAD \
-    && git submodule update --init --recursive --depth 1
+COPY --from=nitro-src /workspace/nitro-contracts /workspace/nitro-contracts
 
 RUN cp scripts/config.example.ts scripts/config.ts
 RUN yarn install --frozen-lockfile