@bananapus/address-registry-v6 0.0.18 → 0.0.20

package/ADMINISTRATION.md

@@ -4,7 +4,7 @@
 
 | Item | Details |
 | --- | --- |
-| Scope | Permissionless provenance registration for CREATE and CREATE2 addresses |
+| Scope | Permissionless provenance registration for `CREATE` and `CREATE2` addresses |
 | Control posture | Fully permissionless and adminless |
 | Highest-risk actions | Incorrect first registration or bad derivation assumptions in offchain tooling |
 | Recovery posture | No in-place recovery; replacement contract is the only fix for logic mistakes |
@@ -15,47 +15,47 @@
 
 ## Control Model
 
-- No owner
-- No governance
-- No pause
-- No upgrade
-- Registration is permissionless and correctness comes from deterministic address derivation
+- no owner
+- no governance
+- no pause
+- no upgrade
+- registration is permissionless and correctness comes from deterministic address derivation
 
 ## Roles
 
 | Role | How Assigned | Scope | Notes |
 | --- | --- | --- | --- |
-| Anyone | No assignment | Global | Can register an address if they provide correct CREATE or CREATE2 inputs |
+| Anyone | No assignment | Global | Can register an address if they provide correct `CREATE` or `CREATE2` inputs |
 
 ## Privileged Surfaces
 
-There are no privileged functions. `registerAddress(...)` is permissionless for both CREATE and CREATE2 registration paths.
+There are no privileged functions. `registerAddress(...)` is permissionless for both registration paths.
 
 ## Immutable And One-Way
 
-- Registration is first-write only.
-- There is no overwrite or delete path for `deployerOf[address]`.
+- registration is first-write only
+- there is no overwrite or delete path for `deployerOf[address]`
 
 ## Operational Notes
 
-- Treat registration as provenance, not endorsement.
-- Register addresses from trustworthy operational pipelines because bad first registration is sticky even though anyone can submit the correct derivation inputs.
+- treat registration as provenance, not endorsement
+- register addresses from trustworthy operational pipelines because bad first registration is sticky even though anyone can submit the correct derivation inputs
 
 ## Machine Notes
 
-- Do not treat registration as a safety certification or allowlist signal.
-- `src/JBAddressRegistry.sol` is the only control-relevant runtime file; there is no hidden owner path.
-- If offchain derivation and onchain registration disagree, stop and resolve the derivation logic rather than assuming overwrite is possible.
+- do not treat registration as a safety certification or allowlist signal
+- `src/JBAddressRegistry.sol` is the only control-relevant runtime file; there is no hidden owner path
+- if offchain derivation and onchain registration disagree, resolve the derivation logic rather than assuming overwrite is possible
 
 ## Recovery
 
-- There is no admin recovery surface.
-- If derivation logic were ever wrong, the contract would need replacement rather than intervention.
+- there is no admin recovery surface
+- if derivation logic were ever wrong, the contract would need replacement rather than intervention
 
 ## Admin Boundaries
 
-- Nobody can curate allowlists, edit entries, or block registration.
-- Nobody can use this registry to certify code safety.
+- nobody can curate allowlists, edit entries, or block registration
+- nobody can use this registry to certify code safety
 
 ## Source Map
 

package/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`nana-address-registry-v6` is a narrow provenance primitive. It records which deployer could have created a contract address by recomputing CREATE or CREATE2 derivation inputs and storing the verified result on-chain.
+`nana-address-registry-v6` is a small provenance primitive. It records which deployer could have created a contract address by recomputing `CREATE` or `CREATE2` inputs and storing the verified result on-chain.
 
 ## System Overview
 
@@ -10,10 +10,10 @@ The repo is intentionally small. `JBAddressRegistry` accepts deterministic deplo
 
 ## Core Invariants
 
-- Registration is permissionless because correctness comes from deterministic derivation, not caller authority.
-- A contract address can only be registered once.
-- Registration must fail until runtime code actually exists at the derived address.
-- CREATE and CREATE2 derivation must match EVM rules exactly.
+- registration is permissionless because correctness comes from deterministic derivation, not caller authority
+- a contract address can only be registered once
+- registration must fail until runtime code actually exists at the derived address
+- `CREATE` and `CREATE2` derivation must match EVM rules exactly
 
 ## Modules
 
@@ -24,9 +24,9 @@ The repo is intentionally small. `JBAddressRegistry` accepts deterministic deplo
 
 ## Trust Boundaries
 
-- The registry attests to deterministic provenance, not code quality.
-- It does not manage ownership, upgrades, or allowlists.
-- External systems may trust its recorded provenance, so derivation correctness is the whole product.
+- the registry attests to deterministic provenance, not code quality
+- it does not manage ownership, upgrades, or allowlists
+- external systems may trust its recorded provenance, so derivation correctness is the whole product
 
 ## Critical Flows
 
@@ -41,24 +41,24 @@ caller
 
 ## Accounting Model
 
-No economic accounting lives here. The only critical state is `deployerOf[address]`.
+No economic accounting lives here. The only important state is `deployerOf[address]`.
 
 ## Security Model
 
-- The risk is concentrated in a small amount of address-derivation logic.
-- The registry records the derived deployer, not the transaction caller. Mixing those concepts would turn provenance into an authority bug.
-- Overengineering is more dangerous than minimal, auditable derivation code.
+- the risk is concentrated in a small amount of address-derivation logic
+- the registry records the derived deployer, not the transaction caller
+- overengineering is more dangerous than minimal, auditable derivation code
 
 ## Safe Change Guide
 
-- Treat derivation code like cryptographic plumbing.
-- Keep the undeployed-address check and first-write-only rule intact; they are part of the provenance guarantee, not optional hygiene.
-- If nonce handling or bytecode hashing changes, keep CREATE and CREATE2 tests aligned.
-- Do not expand the repo into an allowlist or trust-oracle system.
+- treat derivation code like cryptographic plumbing
+- keep the undeployed-address check and first-write-only rule intact
+- if nonce handling or bytecode hashing changes, keep `CREATE` and `CREATE2` tests aligned
+- do not expand the repo into an allowlist or trust-oracle system
 
 ## Canonical Checks
 
-- CREATE and CREATE2 derivation correctness:
+- `CREATE` and `CREATE2` derivation correctness:
   `test/JBAddressRegistry.t.sol`
 - edge-path validation and first-write behavior:
   `test/JBAddressRegistryEdge.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,18 +1,20 @@
 # Audit Instructions
 
-This repo is a small registry, but it participates in deployer verification across the ecosystem. Treat incorrect registration as a security boundary failure.
+This repo is a small registry, but it sits on a deployer-verification boundary across the ecosystem. Treat incorrect registration as a security failure.
 
 ## Audit Objective
 
 Find issues that:
+
 - let callers register contracts under the wrong deployer
 - break determinism or uniqueness assumptions around registration
 - let a malicious deployer spoof provenance for contracts it did not create
-- create stale or truncation-related collisions in recorded mappings
+- create truncation-related collisions or stale mapping assumptions
 
 ## Scope
 
 In scope:
+
 - `src/JBAddressRegistry.sol`
 - `src/interfaces/IJBAddressRegistry.sol`
 - all deployment helpers in `script/`
@@ -25,6 +27,7 @@ In scope:
 ## Security Model
 
 The registry maps deployed addresses to the deployer that created them. Downstream repos use it to:
+
 - validate provenance for clones or deterministically deployed instances
 - discover whether a contract came from an approved deployer path
 
@@ -43,14 +46,12 @@ The registry maps deployed addresses to the deployer that created them. Downstre
 
 ## Critical Invariants
 
-1. Provenance cannot be forged
-Only the actual deployer path the registry intends to trust may create a successful registration for a contract.
-
-2. One contract maps to one authoritative deployer record
-No aliasing or overwrite path should let a later caller replace provenance unexpectedly.
-
-3. Registration metadata is stable
-Nonce, salt, or address truncation must not allow collisions or stale reads.
+1. Provenance cannot be forged.  
+   Only the actual deployer path the registry intends to trust may create a successful registration for a contract.
+2. One contract maps to one authoritative deployer record.  
+   No aliasing or overwrite path should let a later caller replace provenance unexpectedly.
+3. Registration metadata is stable.  
+   Nonce, salt, or address truncation must not allow collisions or stale reads.
 
 ## Attack Surfaces
 

package/README.md

@@ -11,12 +11,12 @@ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-The registry supports both `create` and `create2` style deployments:
+The registry supports both `create` and `create2` deployments:
 
 - for `create`, it reconstructs the deployed address from the deployer and nonce
 - for `create2`, it reconstructs the deployed address from the deployer, salt, and deployment bytecode
 
-Because the address is computed deterministically, registrations do not require access control. Anyone can submit the correct deployment inputs, and the registry records the deployer for the computed address after confirming code already exists there.
+Because the address is computed deterministically, registrations do not need access control. Anyone can submit the correct deployment inputs, and the registry records the deployer for the computed address after confirming code already exists there.
 
 Use this repo when deployer provenance matters. Do not confuse it with an allowlist, audit registry, or trust oracle.
 
@@ -36,7 +36,7 @@ The registry is intentionally narrow:
 2. bind that address to a deployer once
 3. expose the result for other systems and clients
 
-Anything beyond that is out of scope by design.
+Anything beyond that is out of scope.
 
 ## Read These Files First
 
@@ -47,14 +47,14 @@ Anything beyond that is out of scope by design.
 
 ## Integration Traps
 
-- provenance is only meaningful if callers also know what the deployer is supposed to be trusted for
-- permissionless registration is intentional, so integrations should verify the computed inputs rather than assuming caller authority
+- provenance is only useful if callers also know what the deployer is trusted for
+- permissionless registration is intentional, so integrations should verify the computed inputs rather than assume caller authority
 - `create` nonce reconstruction and `create2` salt-bytecode reconstruction are different trust paths and should be reasoned about separately
 
 ## Where State Lives
 
-- deployer provenance lives in `JBAddressRegistry`
-- deployment truth still lives outside this repo in the target chain history and bytecode inputs
+- deployer provenance: `JBAddressRegistry`
+- deployment truth: the target chain history and bytecode inputs outside this repo
 
 ## High-Signal Tests
 
@@ -101,9 +101,9 @@ script/
 
 ## Risks And Notes
 
-- provenance is not the same thing as safety; a known deployer can still deploy unsafe code
-- registrations are first-write only, so bad operational processes around initial registration can be sticky
-- the `create` address path relies on nonce reconstruction and intentionally rejects unrealistic nonce ranges
+- provenance is not the same as safety; a known deployer can still deploy unsafe code
+- registrations are first-write only, so bad initial registration is sticky
+- the `create` path relies on nonce reconstruction and intentionally rejects unrealistic nonce ranges
 
 ## For AI Agents
 

package/RISKS.md

@@ -1,47 +1,47 @@
 # Juicebox Address Registry Risk Register
 
-This file focuses on what `JBAddressRegistry` actually proves: deterministic address provenance claims. The core risk is not funds loss inside the registry; it is consumers over-reading the meaning of a registration entry.
+This file covers what `JBAddressRegistry` actually proves: deterministic address provenance claims. The main risk is not funds loss inside the registry. It is consumers reading too much into a registration entry.
 
-## How to use this file
+## How To Use This File
 
-- Read `Priority risks` first; most failures here are interpretive and integration-driven.
-- Distinguish "address can be derived from these deployment inputs" from "this deployment is trusted".
-- Treat `Invariants to Verify` as the narrow correctness envelope of the registry itself.
+- Read `Priority risks` first. Most failures here are interpretation and integration failures.
+- Distinguish "address can be derived from these inputs" from "this deployment is trusted."
+- Treat `Invariants to verify` as the narrow correctness envelope of the registry itself.
 
-## Priority risks
+## Priority Risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P1 | Over-trusting registration as safety approval | A registered deployer mapping does not mean the contract is audited, canonical, or safe. | UIs must label registration as provenance evidence only. |
+| P1 | Over-trusting registration as safety approval | A registered deployer mapping does not mean the contract is audited, canonical, or safe. | UIs should label registration as provenance evidence only. |
 | P1 | First-writer capture of a valid provenance claim | The registry records the first valid claim for an address and never updates it. | Operational discipline for trusted deployers and curated allowlists for consumers. |
-| P2 | Completeness assumptions | Unregistered contracts can still be legitimate; absence from the registry is not a proof of malice. | Treat registry data as additive metadata, not an allowlist. |
+| P2 | Completeness assumptions | Unregistered contracts can still be legitimate; absence from the registry is not proof of malice. | Treat registry data as additive metadata, not an allowlist. |
 
 ## 1. Trust Assumptions
 
-- **Deterministic address formulas.** The contract trusts its CREATE and CREATE2 address-derivation logic to match EVM semantics.
-- **Consumer trust policy.** The registry does not decide which deployers are trusted. Every consumer must maintain that policy externally.
+- **Deterministic address formulas are correct.** The contract trusts its `CREATE` and `CREATE2` derivation logic to match EVM semantics.
+- **Consumers define trust externally.** The registry does not decide which deployers are trusted.
 
 ## 2. Known Risks
 
-- **Caller identity is irrelevant.** Anyone may call `registerAddress(...)`. The registry proves that an address is consistent with supplied deployment parameters, not that the caller was the deployer.
-- **First registration wins.** Once `deployerOf[addr]` is set, later registrations revert with `JBAddressRegistry_AlreadyRegistered`, even if a different valid provenance claim exists.
-- **No pre-registration of future deployments.** `registerAddress(...)` requires `addr.code.length != 0`. The registry only records provenance for contracts that already exist on-chain; it cannot reserve a deterministic CREATE2 address ahead of deployment.
-- **No removal or correction path.** The registry is intentionally append-only per address. Mistakes are sticky.
-- **Registration is provenance, not endorsement.** A mapping like `deployerOf[hook] = someFactory` says nothing about code safety, upgradeability, audit status, or whether the deployer itself is trustworthy.
+- **Caller identity is irrelevant.** Anyone may call `registerAddress(...)`. The registry proves that an address matches supplied deployment parameters, not that the caller was the deployer.
+- **First registration wins.** Once `deployerOf[addr]` is set, later registrations revert.
+- **No pre-registration of future deployments.** `registerAddress(...)` requires code to already exist at the computed address.
+- **No removal or correction path.** The registry is intentionally append-only per address.
+- **Registration is provenance, not endorsement.** `deployerOf[hook] = someFactory` says nothing about code safety, upgradeability, audit status, or whether the deployer itself is trustworthy.
 - **Operational lag matters.** If a trusted deployer forgets to register immediately, someone else can publish the first valid claim for that address.
 
 ## 3. Integration Risks
 
-- **Frontends must pair registry data with a trusted-deployer set.** Displaying `deployerOf` without a trust list can mislead users into treating any registered provenance as "official".
-- **CREATE and CREATE2 claims are both parameter-based.** In either mode, users should think "the address is compatible with these inputs", not "the registry witnessed deployment".
-- **Off-chain explorers should preserve uncertainty.** A better label is "registered deployer claim" than "deployed by", unless the explorer independently verified the transaction history.
+- **Frontends should pair registry data with a trusted-deployer set.** Displaying `deployerOf` alone can mislead users into treating any registered provenance as official.
+- **`CREATE` and `CREATE2` claims are parameter-based.** In either mode, the right mental model is "the address is compatible with these inputs," not "the registry witnessed deployment."
+- **Off-chain explorers should preserve uncertainty.** "Registered deployer claim" is a safer label than "deployed by" unless the explorer also verified chain history.
 
-## 4. Invariants to Verify
+## 4. Invariants To Verify
 
-- `deployerOf[addr]` is set at most once.
-- CREATE registrations only succeed for addresses derivable from the provided `(deployer, nonce)`.
-- CREATE2 registrations only succeed for addresses derivable from the provided `(deployer, salt, bytecode)`.
-- `_addressFrom` remains correct for the supported nonce range and reverts outside that range.
+- `deployerOf[addr]` is set at most once
+- `CREATE` registrations only succeed for addresses derivable from the provided `(deployer, nonce)`
+- `CREATE2` registrations only succeed for addresses derivable from the provided `(deployer, salt, bytecode)`
+- `_addressFrom` remains correct for the supported nonce range and reverts outside that range
 
 ## 5. Accepted Behaviors
 
@@ -51,8 +51,8 @@ This is intentional. `JBAddressRegistry` is a deterministic provenance registry,
 
 ### 5.2 Unregistered does not mean unsafe
 
-The registry is useful metadata, but it is not complete coverage of all legitimate deployments. Consumers should not infer that an unregistered address is malicious solely because no entry exists.
+The registry is useful metadata, but it does not cover every legitimate deployment. Consumers should not infer that an unregistered address is malicious just because no entry exists.
 
 ### 5.3 The registry is retrospective, not a reservation layer
 
-This is intentional. A deterministic address can only be registered after code already exists there. Consumers should not expect `JBAddressRegistry` to signal future deployment intent or to protect an undeployed CREATE2 address from later first-writer capture once deployment happens.
+This is intentional. A deterministic address can only be registered after code already exists there. Consumers should not expect `JBAddressRegistry` to signal future deployment intent or protect an undeployed `CREATE2` address from later first-writer capture.

package/SKILLS.md

@@ -31,11 +31,11 @@ Permissionless on-chain provenance registry that records which deployer created
 ## Reference Files
 
 - Open [`references/runtime.md`](./references/runtime.md) when you need the core guarantees, first-write semantics, or the difference between provenance and trust.
-- Open [`references/operations.md`](./references/operations.md) when you need deployment breadcrumbs, test pointers, or the common stale assumptions around what the registry can verify.
+- Open [`references/operations.md`](./references/operations.md) when you need deployment breadcrumbs, test pointers, or common stale assumptions about what the registry can verify.
 
 ## Working Rules
 
 - Start in [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol). This repo is intentionally small, so most questions should collapse quickly to the core contract.
 - Treat provenance and safety as separate questions. The registry only proves who deployed something.
-- Registration is first-write only and requires code to already exist at the computed address. Treat both as part of the registry’s guarantee, not just implementation details.
+- Registration is first-write only and requires code to already exist at the computed address.
 - When a task involves wrong or missing registry data, verify the registration inputs before assuming a contract bug.

package/USER_JOURNEYS.md

@@ -2,15 +2,13 @@
 
 ## Repo Purpose
 
-This repo records deployer provenance for contracts whose address can be reconstructed from `create` or `create2` inputs.
-It does not say whether a deployment is safe, canonical, or approved. It only says who deployed it when the inputs are
-correct and someone registered them.
+This repo records deployer provenance for contracts whose address can be reconstructed from `create` or `create2` inputs. It does not say whether a deployment is safe, canonical, or approved. It only says who deployed it when the inputs are correct and someone registered them.
 
 ## Primary Actors
 
 - deployers who want onchain provenance for hooks, clones, and helper contracts
 - integrators who need to verify who deployed an address before trusting it
-- auditors who want a deterministic provenance check rather than offchain screenshots
+- auditors who want a deterministic provenance check instead of offchain screenshots
 
 ## Key Surfaces
 
@@ -43,7 +41,7 @@ correct and someone registered them.
 
 **Actor:** deployer, operator, or auditor with the original deterministic deployment inputs.
 
-**Intent:** bind a `create2` deployment to its deployer without needing privileged access.
+**Intent:** bind a `create2` deployment to its deployer without privileged access.
 
 **Preconditions**
 - the contract was deployed with `create2`

package/package.json

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

package/script/helpers/AddressRegistryDeploymentLib.sol

@@ -72,6 +72,8 @@ library AddressRegistryDeploymentLib {
         string memory deploymentJson =
         // forge-lint: disable-next-line(unsafe-cheatcode)
         vm.readFile(string.concat(path, projectName, "/", networkName, "/", contractName, ".json"));
-        return stdJson.readAddress({json: deploymentJson, key: ".address"});
+        address deployed = stdJson.readAddress({json: deploymentJson, key: ".address"});
+        require(deployed.code.length != 0, "AddressRegistryDeploymentLib: registry has no code");
+        return deployed;
     }
 }

package/test/audit/DeploymentHelperValidation.t.sol

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+import {stdJson} from "forge-std/Script.sol";
+
+import {
+    AddressRegistryDeploymentLib,
+    AddressRegistryDeployment
+} from "../../script/helpers/AddressRegistryDeploymentLib.sol";
+
+/// @notice Wrapper that makes the library's internal functions callable externally so vm.expectRevert works.
+contract DeploymentLibCaller {
+    function getDeployment(
+        string memory path,
+        string memory networkName
+    )
+        external
+        returns (AddressRegistryDeployment memory)
+    {
+        return AddressRegistryDeploymentLib.getDeployment({path: path, networkName: networkName});
+    }
+}
+
+/// @notice Tests M-40: Deployment helper rejects stale artifacts pointing to non-contract addresses.
+contract DeploymentHelperValidationTest is Test {
+    DeploymentLibCaller internal caller;
+
+    function setUp() public {
+        caller = new DeploymentLibCaller();
+    }
+
+    /// @notice Stale deployment artifact pointing to an EOA reverts.
+    function test_deploymentHelper_revertsForEOARegistry() external {
+        address eoa = makeAddr("staleEOA");
+        string memory json = string.concat('{"address":"', vm.toString(eoa), '"}');
+
+        string memory dir = "test/audit/tmp-eoa/nana-address-registry-v6/testnet/";
+        vm.createDir(dir, true);
+        vm.writeFile(string.concat(dir, "JBAddressRegistry.json"), json);
+
+        vm.expectRevert("AddressRegistryDeploymentLib: registry has no code");
+        caller.getDeployment({path: "test/audit/tmp-eoa/", networkName: "testnet"});
+
+        vm.removeFile(string.concat(dir, "JBAddressRegistry.json"));
+    }
+
+    /// @notice Valid deployment artifact with a contract address is accepted.
+    function test_deploymentHelper_acceptsContractRegistry() external {
+        address registry = makeAddr("registryContract");
+        vm.etch(registry, hex"6080604052");
+        string memory json = string.concat('{"address":"', vm.toString(registry), '"}');
+
+        string memory dir = "test/audit/tmp-contract/nana-address-registry-v6/testnet/";
+        vm.createDir(dir, true);
+        vm.writeFile(string.concat(dir, "JBAddressRegistry.json"), json);
+
+        caller.getDeployment({path: "test/audit/tmp-contract/", networkName: "testnet"});
+
+        vm.removeFile(string.concat(dir, "JBAddressRegistry.json"));
+    }
+}