@bananapus/address-registry-v6 0.0.17 → 0.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/ADMINISTRATION.md +41 -48
  2. package/ARCHITECTURE.md +63 -27
  3. package/AUDIT_INSTRUCTIONS.md +26 -12
  4. package/README.md +37 -3
  5. package/RISKS.md +37 -21
  6. package/SKILLS.md +4 -2
  7. package/USER_JOURNEYS.md +71 -22
  8. package/package.json +1 -1
  9. package/references/operations.md +2 -0
  10. package/references/runtime.md +2 -0
package/ADMINISTRATION.md CHANGED
@@ -1,74 +1,67 @@
1
1
  # Administration
2
2
 
3
- Admin privileges and their scope in nana-address-registry-v6.
4
-
5
3
  ## At A Glance
6
4
 
7
5
  | Item | Details |
8
- |------|---------|
9
- | Scope | Permissionless deployer registration and lookup only. There is no privileged admin surface. |
10
- | Operators | Anyone can register address/deployer relationships; clients decide which deployers they trust. |
11
- | Highest-risk actions | Relying on stale cached registry data or treating registry entries as trust endorsements instead of raw claims. |
12
- | Recovery posture | Registry entries can be overwritten but not deleted. Operational recovery is client-side: re-check entries, maintain trusted deployer lists, or migrate consumers to a new registry. |
13
-
14
- ## Routine Operations
6
+ | --- | --- |
7
+ | Scope | Permissionless provenance registration for CREATE and CREATE2 addresses |
8
+ | Control posture | Fully permissionless and adminless |
9
+ | Highest-risk actions | Incorrect first registration or bad derivation assumptions in offchain tooling |
10
+ | Recovery posture | No in-place recovery; replacement contract is the only fix for logic mistakes |
15
11
 
16
- - Re-check `deployerOf()` at time of use instead of caching it indefinitely.
17
- - Pair registry lookups with a separate trusted-deployer allowlist in clients or indexing infrastructure.
18
- - Treat every registration as permissionless input, not proof that the caller was authorized by the deployer.
12
+ ## Purpose
19
13
 
20
- ## One-Way Or High-Risk Actions
14
+ `nana-address-registry-v6` has no admin surface. It is a permissionless first-write provenance registry.
21
15
 
22
- - There is no pause, owner override, or deletion path.
23
- - A later registration can overwrite an earlier mapping for the same computed address.
24
- - The registry does not verify that code is deployed at the registered address.
16
+ ## Control Model
25
17
 
26
- ## Recovery Notes
27
-
28
- - If client trust assumptions change, fix the client or indexer. The contract itself cannot block or roll back bad registrations.
29
- - If the ecosystem needs different trust guarantees, the recovery path is a new registry design and client migration, not an admin action here.
18
+ - No owner
19
+ - No governance
20
+ - No pause
21
+ - No upgrade
22
+ - Registration is permissionless and correctness comes from deterministic address derivation
30
23
 
31
24
  ## Roles
32
25
 
33
- None. `JBAddressRegistry` has no owner, no admin, and no access control. The contract does not inherit from `Ownable`, `AccessControl`, or any permissioned pattern.
26
+ | Role | How Assigned | Scope | Notes |
27
+ | --- | --- | --- | --- |
28
+ | Anyone | No assignment | Global | Can register an address if they provide correct CREATE or CREATE2 inputs |
29
+
30
+ ## Privileged Surfaces
34
31
 
35
- ## Privileged Functions
32
+ There are no privileged functions. `registerAddress(...)` is permissionless for both CREATE and CREATE2 registration paths.
36
33
 
37
- ### JBAddressRegistry
34
+ ## Immutable And One-Way
38
35
 
39
- | Function | Required Role | Permission ID | Scope | What It Does |
40
- |----------|--------------|---------------|-------|--------------|
41
- | `registerAddress(address deployer, uint256 nonce)` | None | N/A | Global | Computes a `create` address from deployer + nonce and stores the deployer mapping |
42
- | `registerAddress(address deployer, bytes32 salt, bytes bytecode)` | None | N/A | Global | Computes a `create2` address from deployer + salt + bytecode and stores the deployer mapping |
43
- | `deployerOf(address)` | None | N/A | Global | View function — returns the registered deployer for a given address |
36
+ - Registration is first-write only.
37
+ - There is no overwrite or delete path for `deployerOf[address]`.
44
38
 
45
- Every function is callable by any address. There are no restricted operations.
39
+ ## Operational Notes
46
40
 
47
- ## Registration Model
41
+ - Treat registration as provenance, not endorsement.
42
+ - Register addresses from trustworthy operational pipelines because bad first registration is sticky even though anyone can submit the correct derivation inputs.
48
43
 
49
- - **Fully permissionless.** Any address can register any deployer/nonce or deployer/salt/bytecode combination.
50
- - **No caller verification.** The registry does not check whether `msg.sender` is the deployer. It only verifies that the computed address is valid by storing the mapping.
51
- - **Overwritable.** A second registration for the same computed address overwrites the previous deployer mapping. Last writer wins.
52
- - **Permanent storage, no removal.** There is no `unregister` or `removeAddress` function. Entries can be overwritten but never deleted.
53
- - **No approval or queue.** Registrations take effect immediately in the same transaction.
44
+ ## Machine Notes
54
45
 
55
- ## Client-Side Trust
46
+ - Do not treat registration as a safety certification or allowlist signal.
47
+ - `src/JBAddressRegistry.sol` is the only control-relevant runtime file; there is no hidden owner path.
48
+ - If offchain derivation and onchain registration disagree, stop and resolve the derivation logic rather than assuming overwrite is possible.
56
49
 
57
- The registry stores deployer mappings without making trust judgments. All trust decisions are delegated to clients:
50
+ ## Recovery
58
51
 
59
- - **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()`.
60
- - **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.
61
- - **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.
62
- - **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).
52
+ - There is no admin recovery surface.
53
+ - If derivation logic were ever wrong, the contract would need replacement rather than intervention.
63
54
 
64
55
  ## Admin Boundaries
65
56
 
66
- There are no admins. Specifically:
57
+ - Nobody can curate allowlists, edit entries, or block registration.
58
+ - Nobody can use this registry to certify code safety.
67
59
 
68
- - **No pause mechanism.** The registry cannot be paused or frozen.
69
- - **No upgrade path.** The contract is not proxied or upgradeable.
70
- - **No fee extraction.** The contract holds no funds and collects no fees.
71
- - **No blocklist.** No address can be prevented from registering.
72
- - **No migration.** There is no way to transfer state to a new registry contract.
60
+ ## Source Map
73
61
 
74
- The only trust assumption is on the frontend side: clients must maintain their own list of trusted deployers and use `deployerOf()` to check whether a contract was deployed by one of them. The registry itself makes no trust judgments.
62
+ - `src/JBAddressRegistry.sol`
63
+ - `src/interfaces/IJBAddressRegistry.sol`
64
+ - `script/Deploy.s.sol`
65
+ - `script/helpers/AddressRegistryDeploymentLib.sol`
66
+ - `test/JBAddressRegistry_Fork.t.sol`
67
+ - `test/regression/NonceTruncation.t.sol`
package/ARCHITECTURE.md CHANGED
@@ -2,47 +2,83 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- `nana-address-registry-v6` is a tiny trust-attestation primitive. It records who deployed a contract by recomputing the deployed address from CREATE or CREATE2 inputs and storing the verified deployer on-chain.
5
+ `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.
6
6
 
7
- ## Boundaries
7
+ ## System Overview
8
8
 
9
- - The repo does not assess contract safety.
10
- - It does not manage upgrades, ownership, or deployment permissions.
11
- - It only answers one question: "which deployer could have created this address?"
9
+ 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.
12
10
 
13
- ## Main Components
11
+ ## Core Invariants
14
12
 
15
- | Component | Responsibility |
16
- | --- | --- |
17
- | `JBAddressRegistry` | Verifies deterministic address derivation and stores `deployerOf[address]` |
18
- | `IJBAddressRegistry` | Minimal public interface for registration and lookup |
13
+ - Registration is permissionless because correctness comes from deterministic derivation, not caller authority.
14
+ - A contract address can only be registered once.
15
+ - Registration must fail until runtime code actually exists at the derived address.
16
+ - CREATE and CREATE2 derivation must match EVM rules exactly.
19
17
 
20
- ## Runtime Model
18
+ ## Modules
19
+
20
+ | Module | Responsibility | Notes |
21
+ | --- | --- | --- |
22
+ | `JBAddressRegistry` | Address derivation and first-write provenance storage | Main contract |
23
+ | `IJBAddressRegistry` | Minimal lookup and registration interface | External surface |
24
+
25
+ ## Trust Boundaries
26
+
27
+ - The registry attests to deterministic provenance, not code quality.
28
+ - It does not manage ownership, upgrades, or allowlists.
29
+ - External systems may trust its recorded provenance, so derivation correctness is the whole product.
30
+
31
+ ## Critical Flows
32
+
33
+ ### Register
21
34
 
22
35
  ```text
23
36
  caller
24
- -> provides deployer plus CREATE nonce or CREATE2 salt+bytecode
37
+ -> supplies deployer plus CREATE nonce or CREATE2 salt and bytecode
25
38
  -> registry recomputes the target address
26
- -> registry stores the deployer for that address if it was not already registered
39
+ -> registry records the deployer if the address was previously unregistered
27
40
  ```
28
41
 
29
- ## Critical Invariants
30
-
31
- - Registration is permissionless because correctness comes from deterministic address derivation, not caller authority.
32
- - Re-registration must stay impossible.
33
- - CREATE and CREATE2 derivations must match EVM address derivation exactly; this repo is useless if the reconstruction is even slightly wrong.
34
-
35
- ## Where Complexity Lives
42
+ ## Accounting Model
36
43
 
37
- - Almost all of the risk is concentrated in a tiny amount of derivation logic.
38
- - The repo is simple enough that overengineering is a bigger risk than underengineering.
44
+ No economic accounting lives here. The only critical state is `deployerOf[address]`.
39
45
 
40
- ## Dependencies
46
+ ## Security Model
41
47
 
42
- - None that matter semantically beyond Solidity's address derivation rules
48
+ - The risk is concentrated in a small amount of address-derivation logic.
49
+ - The registry records the derived deployer, not the transaction caller. Mixing those concepts would turn provenance into an authority bug.
50
+ - Overengineering is more dangerous than minimal, auditable derivation code.
43
51
 
44
52
  ## Safe Change Guide
45
53
 
46
- - Treat derivation logic as cryptographic plumbing. Prefer no change over clever change.
47
- - If you touch nonce handling or bytecode hashing, add or retain tests for both CREATE and CREATE2 paths.
48
- - Do not turn this registry into a trust oracle. Keep the scope narrow.
54
+ - Treat derivation code like cryptographic plumbing.
55
+ - Keep the undeployed-address check and first-write-only rule intact; they are part of the provenance guarantee, not optional hygiene.
56
+ - If nonce handling or bytecode hashing changes, keep CREATE and CREATE2 tests aligned.
57
+ - Do not expand the repo into an allowlist or trust-oracle system.
58
+
59
+ ## Canonical Checks
60
+
61
+ - CREATE and CREATE2 derivation correctness:
62
+ `test/JBAddressRegistry.t.sol`
63
+ - edge-path validation and first-write behavior:
64
+ `test/JBAddressRegistryEdge.t.sol`
65
+ - pre-registration, frontrun, and undeployed-code defenses:
66
+ `test/audit/CodexFrontRunRegistrationDoS.t.sol`
67
+ - provenance abuse and zero-deployer edge cases:
68
+ `test/audit/CodexUnauthorizedRegistrar.t.sol`
69
+ `test/audit/ZeroDeployerRegistration.t.sol`
70
+
71
+ ## Source Map
72
+
73
+ - `src/JBAddressRegistry.sol`
74
+ - `src/interfaces/IJBAddressRegistry.sol`
75
+ - `test/JBAddressRegistry.t.sol`
76
+ - `test/JBAddressRegistryEdge.t.sol`
77
+ - `test/audit/CodexFrontRunRegistrationDoS.t.sol`
78
+ - `test/audit/CodexUnauthorizedRegistrar.t.sol`
79
+ - `test/audit/ZeroDeployerRegistration.t.sol`
80
+ - `test/regression/NonceTruncation.t.sol`
81
+ - `script/Deploy.s.sol`
82
+ - `script/helpers/AddressRegistryDeploymentLib.sol`
83
+ - `references/runtime.md`
84
+ - `references/operations.md`
package/AUDIT_INSTRUCTIONS.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  This repo is a small registry, but it participates in deployer verification across the ecosystem. Treat incorrect registration as a security boundary failure.
4
4
 
5
- ## Objective
5
+ ## Audit Objective
6
6
 
7
7
  Find issues that:
8
8
  - let callers register contracts under the wrong deployer
@@ -15,14 +15,32 @@ Find issues that:
15
15
  In scope:
16
16
  - `src/JBAddressRegistry.sol`
17
17
  - `src/interfaces/IJBAddressRegistry.sol`
18
- - deployment scripts in `script/`
18
+ - all deployment helpers in `script/`
19
19
 
20
- ## System Model
20
+ ## Start Here
21
+
22
+ 1. `src/JBAddressRegistry.sol`
23
+ 2. `script/Deploy.s.sol`
24
+
25
+ ## Security Model
21
26
 
22
27
  The registry maps deployed addresses to the deployer that created them. Downstream repos use it to:
23
28
  - validate provenance for clones or deterministically deployed instances
24
29
  - discover whether a contract came from an approved deployer path
25
30
 
31
+ ## Roles And Privileges
32
+
33
+ | Role | Powers | How constrained |
34
+ |------|--------|-----------------|
35
+ | Deployer | Register contracts as its outputs | Must prove authentic deployment provenance |
36
+ | Registry reader | Trust provenance for privileged decisions | Must not observe spoofable or mutable history |
37
+
38
+ ## Integration Assumptions
39
+
40
+ | Dependency | Assumption | What breaks if wrong |
41
+ |------------|------------|----------------------|
42
+ | Approved deployers | Produce the addresses they claim | Downstream provenance gates become meaningless |
43
+
26
44
  ## Critical Invariants
27
45
 
28
46
  1. Provenance cannot be forged
@@ -34,19 +52,15 @@ No aliasing or overwrite path should let a later caller replace provenance unexp
34
52
  3. Registration metadata is stable
35
53
  Nonce, salt, or address truncation must not allow collisions or stale reads.
36
54
 
37
- ## Threat Model
55
+ ## Attack Surfaces
38
56
 
39
- Prioritize:
57
+ - registration entrypoints that rely on deployer provenance
58
+ - overwrite and replay paths
59
+ - deterministic deployment assumptions
40
60
  - zero-address or malformed registration attempts
41
- - deterministic deployment edge cases
42
- - overwrite or replay behavior
43
- - any assumption that `msg.sender` is sufficient proof without deployment linkage
44
61
 
45
- ## Build And Verification
62
+ ## Verification
46
63
 
47
- Standard workflow:
48
64
  - `npm install`
49
65
  - `forge build`
50
66
  - `forge test`
51
-
52
- Tests already focus on zero deployers and nonce-truncation regressions. A meaningful finding here should show downstream trust in the registry becoming misplaced, not just a cosmetic mismatch.
package/README.md CHANGED
@@ -1,8 +1,13 @@
1
1
  # Juicebox Address Registry
2
2
 
3
- `@bananapus/address-registry-v6` is a permissionless registry that records which deployer created a contract. It is meant to make deployer provenance visible on-chain, especially for hooks and helper contracts that users may need to trust before interacting with them.
3
+ `@bananapus/address-registry-v6` is a permissionless registry that records deployer provenance for contracts when callers provide matching `create` or `create2` deployment inputs. It is meant to make deployer provenance visible on-chain, especially for hooks and helper contracts that users may need to trust before interacting with them.
4
4
 
5
- Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
5
+ Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
6
+ User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)
7
+ Skills: [SKILLS.md](./SKILLS.md)
8
+ Risks: [RISKS.md](./RISKS.md)
9
+ Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)
10
+ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
6
11
 
7
12
  ## Overview
8
13
 
@@ -11,7 +16,7 @@ The registry supports both `create` and `create2` style deployments:
11
16
  - for `create`, it reconstructs the deployed address from the deployer and nonce
12
17
  - for `create2`, it reconstructs the deployed address from the deployer, salt, and deployment bytecode
13
18
 
14
- Because the address is computed deterministically, registrations do not require access control. Anyone can submit the correct deployment inputs, and the registry records the verified deployer for the computed address.
19
+ 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.
15
20
 
16
21
  Use this repo when deployer provenance matters. Do not confuse it with an allowlist, audit registry, or trust oracle.
17
22
 
@@ -33,6 +38,30 @@ The registry is intentionally narrow:
33
38
 
34
39
  Anything beyond that is out of scope by design.
35
40
 
41
+ ## Read These Files First
42
+
43
+ 1. `src/JBAddressRegistry.sol`
44
+ 2. `test/JBAddressRegistry.t.sol`
45
+ 3. `test/JBAddressRegistryEdge.t.sol`
46
+ 4. `test/audit/CodexFrontRunRegistrationDoS.t.sol`
47
+
48
+ ## Integration Traps
49
+
50
+ - provenance is only meaningful if callers also know what the deployer is supposed to be trusted for
51
+ - permissionless registration is intentional, so integrations should verify the computed inputs rather than assuming caller authority
52
+ - `create` nonce reconstruction and `create2` salt-bytecode reconstruction are different trust paths and should be reasoned about separately
53
+
54
+ ## Where State Lives
55
+
56
+ - deployer provenance lives in `JBAddressRegistry`
57
+ - deployment truth still lives outside this repo in the target chain history and bytecode inputs
58
+
59
+ ## High-Signal Tests
60
+
61
+ 1. `test/JBAddressRegistry.t.sol`
62
+ 2. `test/JBAddressRegistryEdge.t.sol`
63
+ 3. `test/audit/CodexUnauthorizedRegistrar.t.sol`
64
+
36
65
  ## Install
37
66
 
38
67
  ```bash
@@ -75,3 +104,8 @@ script/
75
104
  - provenance is not the same thing as safety; a known deployer can still deploy unsafe code
76
105
  - registrations are first-write only, so bad operational processes around initial registration can be sticky
77
106
  - the `create` address path relies on nonce reconstruction and intentionally rejects unrealistic nonce ranges
107
+
108
+ ## For AI Agents
109
+
110
+ - Describe this repo as a provenance registry, not as an allowlist or safety oracle.
111
+ - Read the edge and audit tests before making claims about frontrunning or unauthorized registration.
package/RISKS.md CHANGED
@@ -1,42 +1,58 @@
1
1
  # Juicebox Address Registry Risk Register
2
2
 
3
- This file focuses on the registry's core promise: recording claimed deployer linkage for deterministically derived contracts. The main risks are misuse, incorrect assumptions about what registration means, and collisions between social trust and on-chain truth.
3
+ 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.
4
4
 
5
5
  ## How to use this file
6
6
 
7
- - Read `Priority risks` first; the biggest risks here are almost all interpretive, not balance-sheet failures.
8
- - Use the detailed sections to distinguish what the registry proves from what users may incorrectly infer from it.
9
- - Treat `Invariants to Verify` as the minimal safety envelope for deterministic registration.
7
+ - Read `Priority risks` first; most failures here are interpretive and integration-driven.
8
+ - Distinguish "address can be derived from these deployment inputs" from "this deployment is trusted".
9
+ - Treat `Invariants to Verify` as the narrow correctness envelope of the registry itself.
10
10
 
11
11
  ## Priority risks
12
12
 
13
13
  | Priority | Risk | Why it matters | Primary controls |
14
14
  |----------|------|----------------|------------------|
15
- | P1 | Over-trusting registration as approval | The registry proves deployer linkage, not code safety or ecosystem endorsement. Users can still trust malicious deployments. | Clear docs, UI labeling, and strict separation between proof of origin and proof of safety. |
16
- | P1 | Incorrect deployment-parameter assumptions | Deterministic verification is only as good as the deployment parameters supplied. Wrong assumptions create false negatives or confusing operator workflows. | Strong test coverage around CREATE and CREATE2 derivation and explicit documentation. |
17
- | P2 | Registry completeness assumptions | Useful contracts may remain unregistered; absence from the registry is not proof of absence or malice. | Operational guidance for clients and integrators to treat registration as additive evidence only. |
18
-
15
+ | 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. |
16
+ | 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. |
17
+ | 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. |
19
18
 
20
19
  ## 1. Trust Assumptions
21
20
 
22
- - **Self-registration.** Anyone can register any address. The registry does NOT verify that the caller actually deployed the contract. It only verifies that the computed address matches the provided deployer/nonce or deployer/salt/bytecode parameters.
23
- - **Frontend trust.** Frontends must maintain their own list of trusted deployers. The registry provides the mapping, not a trust judgment.
21
+ - **Deterministic address formulas.** The contract trusts its CREATE and CREATE2 address-derivation logic to match EVM semantics.
22
+ - **Consumer trust policy.** The registry does not decide which deployers are trusted. Every consumer must maintain that policy externally.
24
23
 
25
24
  ## 2. Known Risks
26
25
 
27
- - **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.
28
- - **No removal mechanism.** Once registered, an entry cannot be removed. Re-registration of the same address reverts with `JBAddressRegistry_AlreadyRegistered`.
29
- - **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.
30
- - **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.
26
+ - **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.
27
+ - **First registration wins.** Once `deployerOf[addr]` is set, later registrations revert with `JBAddressRegistry_AlreadyRegistered`, even if a different valid provenance claim exists.
28
+ - **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.
29
+ - **No removal or correction path.** The registry is intentionally append-only per address. Mistakes are sticky.
30
+ - **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.
31
+ - **Operational lag matters.** If a trusted deployer forgets to register immediately, someone else can publish the first valid claim for that address.
32
+
33
+ ## 3. Integration Risks
34
+
35
+ - **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".
36
+ - **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".
37
+ - **Off-chain explorers should preserve uncertainty.** A better label is "registered deployer claim" than "deployed by", unless the explorer independently verified the transaction history.
38
+
39
+ ## 4. Invariants to Verify
40
+
41
+ - `deployerOf[addr]` is set at most once.
42
+ - CREATE registrations only succeed for addresses derivable from the provided `(deployer, nonce)`.
43
+ - CREATE2 registrations only succeed for addresses derivable from the provided `(deployer, salt, bytecode)`.
44
+ - `_addressFrom` remains correct for the supported nonce range and reverts outside that range.
45
+
46
+ ## 5. Accepted Behaviors
47
+
48
+ ### 5.1 The registry does not authenticate the registrant
31
49
 
32
- ## 3. Invariants to Verify
50
+ This is intentional. `JBAddressRegistry` is a deterministic provenance registry, not a permissioned attestation service.
33
51
 
34
- - `deployerOf[addr]` always corresponds to a valid deployer/nonce pair that produces `addr` (if registered via `registerAddress`).
35
- - `create2` registrations: `deployerOf[addr]` corresponds to a valid deployer/salt/bytecode combination whose `keccak256(bytecode)` produces `addr` via the CREATE2 formula.
36
- - Registration idempotency: `deployerOf[addr]` reflects the first and only registration. Subsequent attempts to register the same address revert with `JBAddressRegistry_AlreadyRegistered`.
52
+ ### 5.2 Unregistered does not mean unsafe
37
53
 
38
- ## 4. Accepted Behaviors
54
+ 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.
39
55
 
40
- ### 4.1 RLP encoding correctness is well-tested and bounded
56
+ ### 5.3 The registry is retrospective, not a reservation layer
41
57
 
42
- 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.
58
+ 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.
package/SKILLS.md CHANGED
@@ -3,7 +3,7 @@
3
3
  ## Use This File For
4
4
 
5
5
  - Use this file when the task involves deployer provenance, `create` or `create2` registration logic, or determining what the registry does and does not prove.
6
- - Start here, then open the registry contract or tests that match the registration mode under review.
6
+ - Start here, then decide whether the issue is `create` address derivation, `create2` derivation, or misuse of provenance as a trust signal.
7
7
 
8
8
  ## Read This Next
9
9
 
@@ -11,8 +11,9 @@
11
11
  |---|---|
12
12
  | Repo overview and intended guarantees | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
13
13
  | Registry implementation | [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol) |
14
+ | Runtime and operational assumptions | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
14
15
  | Interfaces and deployment | [`src/interfaces/`](./src/interfaces/), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
15
- | Edge, fork, or regression coverage | [`test/JBAddressRegistry.t.sol`](./test/JBAddressRegistry.t.sol), [`test/JBAddressRegistryEdge.t.sol`](./test/JBAddressRegistryEdge.t.sol), [`test/regression/`](./test/regression/) |
16
+ | 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) |
16
17
 
17
18
  ## Repo Map
18
19
 
@@ -36,4 +37,5 @@ Permissionless on-chain provenance registry that records which deployer created
36
37
 
37
38
  - Start in [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol). This repo is intentionally small, so most questions should collapse quickly to the core contract.
38
39
  - Treat provenance and safety as separate questions. The registry only proves who deployed something.
40
+ - 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.
39
41
  - When a task involves wrong or missing registry data, verify the registration inputs before assuming a contract bug.
package/USER_JOURNEYS.md CHANGED
@@ -1,43 +1,92 @@
1
1
  # User Journeys
2
2
 
3
- ## Who This Repo Serves
3
+ ## Repo Purpose
4
4
 
5
- - deployers that want on-chain provenance for helper contracts and hooks
6
- - integrators checking who deployed an existing address
7
- - auditors verifying deterministic deployment claims
5
+ This repo records deployer provenance for contracts whose address can be reconstructed from `create` or `create2` inputs.
6
+ It does not say whether a deployment is safe, canonical, or approved. It only says who deployed it when the inputs are
7
+ correct and someone registered them.
8
+
9
+ ## Primary Actors
10
+
11
+ - deployers who want onchain provenance for hooks, clones, and helper contracts
12
+ - integrators who need to verify who deployed an address before trusting it
13
+ - auditors who want a deterministic provenance check rather than offchain screenshots
14
+
15
+ ## Key Surfaces
16
+
17
+ - `JBAddressRegistry`: stores `deployerOf[address]` after reconstructing the target address from deployment inputs
18
+ - `registerAddress(deployer, nonce)` and `registerAddress(deployer, salt, bytecode)`: the two provenance-registration paths
8
19
 
9
20
  ## Journey 1: Register A `CREATE` Deployment
10
21
 
11
- **Starting state:** you know the deploying address and nonce for a contract already created with `create`.
22
+ **Actor:** deployer, operator, or auditor with the original deployment inputs.
23
+
24
+ **Intent:** bind an already-deployed `create` address to the account that deployed it.
25
+
26
+ **Preconditions**
27
+ - the contract was deployed with `create`
28
+ - the caller knows the deployer address and nonce used for the deployment
29
+ - the address has not already been registered
12
30
 
13
- **Success:** the registry stores the verified deployer for the computed contract address.
31
+ **Main Flow**
32
+ 1. Call `registerAddress(deployer, nonce)`.
33
+ 2. `JBAddressRegistry` reconstructs the deployed address from the deployer and nonce.
34
+ 3. If the computed address is valid and unused, the registry stores `deployerOf[address] = deployer`.
14
35
 
15
- **Flow**
16
- 1. Call the `registerAddress` overload for `create` deployments with the deployer and nonce.
17
- 2. `JBAddressRegistry` reconstructs the expected deployed address.
18
- 3. If the reconstruction matches a real address and no one registered it before, the registry stores `deployerOf[address]`.
36
+ **Failure Modes**
37
+ - the nonce does not match the real deployment
38
+ - the computed address has already been registered
39
+ - the nonce exceeds the supported `uint64` range and registration reverts
40
+ - the deployment assumptions are wrong and the reconstructed address is useless
19
41
 
20
42
  ## Journey 2: Register A `CREATE2` Deployment
21
43
 
22
- **Starting state:** you know the deployer, salt, and init code for a deterministic deployment.
44
+ **Actor:** deployer, operator, or auditor with the original deterministic deployment inputs.
23
45
 
24
- **Success:** the registry records the verified deployer for the deterministic address without any privileged access.
46
+ **Intent:** bind a `create2` deployment to its deployer without needing privileged access.
25
47
 
26
- **Flow**
27
- 1. Call the `registerAddress` overload for `create2`.
28
- 2. The registry hashes deployer, salt, and deployment bytecode to reconstruct the deterministic address.
29
- 3. It stores the deployer for that address if the registration is valid and unused.
48
+ **Preconditions**
49
+ - the contract was deployed with `create2`
50
+ - the caller knows the deployer, salt, and init code
51
+ - the address has not already been registered
52
+
53
+ **Main Flow**
54
+ 1. Call `registerAddress(deployer, salt, bytecode)`.
55
+ 2. The registry reconstructs the deterministic address from the standard `create2` formula.
56
+ 3. If the address is valid and unused, the registry records the deployer.
57
+
58
+ **Failure Modes**
59
+ - the bytecode or salt is wrong
60
+ - the address was registered already
61
+ - a third party publishes the first valid provenance claim before the expected deployer registers it
62
+ - operators assume registration proves a contract exists there right now
63
+ - consumers misread provenance as an allowlist or audit stamp
30
64
 
31
65
  ## Journey 3: Resolve Provenance For An Existing Address
32
66
 
33
- **Starting state:** an integration or auditor sees a contract address and wants to know who deployed it.
67
+ **Actor:** integrator, frontend, or auditor.
68
+
69
+ **Intent:** answer "who deployed this?" before trusting a hook, helper, or clone.
70
+
71
+ **Preconditions**
72
+ - the address was registered previously
73
+ - the caller understands that an empty result means "unknown" rather than "unsafe"
74
+
75
+ **Main Flow**
76
+ 1. Query `deployerOf[address]`.
77
+ 2. If a deployer is present, use it as provenance evidence for who originated the deployment.
78
+ 3. If no deployer is present, treat the address as unregistered and keep investigating elsewhere.
79
+ 4. Pair the result with an external trust list, transaction history, or audit context before relying on the contract.
80
+
81
+ **Postconditions**
82
+ - downstream reviewers know which deployer or factory to inspect next
83
+ - the trust decision still happens outside this repo
34
84
 
35
- **Success:** the caller can query `deployerOf[address]` and get provenance if someone registered it correctly.
85
+ ## Trust Boundaries
36
86
 
37
- **Flow**
38
- 1. Look up the address in the registry.
39
- 2. If a deployer is present, use that as provenance evidence for who originated the deployment.
40
- 3. Treat absence as "not registered," not as a trust verdict on the code.
87
+ - this repo only proves registered deployer provenance from deterministic inputs
88
+ - anyone can submit a valid claim, so the mapping authenticates deployment inputs rather than caller identity
89
+ - it does not prove code quality, audit status, or governance approval
41
90
 
42
91
  ## Hand-Offs
43
92
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bananapus/address-registry-v6",
3
- "version": "0.0.17",
3
+ "version": "0.0.18",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
package/references/operations.md CHANGED
@@ -5,8 +5,10 @@
5
5
  - If you edit `create` reconstruction logic, verify nonce-boundary behavior.
6
6
  - If you edit `create2` behavior, verify bytecode hashing and salt assumptions.
7
7
  - If a user asks whether a contract is "safe," redirect the question to code provenance plus code review, not the registry alone.
8
+ - If you change registration guards, re-read the audit tests before trusting a narrower unit proof.
8
9
 
9
10
  ## Common Failure Modes
10
11
 
11
12
  - Operators confuse deployer provenance with trustworthiness.
12
13
  - Registration is attempted with stale deployment inputs from another repo or environment.
14
+ - The wrong party is allowed to bind or front-run a computed address because the first-write assumption was weakened.
package/references/runtime.md CHANGED
@@ -15,3 +15,5 @@
15
15
  - [`test/JBAddressRegistry.t.sol`](../test/JBAddressRegistry.t.sol) for baseline behavior.
16
16
  - [`test/JBAddressRegistryEdge.t.sol`](../test/JBAddressRegistryEdge.t.sol) for boundary conditions.
17
17
  - [`test/JBAddressRegistry_Fork.t.sol`](../test/JBAddressRegistry_Fork.t.sol) for live assumptions.
18
+ - [`test/regression/NonceTruncation.t.sol`](../test/regression/NonceTruncation.t.sol) for nonce-width and reconstruction regressions.
19
+ - [`test/audit/ZeroDeployerRegistration.t.sol`](../test/audit/ZeroDeployerRegistration.t.sol), [`test/audit/CodexUnauthorizedRegistrar.t.sol`](../test/audit/CodexUnauthorizedRegistrar.t.sol), and [`test/audit/CodexFrontRunRegistrationDoS.t.sol`](../test/audit/CodexFrontRunRegistrationDoS.t.sol) for the abuse cases this repo is expected to resist.