@bananapus/address-registry-v6 0.0.11 → 0.0.14

package/ADMINISTRATION.md

@@ -26,6 +26,15 @@ Every function is callable by any address. There are no restricted operations.
 - **Permanent storage, no removal.** There is no `unregister` or `removeAddress` function. Entries can be overwritten but never deleted.
 - **No approval or queue.** Registrations take effect immediately in the same transaction.
 
+## Client-Side Trust
+
+The registry stores deployer mappings without making trust judgments. All trust decisions are delegated to clients:
+
+- **No on-chain filtering.** The contract does not distinguish "trusted" from "untrusted" deployers. Clients must maintain their own allowlist of known deployer addresses and cross-reference against `deployerOf()`.
+- **Event-based discovery.** The contract emits an `AddressRegistered(address indexed addr, address indexed deployer, address caller)` event on every registration. Clients can monitor this event to discover new registrations in real time.
+- **Overwrite risk.** Since registrations are overwritable, a client that caches `deployerOf(addr)` at time T may see a different result at time T+1 if someone re-registers the same address with a different deployer/nonce or deployer/salt/bytecode combination. Clients should re-check at time of use rather than caching indefinitely.
+- **No validation of deployment.** The registry computes the expected address from the inputs but does not verify that a contract actually exists at that address. A registration can be created for an address that has not yet been deployed (or will never be deployed).
+
 ## Admin Boundaries
 
 There are no admins. Specifically:

package/ARCHITECTURE.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Deployer verification registry for Juicebox V6. Allows contracts deployed via `create` or `create2` to publicly register their deployer's address. Frontend clients use this to verify that hooks and other contracts were deployed by trusted deployers.
+Juicebox projects can attach arbitrary hook contracts (pay hooks, cashout hooks, 721 tier hooks, etc.) that execute during payments, cashouts, and payouts. A malicious hook could steal funds or mislead users. Frontends need a way to answer the question: "Was this hook deployed by a trusted deployer like `JB721TiersHookDeployer`?"
+
+`JBAddressRegistry` solves this by letting contracts deployed via `create` or `create2` publicly register their deployer's address. A frontend can then call `deployerOf(hookAddress)` and check the result against its own list of trusted deployers — displaying warnings or blocking interactions for hooks with unknown origins.
 
 ## Contract Map
 
@@ -38,6 +40,16 @@ Frontend → JBAddressRegistry.deployerOf(hookAddress)
   → Frontend checks deployer against trusted deployer list
 ```
 
+## Design Decisions
+
+**Deployer verification, not a whitelist.** The registry records *who* deployed a contract, not *whether* a contract is approved. This keeps the registry permissionless and neutral — any deployer can register, and trust decisions are made by each frontend independently. There is no governance or admin role.
+
+**Both `create` and `create2` support.** Deployers that use `create` (nonce-based) and `create2` (salt + bytecode) both exist in the Juicebox ecosystem. Supporting both ensures any deployer can register its contracts regardless of deployment strategy.
+
+**No validation beyond hash match.** The registry does not check that registered addresses contain code, implement a particular interface, or were recently deployed. It only verifies that the provided deployer + nonce/salt/bytecode deterministically produce the claimed address. This keeps the contract simple and gas-efficient — frontends already perform their own trust checks on the deployer address.
+
+**Anyone can call `registerAddress`.** Registration is not restricted to the deployer itself. Any account that knows the deployer address and nonce (or salt + bytecode) can register a contract. This is safe because the mapping is deterministic — providing incorrect inputs simply computes a different address, not a false registration for the target contract.
+
 ## Dependencies
 
 - `@sphinx-labs/plugins` — Deployment tooling (devDependency only)

package/AUDIT_INSTRUCTIONS.md

@@ -2,6 +2,31 @@
 
 You are auditing a permissionless address registry for Juicebox V6. The contract stores a mapping from deployed contract addresses to their deployers, computed deterministically from `create` or `create2` parameters. It has no owner, no access control, no constructor arguments, and no external dependencies. Read [RISKS.md](./RISKS.md) first -- it documents all known risks and trust assumptions. Then come back here.
 
+## Compiler and Version Info
+
+| Setting | Value |
+|---------|-------|
+| Solidity version | ^0.8.26 |
+| EVM target | cancun |
+| Optimizer | enabled, 200 runs |
+| via-IR | not enabled |
+| Fuzz runs | 4,096 |
+| Invariant runs | 1,024 (depth 100) |
+
+Source: [`foundry.toml`](./foundry.toml)
+
+## Previous Audit Findings
+
+A Nemesis automated audit was conducted on 2026-03-17. Results are in [`.audit/findings/nemesis-verified.md`](./.audit/findings/nemesis-verified.md). Summary:
+
+| ID | Severity | Title | Status |
+|----|----------|-------|--------|
+| NM-001 | LOW | Deployment library project name mismatch (`"nana-address-registry"` vs `"nana-address-registry-v6"`) | Open (deployment script only, no runtime impact) |
+
+The core contract (`JBAddressRegistry`) was verified sound -- RLP encoding is correct across all 10 nonce ranges, CREATE2 computation matches EIP-1014. No CRITICAL, HIGH, or MEDIUM findings were identified.
+
+No prior formal audit with finding IDs from an external security firm has been conducted.
+
 ## Scope
 
 **In scope -- all Solidity in `src/`:**

package/CHANGE_LOG.md

@@ -2,11 +2,17 @@
 
 This document describes all changes between `nana-address-registry` (v5) and `nana-address-registry-v6` (v6).
 
+## Summary
+
+- **Nonce range extended from `uint32` to `uint64`**: Fixes silent address miscalculation for large nonces — previously truncated without error, now correctly RLP-encodes up to `uint64` and reverts above.
+- **New `NonceTooLarge` error**: Explicit revert replaces silent truncation for nonces exceeding `uint64.max`.
+- **No ABI-breaking changes**: Interface and function signatures are identical — only the internal nonce encoding logic changed.
+
 ---
 
 ## 1. Breaking Changes
 
-- **Solidity version bump**: `0.8.23` → `0.8.26`. Contracts compiled against v5 ABIs will still be compatible (no ABI-level breaking changes), but the compiler version requirement has changed.
+- **Solidity version bump**: `0.8.23` → `^0.8.26`. Contracts compiled against v5 ABIs will still be compatible (no ABI-level breaking changes), but the compiler version requirement has changed.
 - **Nonce range extended from `uint32` to `uint64`**: In v5, the `_addressFrom` function silently produced incorrect addresses for nonces at or above `2^32`. In v6, nonces up to `uint64.max` are correctly RLP-encoded, and nonces above `uint64.max` revert with `JBAddressRegistry_NonceTooLarge`. Any off-chain tooling that assumed the `uint32` ceiling must be updated.
 
 ## 2. New Features
@@ -81,7 +87,7 @@ No function signatures, parameter types, or return types changed.
 | v5 | v6 | Action Required |
 |---|---|---|
 | `IJBAddressRegistry` | `IJBAddressRegistry` | **None** — ABI-identical. Update import path only. |
-| `JBAddressRegistry` | `JBAddressRegistry` | **None** — ABI-compatible. Deploy new instance compiled with Solidity 0.8.26. |
+| `JBAddressRegistry` | `JBAddressRegistry` | **None** — ABI-compatible. Deploy new instance compiled with Solidity ^0.8.26. |
 | `registerAddress(address, uint256)` | `registerAddress(address, uint256)` | **None** — signature unchanged. Nonces > `uint32` now work correctly; nonces > `uint64` now revert instead of silently producing wrong addresses. |
 | `registerAddress(address, bytes32, bytes)` | `registerAddress(address, bytes32, bytes)` | **None** — signature unchanged. |
 | `deployerOf(address)` | `deployerOf(address)` | **None** — signature unchanged. |

package/README.md

@@ -46,6 +46,17 @@ In both cases, the registry stores the mapping `deployerOf[computedAddress] = de
 
 No access control is needed -- only the correct deployer + parameters can produce a given address, so registrations cannot be faked.
 
+```solidity
+// Register a contract deployed via create.
+registry.registerAddress(deployer, nonce);
+
+// Register a contract deployed via create2.
+registry.registerAddress(deployer, salt, bytecode);
+
+// Look up who deployed a contract.
+address deployer = registry.deployerOf(contractAddress);
+```
+
 ### Events
 
 | Event | Fields | Emitted When |
@@ -61,7 +72,7 @@ Deployers can be exploited or act maliciously. Clients should still communicate
 ### Limitations
 
 - The `_addressFrom` function for `create` addresses uses RLP encoding that only supports nonces up to `uint64` max (18,446,744,073,709,551,615). Higher nonces revert with `JBAddressRegistry_NonceTooLarge`. In practice, this limit is unreachable.
-- No overwrite protection: registering the same computed address again overwrites the previous deployer. This is safe because only the correct deployer + parameters produce a given address -- a second call with the same inputs just re-registers the same deployer.
+- Re-registration is prevented: registering the same computed address again reverts with `JBAddressRegistry_AlreadyRegistered`. Only the first registration is accepted.
 - Registration is permissionless -- anyone can call `registerAddress`, not just the deployer. Security relies entirely on deterministic address computation.
 
 ## Deployment

package/RISKS.md

@@ -8,11 +8,18 @@
 ## 2. Known Risks
 
 - **False registration.** Anyone can call `registerAddress` with arbitrary deployer/nonce values, registering a computed address with a deployer that did not actually deploy it. Consumers must verify the deployer is trusted, not just that a mapping exists.
-- **Overwrite of existing entries.** There is no check preventing re-registration. A second call with different parameters that computes the same address will overwrite the previous `deployerOf` entry.
-- **No removal mechanism.** Once registered, an entry cannot be removed, only overwritten.
-- **RLP encoding correctness.** The `_addressFrom` function manually implements RLP encoding for nonces up to uint64. Well-tested pattern; nonce capped at uint64 max with explicit revert.
+- **No removal mechanism.** Once registered, an entry cannot be removed. Re-registration of the same address reverts with `JBAddressRegistry_AlreadyRegistered`.
+- **CREATE2 vs CREATE1 trust model.** CREATE1 registrations (`registerAddress(deployer, nonce)`) can be spoofed: anyone who knows the deployer address and nonce can register the computed address without being the deployer. CREATE2 registrations (`registerAddress(deployer, salt, bytecode)`) have the same trust model — knowing the parameters is sufficient to register. The function accepts raw deployment bytecode and hashes it internally (`keccak256(bytecode)`) for the CREATE2 address computation. In both cases, the registry only proves "this address COULD have been deployed by this deployer with these parameters", not "this deployer DID deploy this address". Consumers must verify the deployer is trusted independently.
+- **Frontend trust example.** A malicious actor could register `deployerOf[uniswapRouter] = attackerDeployer` if they find a `(deployer, nonce)` or `(deployer, salt, bytecode)` combination that computes to the Uniswap router address and register it before the legitimate deployer does. Only the first registration is accepted; subsequent attempts revert with `JBAddressRegistry_AlreadyRegistered`. Frontends that display "deployed by X" based on `deployerOf` should cross-reference against a curated allowlist of trusted deployers.
 
 ## 3. Invariants to Verify
 
 - `deployerOf[addr]` always corresponds to a valid deployer/nonce pair that produces `addr` (if registered via `registerAddress`).
-- `create2` registrations: `deployerOf[addr]` corresponds to a valid deployer/salt/bytecodeHash that produces `addr`.
+- `create2` registrations: `deployerOf[addr]` corresponds to a valid deployer/salt/bytecode combination whose `keccak256(bytecode)` produces `addr` via the CREATE2 formula.
+- Registration idempotency: `deployerOf[addr]` reflects the first and only registration. Subsequent attempts to register the same address revert with `JBAddressRegistry_AlreadyRegistered`.
+
+## 4. Accepted Behaviors
+
+### 4.1 RLP encoding correctness is well-tested and bounded
+
+The `_addressFrom` function manually implements RLP encoding for nonces up to uint64. The nonce is capped at uint64 max with an explicit revert, and the encoding logic is a well-tested pattern. This is not an open risk.

package/SKILLS.md

@@ -41,6 +41,14 @@ Deployed on: Ethereum, Optimism, Arbitrum, Base, and their Sepolia testnets.
 | `_addressFrom(address origin, uint256 nonce) returns (address)` | Computes `create` address using RLP encoding. Handles 10 nonce ranges: `0`, `1-0x7f`, `0x80-0xff`, `0x100-0xffff`, `0x10000-0xffffff`, `0x1000000-0xffffffff`, `0x100000000-0xffffffffff`, `0x10000000000-0xffffffffffff`, `0x1000000000000-0xffffffffffffff`, `0x100000000000000-0xffffffffffffffff`. Reverts with `JBAddressRegistry_NonceTooLarge` for nonces above `uint64` max. Uses `keccak256` of the RLP-encoded `[origin, nonce]` and extracts the low 160 bits via assembly. |
 | `_registerAddress(address addr, address deployer)` | Writes `deployerOf[addr] = deployer` and emits `AddressRegistered`. Shared by both public `registerAddress` overloads. |
 
+## Errors
+
+| Error | Defined In | Trigger Condition |
+|-------|-----------|-------------------|
+| `JBAddressRegistry_NonceTooLarge(uint256 nonce)` | `JBAddressRegistry` | `registerAddress(deployer, nonce)` is called with a `nonce` greater than `type(uint64).max` (18,446,744,073,709,551,615). Reverts inside `_addressFrom` before any state change. In practice unreachable since no EOA or contract can reach this nonce. |
+
+This is the only custom error in the contract. The `create2` overload of `registerAddress` has no revert paths (invalid parameters silently compute the wrong address).
+
 ## Integration Points
 
 | Dependency | Import | Used For |
@@ -83,11 +91,11 @@ No arrays, no structs, no linked lists. One mapping, that is all.
 - **Nonce limit**: `_addressFrom` supports nonces up to `uint64` max (18,446,744,073,709,551,615). Nonces above this revert with `JBAddressRegistry_NonceTooLarge`. In practice this limit is unreachable.
 - **No overwrite protection**: Calling `registerAddress` with parameters that compute to an already-registered address will overwrite the `deployerOf` entry. This is safe because only the correct deployer + parameters produce a given address. But be aware that the same address can be "re-registered" by anyone at any time (with the same result).
 - **Permissionless**: Anyone can call `registerAddress`, not just the deployer. `msg.sender` is recorded in the event as `caller` but is NOT stored in the mapping. Only the computed deployer is stored.
-- **No validation**: The registry does not check that `addr` has code deployed, or that the deployer is a real deployer. It purely does math and stores the result. If you pass wrong parameters, it silently registers a mapping for the wrong address.
+- **No validation**: The registry does not check that `addr` has code deployed, or that the deployer is a real deployer. It purely does math and stores the result. If you pass wrong parameters, it silently registers a mapping for the wrong address. Frontends MUST verify `addr.code.length > 0` (or `extcodesize(addr) > 0` in assembly) before trusting a registry entry.
 - **`deployerOf` returns `address(0)` for unregistered addresses**: This is the default mapping value, not a sentinel. There is no way to distinguish "never registered" from "registered with deployer = address(0)" (though the latter would require someone to call `registerAddress(address(0), ...)` deliberately).
 - **`create2` bytecode must include constructor args**: When registering a `create2` deployment, the `bytecode` parameter must be the full creation bytecode including ABI-encoded constructor arguments: `abi.encodePacked(type(Contract).creationCode, abi.encode(arg1, arg2, ...))`. Omitting constructor args will compute the wrong address.
 - **Contract nonces start at 1**: When using the `create` overload to register a contract deployed by another contract, remember that contract nonces start at 1 (not 0 like EOAs). The first contract deployed by a factory is at nonce 1.
-- **Solidity version**: The implementation uses `pragma solidity 0.8.26` (exact). The interface uses `pragma solidity ^0.8.0` (flexible) so it can be imported by any 0.8.x consumer.
+- **Solidity version**: The implementation uses `pragma solidity ^0.8.26`. The interface uses `pragma solidity ^0.8.0` (flexible) so it can be imported by any 0.8.x consumer.
 
 ## Example: Register a `create` Deployment
 

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;

package/USER_JOURNEYS.md

@@ -1,144 +1,97 @@
 # User Journeys -- nana-address-registry-v6
 
-Concrete end-to-end flows through the address registry. Each journey traces the exact function calls, state changes, and external interactions.
+All user paths through the Juicebox V6 address registry. For each journey: entry point, key parameters, state changes, events, and edge cases.
 
-## Journey 1: Register a Contract Deployed via create
-
-**Actor:** Anyone (the deployer, the deployed contract itself, or a third party).
-**Goal:** Record the deployer of a contract that was deployed using the `create` opcode (standard deployment).
-
-### Precondition
-
-A contract exists on-chain at the address that `create` would produce from `(deployer, nonce)`. The caller knows the deployer's address and the nonce used during deployment.
-
-### Steps
-
-1. **Caller invokes `registerAddress(address deployer, uint256 nonce)`**
-
-   - The `nonce` must be `<= type(uint64).max` or the call reverts with `JBAddressRegistry_NonceTooLarge(nonce)`
-   - The contract calls `_addressFrom(deployer, nonce)` internally
-
-2. **`_addressFrom` computes the create address via RLP encoding**
+---
 
-   - Selects the correct RLP encoding branch based on the nonce range (10 branches: `0`, `1-0x7f`, `0x80-0xff`, ..., up to `uint64` max)
-   - Builds the RLP-encoded byte sequence: `[list_prefix, 0x94, deployer_20_bytes, nonce_encoding]`
-   - Hashes the sequence with `keccak256`
-   - Extracts the low 160 bits as the computed address via inline assembly
+## 1. Register a Contract Deployed via `create`
 
-3. **`_registerAddress` stores the mapping and emits the event**
+**Entry point**: `JBAddressRegistry.registerAddress(address deployer, uint256 nonce)`
 
-   - Sets `deployerOf[computedAddress] = deployer`
-   - Emits `AddressRegistered(addr: computedAddress, deployer: deployer, caller: msg.sender)`
+**Who can call**: Anyone. No access control -- any account can register any `(deployer, nonce)` pair. The caller does not need to be the deployer.
 
-### Result
+**Parameters**:
+- `deployer` -- Address of the account that deployed the contract via `create`
+- `nonce` -- The nonce the deployer's account had when deploying the contract (must be `<= type(uint64).max`)
 
-`deployerOf[computedAddress]` now returns `deployer`. Anyone querying the registry for that address can verify who deployed it.
+**State changes**:
+1. Computes the deterministic `create` address via RLP encoding of `[deployer, nonce]` -- selects one of 10 encoding branches based on nonce range (`0`, `1..0x7f`, `0x80..0xff`, ..., up to `uint64` max)
+2. `JBAddressRegistry.deployerOf[computedAddress] = deployer` -- stores the deployer mapping
 
-### What to verify
+**Events**: `AddressRegistered(addr, deployer, caller)` -- where `addr` is the computed `create` address, `deployer` is the registered deployer, and `caller` is `msg.sender`. Both `addr` and `deployer` are `indexed`.
 
-- The computed address matches the actual on-chain contract address for the given `(deployer, nonce)` pair.
+**Edge cases**:
+- `nonce > type(uint64).max` reverts with `JBAddressRegistry_NonceTooLarge(nonce)`
 - If the caller provides incorrect parameters (wrong nonce, wrong deployer), a mapping is still created -- but for a different (likely nonexistent) address. The registry does not verify that code exists at the computed address.
-- Calling `registerAddress` again with the same parameters is idempotent (same result, no revert).
+- Calling `registerAddress` again with the same parameters is idempotent (same mapping value, same event, no revert).
 - The `caller` in the event is `msg.sender`, which may differ from `deployer`.
 
 ---
 
-## Journey 2: Register a Contract Deployed via create2
-
-**Actor:** Anyone (the deployer, the deployed contract itself, or a third party).
-**Goal:** Record the deployer of a contract that was deployed using the `create2` opcode (deterministic deployment).
-
-### Precondition
-
-A contract exists on-chain at the address that `create2` would produce from `(deployer, salt, bytecode)`. The caller knows the deployer's address, the salt, and the full creation bytecode (including constructor arguments).
-
-### Steps
-
-1. **Caller invokes `registerAddress(address deployer, bytes32 salt, bytes calldata bytecode)`**
+## 2. Register a Contract Deployed via `create2`
 
-   - No parameter validation beyond the address computation itself
-   - `bytecode` must include ABI-encoded constructor arguments appended to the creation code
+**Entry point**: `JBAddressRegistry.registerAddress(address deployer, bytes32 salt, bytes calldata bytecode)`
 
-2. **The contract computes the create2 address inline**
+**Who can call**: Anyone. No access control -- any account can register any `(deployer, salt, bytecode)` tuple. The caller does not need to be the deployer.
 
-   - `address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0xff), deployer, salt, keccak256(bytecode))))))`
-   - This matches the EIP-1014 specification
+**Parameters**:
+- `deployer` -- Address of the account or factory contract that deployed the contract via `create2`
+- `salt` -- The `create2` salt used during deployment
+- `bytecode` -- The full creation bytecode including ABI-encoded constructor arguments (not runtime bytecode)
 
-3. **`_registerAddress` stores the mapping and emits the event**
+**State changes**:
+1. Computes the deterministic `create2` address: `address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0xff), deployer, salt, keccak256(bytecode))))))`
+2. `JBAddressRegistry.deployerOf[computedAddress] = deployer` -- stores the deployer mapping
 
-   - Sets `deployerOf[computedAddress] = deployer`
-   - Emits `AddressRegistered(addr: computedAddress, deployer: deployer, caller: msg.sender)`
-
-### Result
-
-`deployerOf[computedAddress]` now returns `deployer`. Frontends and other contracts can look up the deployer of any `create2`-deployed contract.
-
-### What to verify
+**Events**: `AddressRegistered(addr, deployer, caller)` -- where `addr` is the computed `create2` address, `deployer` is the registered deployer, and `caller` is `msg.sender`. Both `addr` and `deployer` are `indexed`.
 
+**Edge cases**:
 - The `bytecode` parameter must be the full creation bytecode, not the deployed (runtime) bytecode. Omitting constructor arguments produces a different hash and therefore a different address.
-- For large bytecode payloads, `keccak256(bytecode)` is computed in memory. The gas cost scales with bytecode size, but the registry itself has no gas limit issues -- the caller pays.
+- For large bytecode payloads, `keccak256(bytecode)` is computed in memory. Gas cost scales with bytecode size, but the registry itself has no gas limit issues -- the caller pays.
 - The salt is deployer-specific. Different deployers with the same salt and bytecode produce different addresses (because the deployer address is part of the hash input).
+- No parameter validation beyond the address computation itself. No revert conditions exist for this overload.
 
 ---
 
-## Journey 3: Frontend Verifies a Hook's Deployer
-
-**Actor:** Frontend application or off-chain service.
-**Goal:** Determine whether a Juicebox hook was deployed by a trusted factory.
-
-### Precondition
-
-The hook contract has been registered in the registry (via Journey 1 or 2). The frontend maintains a list of trusted deployer addresses.
-
-### Steps
+## 3. Frontend Verifies a Hook's Deployer
 
-1. **Frontend reads `deployerOf(hookAddress)`**
+**Entry point**: `JBAddressRegistry.deployerOf(address addr)` (public mapping getter -- `view`)
 
-   - This is a simple public mapping getter -- a `staticcall` with no state changes
-   - Returns `address(0)` if the hook has never been registered
+**Who can call**: Anyone. This is a `view` function (auto-generated mapping getter) with no access control or state changes.
 
-2. **Frontend evaluates the result**
+**Parameters**:
+- `addr` -- The address of the contract to look up
 
-   - If `deployer == address(0)`: the hook is unregistered. The frontend should treat it as untrusted.
-   - If `deployer` is in the trusted deployer set: the hook was deployed by a known, audited factory. The frontend can display it with confidence.
-   - If `deployer` is a non-zero address not in the trusted set: the hook is registered but was deployed by an unknown deployer. The frontend should flag it as unverified.
+**State changes**: None. Read-only query.
 
-### Result
+**Events**: None. No state mutation occurs.
 
-The frontend can make a trust decision about the hook without needing to trace the deployment transaction on-chain.
+**Result**: Returns the registered deployer address, or `address(0)` if the address has never been registered. The frontend evaluates:
+- `deployer == address(0)` -- the hook is unregistered; treat as untrusted
+- `deployer` is in the trusted deployer set -- the hook was deployed by a known, audited factory; display with confidence
+- `deployer` is a non-zero address not in the trusted set -- registered but deployed by an unknown deployer; flag as unverified
 
-### What to verify
-
-- `deployerOf` returns `address(0)` for any address that has never been registered. There is no way to distinguish "never registered" from "registered with `deployer = address(0)`", though the latter requires deliberately passing `address(0)` as the deployer.
+**Edge cases**:
+- `deployerOf` returns `address(0)` for any address never registered. There is no way to distinguish "never registered" from "registered with `deployer = address(0)`", though the latter requires deliberately passing `address(0)` as the deployer.
 - The registry provides no guarantee that code exists at the registered address. A deployer could register an address for a contract that has been self-destructed or was never deployed.
 - The registry provides no guarantee that the registered deployer is the *actual* deployer. It only guarantees that the deterministic computation of `(deployer, nonce)` or `(deployer, salt, bytecode)` produces that address. Since the EVM's address derivation is deterministic, this is equivalent -- but the registry itself does not verify the deployment transaction.
 
 ---
 
-## Journey 4: Overwrite a Previous Registration
-
-**Actor:** Anyone.
-**Goal:** Re-register an address with the same or different parameters.
-
-### Precondition
-
-`deployerOf[addr]` already has a non-zero value from a previous registration.
-
-### Steps
-
-1. **Caller invokes either `registerAddress` overload with parameters that compute to `addr`**
+## 4. Overwrite a Previous Registration
 
-2. **`_registerAddress` overwrites the existing value**
+**Entry point**: `JBAddressRegistry.registerAddress(address deployer, uint256 nonce)` or `JBAddressRegistry.registerAddress(address deployer, bytes32 salt, bytes calldata bytecode)`
 
-   - `deployerOf[addr] = deployer` (unconditional write, no check for existing value)
-   - Emits a new `AddressRegistered` event
+**Who can call**: Anyone. There is no access control on overwrites. No owner check or deployer verification is performed.
 
-### Result
+**Parameters**: Same as Journey 1 or Journey 2, depending on which `registerAddress` overload is called. The provided parameters must compute to the same target address as the previous registration.
 
-The previous deployer mapping is overwritten. The event log contains both the old and new registrations.
+**State changes**:
+1. `JBAddressRegistry.deployerOf[addr] = deployer` -- unconditional `SSTORE`, overwrites any existing value without checking the previous deployer
 
-### What to verify
+**Events**: `AddressRegistered(addr, deployer, caller)` -- emitted on every call, even if the stored value is unchanged.
 
+**Edge cases**:
 - Overwriting is safe because the same address can only be computed from the same `(deployer, nonce)` or `(deployer, salt, bytecode)` parameters (assuming no keccak256 collision). Re-registering with the same parameters produces the same result.
 - There is no way to "unregister" an address. Setting `deployerOf[addr] = address(0)` would require computing a `(deployer, nonce)` pair that produces `addr` with `deployer = address(0)`, which is theoretically possible but practically useless.
 - The event log preserves the full history of registrations. Off-chain indexers can detect overwrites by tracking multiple `AddressRegistered` events for the same `addr`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/address-registry-v6",
-  "version": "0.0.11",
+  "version": "0.0.14",
   "license": "MIT",
   "repository": {
     "type": "git",

package/script/helpers/AddressRegistryDeploymentLib.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 import {stdJson} from "forge-std/Script.sol";
 import {Vm} from "forge-std/Vm.sol";

package/src/JBAddressRegistry.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 import {IJBAddressRegistry} from "./interfaces/IJBAddressRegistry.sol";
 
@@ -16,6 +16,10 @@ contract JBAddressRegistry is IJBAddressRegistry {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when attempting to register an address that has already been registered.
+    /// @param addr The address that is already registered.
+    error JBAddressRegistry_AlreadyRegistered(address addr);
+
     /// @notice Thrown when a nonce exceeds the maximum value supported by the RLP encoding (uint64 max).
     error JBAddressRegistry_NonceTooLarge(uint256 nonce);
 
@@ -120,6 +124,8 @@ contract JBAddressRegistry is IJBAddressRegistry {
     /// @param addr The deployed contract's address.
     /// @param deployer The deployer's address.
     function _registerAddress(address addr, address deployer) internal {
+        if (deployerOf[addr] != address(0)) revert JBAddressRegistry_AlreadyRegistered(addr);
+
         deployerOf[addr] = deployer;
 
         emit AddressRegistered({addr: addr, deployer: deployer, caller: msg.sender});

package/test/JBAddressRegistryEdge.t.sol

@@ -158,30 +158,43 @@ contract JBAddressRegistryEdge is Test {
     }
 
     // =========================================================================
-    // Duplicate registration - second registration overwrites first
+    // Duplicate registration - second registration reverts
     // =========================================================================
 
-    /// @notice Registering the same computed address twice overwrites the deployer.
-    function test_duplicateRegistration_overwrites() public {
+    /// @notice Registering the same computed address twice reverts with AlreadyRegistered.
+    function test_duplicateRegistration_reverts() public {
         uint64 nonce = 1;
 
         vm.setNonce(deployer, nonce);
         vm.prank(deployer);
         address deployed = address(new MockDeployment());
 
-        // First registration.
+        // First registration succeeds.
         registry.registerAddress(deployer, nonce);
         assertEq(registry.deployerOf(deployed), deployer);
 
-        // Register again with a different deployer (same computed address via different params).
-        // Actually, same deployer + nonce = same address. Let's just call register again.
-        address fakeDeployer = makeAddr("fake");
-        registry.registerAddress(fakeDeployer, nonce);
+        // Second registration of the same address reverts.
+        vm.expectRevert(
+            abi.encodeWithSelector(JBAddressRegistry.JBAddressRegistry_AlreadyRegistered.selector, deployed)
+        );
+        registry.registerAddress(deployer, nonce);
+    }
 
-        // The real deployed address still has the correct deployer.
-        // But the address computed from (fakeDeployer, nonce) is a DIFFERENT address.
-        // So deployed's mapping is unchanged.
-        assertEq(registry.deployerOf(deployed), deployer, "Original registration should be unchanged");
+    /// @notice Registering the same create2 address twice reverts with AlreadyRegistered.
+    function test_duplicateRegistration_create2_reverts() public {
+        Factory factory = new Factory();
+        bytes32 salt = bytes32(uint256(42));
+        address deployed = factory.deploy(salt);
+
+        // First registration succeeds.
+        registry.registerAddress(address(factory), salt, type(MockDeployment).creationCode);
+        assertEq(registry.deployerOf(deployed), address(factory));
+
+        // Second registration of the same address reverts.
+        vm.expectRevert(
+            abi.encodeWithSelector(JBAddressRegistry.JBAddressRegistry_AlreadyRegistered.selector, deployed)
+        );
+        registry.registerAddress(address(factory), salt, type(MockDeployment).creationCode);
     }
 
     // =========================================================================