Nethermind.Arbitrum.Precompiles 2.0.1

Nethermind.Arbitrum.Precompiles

Auto-generated .NET ABI metadata for Arbitrum precompiles, regenerated on every PR from a pinned Arbitrum Nitro submodule.

The package exists to remove a single class of bug: ABI drift between Nethermind's .NET Arbitrum implementation and the Solidity interfaces in Nitro. Arbitrum precompiles (ArbSys, ArbGasInfo, ArbOwner, …) are EVM-callable system contracts whose method selectors, event topics, and error selectors are defined upstream in Nitro. Hand-copying these from Foundry artifacts is fragile — a forgotten regeneration after a Nitro bump silently ships stale metadata. This repo's job is to make that bug structurally impossible: bump the submodule pin, CI regenerates, drift is autocommitted (or refused on forks), and the published NuGet always matches its pinned Nitro commit.

How It Works

The repository is a small generator wrapped in a strict CI invariant.

• One generated .g.cs per precompile. Each file (e.g., Generated/ArbSys.g.cs) exposes nested static Methods, Functions, Events, and Errors with constants extracted from the Solidity interface. The library project ships only generated code plus a handful of descriptor types — no runtime logic.
• Foundry is the source of truth. forge build produces JSON artifacts from the pinned Nitro submodule; the generator parses them and emits C#.
• Hashes are pre-computed at generation time. Event topic0 strings and 4-byte error selectors are baked in via BouncyCastle's KeccakDigest(256), so the consumer never runs Keccak at startup.
• CI enforces the invariant. Every PR runs make generate and either commits drift back (same-repo PRs) or fails with a hint (fork PRs). Generated files in git always match the pinned Nitro.

The consumer (Nethermind Arbitrum) wires these constants into its own dispatch tables, business logic, and event/error encoding. This package owns ABI metadata; the consumer owns execution.

Architecture

nitro/  (git submodule, pinned commit)
  └─ contracts-local/src/precompiles/*.sol
        │  forge build
        ▼
  contracts-local/out/precompiles/*.json     (Foundry artifacts: abi + methodIdentifiers)
        │  dotnet run --project ...Precompiles.Generator
        ▼
  src/Nethermind.Arbitrum.Precompiles/Generated/*.g.cs  (committed)
        │  dotnet pack
        ▼
  Nethermind.Arbitrum.Precompiles  (NuGet)

Three projects in one solution:

• Nethermind.Arbitrum.Precompiles — published library: Generated/*.g.cs plus descriptor types (AbiType, FunctionDescriptor, EventDescriptor, ErrorDescriptor).
• Nethermind.Arbitrum.Precompiles.Generator — console tool: reads Foundry artifacts, emits C#.
• Nethermind.Arbitrum.Precompiles.Test — test suite over the artifact reader, descriptor types, and generated output.

Local Development

Prerequisites: .NET SDK 10.0.100, Foundry on PATH, initialized Nitro submodule.

git submodule update --init --recursive
make generate                                    # forge build → run C# generator
dotnet test src/Nethermind.Arbitrum.Precompiles.slnx

make help lists every target. make clean removes the generated .g.cs files; make build runs only the Foundry compile step.

Bumping Nitro

1. Update the nitro/ submodule to the desired Nitro commit.
2. Run make generate locally and inspect the diff under Generated/.
3. Open a PR. CI will autocommit the regenerated files if you skip step 2 (same-repo PRs only).

CI Workflows

The pipeline is split across four workflow files. Three are event-triggered; one is a reusable workflow consumed by the others via workflow_call to keep build/test logic in a single place.

Two quirks worth knowing:

• Autocommit doesn't re-trigger workflows. The bot uses GITHUB_TOKEN, which GitHub deliberately suppresses to break recursion loops. After an autocommit, the Build and test check ran against the previous HEAD — click "re-run" in the UI to validate the post-autocommit commit before merging.
• The required check name is compound. Because pr.yaml's build-test job invokes build-test.yaml via workflow_call, GitHub posts the check as Build and test / Build and test. Branch rulesets must use the compound name verbatim.

Releases

Releases are deliberate, not automatic.

1. Tag a commit on main as vX.Y.Z.
2. Manually dispatch the Release workflow against that tag, choosing Staging or Production.
3. The guard job refuses any non-refs/tags/v* ref; the version comes from the tag; dotnet pack produces .nupkg + .snupkg; dotnet nuget push --skip-duplicate makes re-runs safe; a GitHub Release is created automatically.

Consumer Usage

dotnet add package Nethermind.Arbitrum.Precompiles

Everything is a static constant under the Nethermind.Arbitrum.Precompiles.Solgen namespace.

using Nethermind.Arbitrum.Precompiles.Solgen;

uint selector  = ArbSys.Methods.ArbBlockNumber;             // 0xa3b1b31d
string topic0  = ArbSys.Events.L2ToL1Tx.Topic0Hex;          // 0x3e7aafa7…
uint errorSel  = ArbSys.Errors.InvalidBlockNumber.Selector; // 0xd5dc642d
string abiJson = ArbSys.Abi;
string nitro   = ArbSys.NitroCommit;

foreach (string name in AllPrecompiles.Names) { /* … */ }