@bananapus/address-registry-v6 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/address-registry-v6",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,5 +22,12 @@
   },
   "devDependencies": {
     "@sphinx-labs/plugins": "0.33.3"
-  }
+  },
+  "files": [
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/",
+    "src/"
+  ]
 }

package/ADMINISTRATION.md

@@ -1,67 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| 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 |
-
-## Purpose
-
-`nana-address-registry-v6` has no admin surface. It is a permissionless first-write provenance registry.
-
-## Control Model
-
-- 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 |
-
-## Privileged Surfaces
-
-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]`
-
-## 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
-
-## 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, 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
-
-## Admin Boundaries
-
-- nobody can curate allowlists, edit entries, or block registration
-- nobody can use this registry to certify code safety
-
-## Source Map
-
-- `src/JBAddressRegistry.sol`
-- `src/interfaces/IJBAddressRegistry.sol`
-- `script/Deploy.s.sol`
-- `script/helpers/AddressRegistryDeploymentLib.sol`
-- `test/JBAddressRegistry_Fork.t.sol`
-- `test/regression/NonceTruncation.t.sol`

package/ARCHITECTURE.md

@@ -1,84 +0,0 @@
-# Architecture
-
-## Purpose
-
-`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
-
-The repo is intentionally small. `JBAddressRegistry` accepts deterministic deployment inputs, reconstructs the resulting address, and records the deployer if that address has not already been registered. It does not judge code safety, manage upgrades, or gate deployments.
-
-## 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
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBAddressRegistry` | Address derivation and first-write provenance storage | Main contract |
-| `IJBAddressRegistry` | Minimal lookup and registration interface | External surface |
-
-## 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
-
-## Critical Flows
-
-### Register
-
-```text
-caller
-  -> supplies deployer plus CREATE nonce or CREATE2 salt and bytecode
-  -> registry recomputes the target address
-  -> registry records the deployer if the address was previously unregistered
-```
-
-## Accounting Model
-
-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
-- overengineering is more dangerous than minimal, reviewable derivation code
-
-## Safe Change Guide
-
-- 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:
-  `test/JBAddressRegistry.t.sol`
-- edge-path validation and first-write behavior:
-  `test/JBAddressRegistryEdge.t.sol`
-- pre-registration, frontrun, and undeployed-code defenses:
-  `test/regression/RegressionFrontRunRegistrationDoS.t.sol`
-- provenance abuse and zero-deployer edge cases:
-  `test/regression/RegressionUnauthorizedRegistrar.t.sol`
-  `test/regression/ZeroDeployerRegistration.t.sol`
-
-## Source Map
-
-- `src/JBAddressRegistry.sol`
-- `src/interfaces/IJBAddressRegistry.sol`
-- `test/JBAddressRegistry.t.sol`
-- `test/JBAddressRegistryEdge.t.sol`
-- `test/regression/RegressionFrontRunRegistrationDoS.t.sol`
-- `test/regression/RegressionUnauthorizedRegistrar.t.sol`
-- `test/regression/ZeroDeployerRegistration.t.sol`
-- `test/regression/NonceTruncation.t.sol`
-- `script/Deploy.s.sol`
-- `script/helpers/AddressRegistryDeploymentLib.sol`
-- `references/runtime.md`
-- `references/operations.md`

package/AUDIT_INSTRUCTIONS.md

@@ -1,69 +0,0 @@
-# Audit Instructions
-
-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
-
-There is a billion dollars of well-meaning projects' money in the Juicebox Money Engine, growing exponentially. Your job is to hack it before anyone else. Whoever hacks it first saves/steals the money, and you are obsessed with being this winner, while also being a steward of the protocol and wanting it to keep growing safely.
-
-Suggestions of where to look:
-
-- let callers register contracts under the wrong deployer
-- break determinism or uniqueness assumptions around registration
-- let callers spoof provenance for contracts the claimed deployer did not create
-- create truncation-related collisions or stale mapping assumptions
-
-## Scope
-
-In scope:
-
-- `src/JBAddressRegistry.sol`
-- `src/interfaces/IJBAddressRegistry.sol`
-- all deployment helpers in `script/`
-
-## Start Here
-
-1. `src/JBAddressRegistry.sol`
-2. `script/Deploy.s.sol`
-
-## 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
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Registrant | Register contracts by supplying deterministic deployment inputs | Must supply inputs that reconstruct an already-deployed contract address |
-| Registry reader | Interpret provenance for downstream decisions | Must pair provenance with an external trust model |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| Approved deployers | Produce the addresses they claim | Downstream provenance gates become meaningless |
-
-## Critical Invariants
-
-1. Provenance cannot be forged.  
-   Only inputs matching the actual deployer path 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
-
-- registration entrypoints that rely on deployer provenance
-- overwrite and replay paths
-- deterministic deployment assumptions
-- zero-address or malformed registration attempts
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/CHANGELOG.md

@@ -1,39 +0,0 @@
-# Changelog
-
-## Scope
-
-This file describes the verified change from `nana-address-registry-v5` to the current `nana-address-registry-v6` repo.
-
-## Current v6 surface
-
-- `JBAddressRegistry`
-- `IJBAddressRegistry`
-
-## Summary
-
-- Nonce handling is safer than in v5. The registry now guards against oversized nonces instead of silently producing the wrong derived address once the old encoding assumptions stopped holding.
-- Zero-address deployers are explicitly rejected.
-- The external surface remains intentionally small. This repo changed behavior more than shape.
-- The repo moved from the v5 Solidity baseline to `0.8.28`.
-
-## Verified deltas
-
-- `_addressFrom(...)` now supports RLP nonce encoding through `uint64` instead of stopping at the old `uint32` path.
-- `JBAddressRegistry_NonceTooLarge(uint256)` is thrown above that supported range.
-- `JBAddressRegistry_ZeroDeployer()` is thrown when trying to register against `address(0)`.
-- Duplicate registration now explicitly reverts with `JBAddressRegistry_AlreadyRegistered(address)`.
-
-## Breaking ABI changes
-
-- There is no meaningful function-selector migration here.
-- The practical ABI-visible change is new custom errors that callers and tooling may need to decode.
-
-## Indexer impact
-
-- Event shape is effectively unchanged.
-- The real migration concern is stricter revert behavior for previously tolerated bad inputs.
-
-## Migration notes
-
-- If you treated this repo as ABI-stable, that is mostly still true, but behavior around bad inputs is stricter.
-- Recheck any tool that depended on silent high-nonce behavior. v6 makes that path explicit instead of permissive.

package/RISKS.md

@@ -1,58 +0,0 @@
-# Juicebox Address Registry Risk Register
-
-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
-
-- 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 | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P1 | Over-trusting registration as safety approval | A registered deployer mapping does not mean the contract is reviewed, 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 proof of malice. | Treat registry data as additive metadata, not an allowlist. |
-
-## 1. Trust Assumptions
-
-- **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 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, review 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 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
-
-- `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
-
-### 5.1 The registry does not authenticate the registrant
-
-This is intentional. `JBAddressRegistry` is a deterministic provenance registry, not a permissioned attestation service.
-
-### 5.2 Unregistered does not mean unsafe
-
-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 protect an undeployed `CREATE2` address from later first-writer capture.

package/SKILLS.md

@@ -1,41 +0,0 @@
-# Juicebox Address Registry
-
-## Use This File For
-
-- Use this file when the task involves deployer provenance, `create` or `create2` registration logic, or determining what the registry does and does not prove.
-- Start here, then decide whether the issue is `create` address derivation, `create2` derivation, or misuse of provenance as a trust signal.
-
-## Read This Next
-
-| If you need... | Open this next |
-|---|---|
-| Repo overview and intended guarantees | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Registry implementation | [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol) |
-| Runtime and operational assumptions | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
-| Interfaces and deployment | [`src/interfaces/`](./src/interfaces/), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Edge and fork coverage | [`test/JBAddressRegistry.t.sol`](./test/JBAddressRegistry.t.sol), [`test/JBAddressRegistryEdge.t.sol`](./test/JBAddressRegistryEdge.t.sol), [`test/JBAddressRegistry_Fork.t.sol`](./test/JBAddressRegistry_Fork.t.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contract | [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol) |
-| Interfaces | [`src/interfaces/`](./src/interfaces/) |
-| Scripts | [`script/`](./script/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-Permissionless on-chain provenance registry that records which deployer created a contract by reconstructing deterministic `create` or `create2` addresses from the supplied deployment inputs.
-
-## 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 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.
-- When a task involves wrong or missing registry data, verify the registration inputs before assuming a contract bug.