Address registry: interface, concrete, reader lib and post-deploy cross-network verification

CLAUDE.md

@@ -3,15 +3,22 @@
 
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
 
 ## Project Overview
 
-rain.deploy is a Solidity library for deploying Rain Protocol contracts via the Zoltu deterministic deployment proxy to multiple EVM networks. It ensures identical contract addresses across all supported chains (Arbitrum, Base, Flare, Polygon) because the Zoltu proxy is deployed at the same address on every chain and uses CREATE with a predictable nonce.
+rain.deploy is a Solidity library for deploying Rain Protocol contracts via the
+Zoltu deterministic deployment proxy to multiple EVM networks. It ensures
+identical contract addresses across all supported chains (Arbitrum, Base, Base
+Sepolia, Flare, Polygon) because the Zoltu proxy is deployed at the same address
+on every chain and deploys with `CREATE2` over its calldata under a zero salt,
+so a contract's address is a pure function of its creation code.
 
 ## Build & Development
 
-This project uses **Foundry** (forge) for Solidity development and **Nix** for environment management.
+This project uses **Foundry** (forge) for Solidity development and **Nix** for
+environment management.
 
 ```bash
 # Enter the nix dev shell (provides forge and all tooling)
@@ -33,40 +40,78 @@ nix develop -c rainix-sol-static
 nix develop -c rainix-sol-legal
 ```
 
-CI runs three matrix tasks: `rainix-sol-legal`, `rainix-sol-test`, `rainix-sol-static`.
+CI runs three matrix tasks: `rainix-sol-legal`, `rainix-sol-test`,
+`rainix-sol-static`.
 
 ## RPC Configuration
 
 Fork tests require RPC endpoints defined in `.env` (gitignored):
+
 ```bash
 ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
 BASE_RPC_URL=https://mainnet.base.org
 FLARE_RPC_URL=https://flare-api.flare.network/ext/C/rpc
 POLYGON_RPC_URL=https://polygon-rpc.com
 ```
+
 These are referenced in `foundry.toml` under `[rpc_endpoints]`.
 
 ## Architecture
 
-The entire library is a single file: `src/lib/LibRainDeploy.sol`.
-
-**LibRainDeploy** provides:
-- `etchZoltuFactory(Vm)` — etches the Zoltu factory bytecode at the factory address (for networks where it isn't deployed)
-- `deployZoltu(bytes creationCode)` — deploys creation code via the Zoltu factory (`0x7A0D94F55792C434d74a40883C6ed8545E406D12`) using low-level `call`, returns the deployed address
-- `supportedNetworks()` — returns the list of Rain-supported network names (used as foundry RPC config aliases)
-- `checkDependencies(...)` — forks each network, verifies dependencies and Zoltu factory exist with expected codehashes
-- `deployToNetworks(...)` — re-verifies dependencies, deploys via Zoltu, verifies address and code hash
-- `deployAndBroadcast(...)` — the main entry point: derives deployer from private key, calls `checkDependencies` then `deployToNetworks`
-
-The library is designed to be called from Foundry scripts (`forge script`) in consuming repos, not directly. Consuming repos provide their own creation code, expected addresses, expected code hashes, and dependency lists.
+**`src/lib/LibRainDeploy.sol`** — the deploy library:
+
+- `etchZoltuFactory(Vm)` — etches the Zoltu factory bytecode at the factory
+  address (for networks where it isn't deployed)
+- `zoltuAddress(bytes creationCode)` — derives the address the factory deploys
+  creation code to, without deploying
+- `deployZoltu(bytes creationCode)` — deploys creation code via the Zoltu
+  factory (`0x7A0D94F55792C434d74a40883C6ed8545E406D12`) using low-level `call`,
+  returns the deployed address
+- `supportedNetworks()` — returns the list of Rain-supported network names (used
+  as foundry RPC config aliases)
+- `isStartBlock(...)` / `findDeployBlock(...)` — binary search a fork's history
+  for the block a contract first appears at
+- `checkRegisteredAddresses(...)` — asserts names resolve to their expected
+  addresses in the address registry, on the currently selected fork
+- `checkRegisteredAddressesOnNetworks(...)` — runs that check on every network,
+  so a deployment's resolved addresses are gated across the whole target set
+  here rather than in each consumer's deploy script
+- `deployToNetworks(...)` — forks each network, verifies the factory and
+  dependencies, deploys via Zoltu, verifies address and code hash
+- `deployAndBroadcast(...)` — the main entry point: derives the deployer from a
+  private key, then `deployToNetworks`
+
+**`src/interface/IAddressRegistryV1.sol`** — the address registry interface: an
+immutable root binds a `bytes32` name to an address once and forever
+(`register`), anyone reads a bound name (`get`), and reading an unbound name
+reverts. The implementation is `AddressRegistry` in
+[rain.factory.deploy](https://github.com/rainlanguage/rain.factory.deploy).
+
+**`src/lib/LibAddressRegistry.sol`** — reads that registry at its deterministic
+address, verifying its code hash first, exactly as `LibRainDeploy` verifies
+`ZOLTU_FACTORY_CODEHASH`. It resolves a name to an address and nothing more:
+what a consumer resolves a name for, and when, is the consumer's business.
+
+The libraries are designed to be called from Foundry scripts (`forge script`) in
+consuming repos, not directly. Consuming repos provide their own creation code,
+expected addresses, expected code hashes, and dependency lists.
 
 ## Key Design Patterns
 
-- **Deterministic addresses**: Zoltu proxy ensures same address on every chain. Deployments fail if the resulting address doesn't match `expectedAddress`.
-- **Code hash verification**: Post-deploy bytecode integrity is verified against `expectedCodeHash`.
-- **Dependency checking**: Before deploying to any network, all dependencies (contract addresses) are verified to have code on-chain.
-- **Idempotent deploys**: If code already exists at the expected address, deployment is skipped for that network.
+- **Deterministic addresses**: Zoltu proxy ensures same address on every chain.
+  Deployments fail if the resulting address doesn't match `expectedAddress`.
+- **Code hash verification**: Post-deploy bytecode integrity is verified against
+  `expectedCodeHash`. The address registry is verified the same way before it is
+  read.
+- **Dependency checking**: Before deploying to any network, all dependencies
+  (contract addresses) are verified to have code on-chain.
+- **Idempotent deploys**: If code already exists at the expected address,
+  deployment is skipped for that network.
+- **Write-once bindings**: registry bindings can never move, which is what makes
+  checking them before a deploy meaningful rather than a race, and what lets the
+  cross-network check be a pre-flight over every network.
 
 ## License
 
-DecentraLicense 1.0 (LicenseRef-DCL-1.0). All source files must have SPDX headers. REUSE compliance is enforced in CI.
+DecentraLicense 1.0 (LicenseRef-DCL-1.0). All source files must have SPDX
+headers. REUSE compliance is enforced in CI.

README.md

@@ -15,6 +15,9 @@ It answers:
 - Have I deployed successfully to all expected networks?
 - How do I track deployments over time and share addresses with other people?
 - How do I ensure deployed code is bytecode-equivalent to local compilations?
+- How does a deployment get a configured address — an owner, say — without
+  baking one into its creation code, where changing it would move every future
+  deployment?
 
 Approach:
 
@@ -25,6 +28,31 @@ Approach:
   and against the chain after: silent failures fail loudly.
 - Bytecode integrity checks (e.g. via the Rain Extrospection lib) supported
   post-deploy.
+- A write-once address registry, read at run time rather than compiled in, and
+  gated across every target network before a deploy.
+
+## Address registry
+
+`IAddressRegistryV1` binds an opaque `bytes32` name to an address. An immutable
+root authority binds a name that is unbound; nothing, root included, can change
+one after; and reading an unbound name reverts rather than answering with the
+zero address. There is no rotation, no removal and no admin surface, because a
+binding that can move is not worth checking before a deploy.
+
+`LibAddressRegistry.resolve` reads it, verifying the registry's code hash first,
+the same way `LibRainDeploy` verifies the Zoltu factory's. It resolves a name to
+an address and stops there — what a consumer does with the address, and when, is
+the consumer's business.
+
+`LibRainDeploy.checkRegisteredAddressesOnNetworks` is the deploy-time gate:
+every name must resolve to the address the deployment expects, on every target
+network, before anything is broadcast. Because bindings are write-once, that
+pre-flight is exactly as strong as checking inline — an answer that exists
+cannot change, and one that does not exist reverts.
+
+The implementation, `AddressRegistry`, lives in
+[rain.factory.deploy](https://github.com/rainlanguage/rain.factory.deploy);
+`LibAddressRegistry` pins its deterministic address and code hash.
 
 ## Install
 

src/interface/IAddressRegistryV1.sol

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity ^0.8.25;
+
+/// @title IAddressRegistryV1
+/// @notice A registry of `bytes32` names to addresses with exactly two
+/// operations: an immutable root authority binds a name that is unbound, and
+/// anyone reads a name that is bound. There is no rotation, no removal, no
+/// upgrade and no admin surface, and an implementation MUST NOT add any: the
+/// value of the registry is that a binding, once made, is a constant.
+///
+/// Names are opaque 32-byte values. This interface says nothing about how a
+/// name is derived — hashed from a string, a raw ASCII literal, a counter — and
+/// an implementation MUST NOT constrain it. Two callers agreeing on a name is
+/// entirely their business.
+///
+/// The write-once property is what makes a deploy-time check of a binding worth
+/// anything. Against a mutable value the check would be a race, because the
+/// value could move between the check and the read that consumes it. Here, once
+/// `get` returns for a name, it returns the same address forever.
+///
+/// Compromising root therefore cannot change any existing binding. It can reach
+/// a network nobody has deployed to yet and bind the intended names against
+/// itself, burning them there, which forces a different name on that network
+/// and moves addresses on that network only. That is a loud, per-network loss
+/// of determinism, never a silent or retroactive change.
+interface IAddressRegistryV1 {
+    /// Thrown when an account that is not the root authority calls `register`.
+    /// @param sender The `msg.sender` that was not root.
+    error NotRoot(address sender);
+
+    /// Thrown when `register` is called for a name that is already bound.
+    /// Bindings are write-once, so this is thrown even for root, and even when
+    /// the account being registered is the account already bound.
+    /// @param name The name that is already bound.
+    /// @param account The address `name` is bound to.
+    error NameAlreadyRegistered(bytes32 name, address account);
+
+    /// Thrown when `register` is called with the zero address. The zero address
+    /// is how an unbound name reads, so binding it would produce a name that is
+    /// both bound and unreadable, and that `register` would accept a second
+    /// time.
+    /// @param name The name that was being bound to the zero address.
+    error ZeroAccount(bytes32 name);
+
+    /// Thrown by `get` when a name has never been bound, so that a caller
+    /// cannot silently proceed on the zero address by forgetting to check.
+    /// @param name The name that is not bound.
+    error NameNotRegistered(bytes32 name);
+
+    /// Emitted when `name` is bound to `account`. Bindings are write-once, so
+    /// exactly one `Register` is ever emitted per name, and the log is the
+    /// complete enumeration of the registry — there is no other way to discover
+    /// a binding without already knowing the name. Both parameters are indexed
+    /// for that reason: the log has to answer "what is this name bound to" and
+    /// "what did root bind to this address" without a full scan.
+    /// @param name The name that was bound.
+    /// @param account The address `name` was bound to.
+    event Register(bytes32 indexed name, address indexed account);
+
+    /// Binds `name` to `account`, permanently.
+    ///
+    /// The implementation MUST revert `NotRoot` unless the caller is the root
+    /// authority, MUST revert `ZeroAccount` if `account` is the zero address,
+    /// and MUST revert `NameAlreadyRegistered` if `name` is already bound —
+    /// including when the caller is root and including when `account` is the
+    /// address already bound. On success it MUST emit `Register`.
+    /// @param name The name to bind.
+    /// @param account The address to bind it to.
+    function register(bytes32 name, address account) external;
+
+    /// The address `name` is bound to.
+    ///
+    /// The implementation MUST revert `NameNotRegistered` when `name` is
+    /// unbound, rather than returning the zero address, so that no caller has
+    /// to remember to check. It MUST NOT expose any other reader that returns
+    /// the zero address for an unbound name, as that reintroduces exactly the
+    /// mistake this reverting read exists to prevent.
+    /// @param name The name to read.
+    /// @return account The address bound to `name`. Never the zero address.
+    function get(bytes32 name) external view returns (address account);
+}

src/lib/LibAddressRegistry.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: LicenseRef-DCL-1.0
+// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
+pragma solidity ^0.8.25;
+
+import {IAddressRegistryV1} from "../interface/IAddressRegistryV1.sol";
+
+/// @title LibAddressRegistry
+/// @notice Reads the `IAddressRegistryV1` deployed at a single deterministic
+/// address on every network, verifying the registry's code hash first, exactly
+/// as `LibRainDeploy` verifies `ZOLTU_FACTORY_CODEHASH` before using the Zoltu
+/// factory. An address alone says nothing on a chain the caller has not
+/// audited; the address plus the code hash says the caller is talking to the
+/// registry it compiled against.
+///
+/// That is the whole library. It resolves a name to an address. What a consumer
+/// resolves a name for, and when — an owner set in a constructor or an
+/// initializer, under `Ownable` or RBAC or nothing at all — is entirely the
+/// consumer's business and none of this library's.
+library LibAddressRegistry {
+    /// Thrown when the code at the registry address is not the registry this
+    /// library was compiled against. An address with no code hits this too: an
+    /// empty account's code hash is zero (or the hash of empty code), never the
+    /// expected value.
+    /// @param expectedCodeHash The code hash of the pinned registry.
+    /// @param actualCodeHash The code hash actually found at the address.
+    error UnexpectedAddressRegistryCodeHash(bytes32 expectedCodeHash, bytes32 actualCodeHash);
+
+    /// The deterministic Zoltu deploy address of `AddressRegistry`, the same on
+    /// every network.
+    ///
+    /// Derived from that contract's creation code, not observed from a chain:
+    /// the Zoltu factory is `CREATE2` over its calldata with a zero salt, so the
+    /// address is a pure function of the creation code
+    /// (`LibRainDeploy.zoltuAddress`). The root authority is a constant in that
+    /// creation code, so changing the root moves this address, and both this and
+    /// `ADDRESS_REGISTRY_CODEHASH` MUST be re-derived whenever it changes.
+    address constant ADDRESS_REGISTRY = 0x619e47868cE4a9AEbBD6444c9385f1558c79ED52;
+
+    /// The code hash of `AddressRegistry` once deployed, i.e. `keccak256` over
+    /// the runtime code its creation code leaves behind. Derived from the same
+    /// compilation as `ADDRESS_REGISTRY`, and moves with it.
+    bytes32 constant ADDRESS_REGISTRY_CODEHASH = 0x01e8bf67abc9d4b4abe2d39c66c07c1b02e39bdf559c694f94f5853bad6394d8;
+
+    /// The address a name is bound to in the registry.
+    ///
+    /// Verifies the registry's code hash before reading, so a chain where the
+    /// registry is absent, or where something else occupies its address, is a
+    /// loud revert rather than a call into unknown code. The registry itself
+    /// reverts on an unbound name, so a returned address is always a real
+    /// binding and is never the zero address.
+    /// @param name The name to resolve. Opaque; the registry constrains nothing
+    /// about how it was derived.
+    /// @return The address bound to `name`.
+    function resolve(bytes32 name) internal view returns (address) {
+        bytes32 actualCodeHash = ADDRESS_REGISTRY.codehash;
+        if (actualCodeHash != ADDRESS_REGISTRY_CODEHASH) {
+            revert UnexpectedAddressRegistryCodeHash(ADDRESS_REGISTRY_CODEHASH, actualCodeHash);
+        }
+        return IAddressRegistryV1(ADDRESS_REGISTRY).get(name);
+    }
+}