@bananapus/address-registry-v6 0.0.16 → 0.0.17

package/ADMINISTRATION.md

@@ -2,6 +2,32 @@
 
 Admin privileges and their scope in nana-address-registry-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Permissionless deployer registration and lookup only. There is no privileged admin surface. |
+| Operators | Anyone can register address/deployer relationships; clients decide which deployers they trust. |
+| Highest-risk actions | Relying on stale cached registry data or treating registry entries as trust endorsements instead of raw claims. |
+| 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. |
+
+## Routine Operations
+
+- Re-check `deployerOf()` at time of use instead of caching it indefinitely.
+- Pair registry lookups with a separate trusted-deployer allowlist in clients or indexing infrastructure.
+- Treat every registration as permissionless input, not proof that the caller was authorized by the deployer.
+
+## One-Way Or High-Risk Actions
+
+- There is no pause, owner override, or deletion path.
+- A later registration can overwrite an earlier mapping for the same computed address.
+- The registry does not verify that code is deployed at the registered address.
+
+## Recovery Notes
+
+- If client trust assumptions change, fix the client or indexer. The contract itself cannot block or roll back bad registrations.
+- If the ecosystem needs different trust guarantees, the recovery path is a new registry design and client migration, not an admin action here.
+
 ## Roles
 
 None. `JBAddressRegistry` has no owner, no admin, and no access control. The contract does not inherit from `Ownable`, `AccessControl`, or any permissioned pattern.

package/ARCHITECTURE.md

@@ -1,57 +1,48 @@
-# nana-address-registry-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-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`?"
+`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.
 
-`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.
+## Boundaries
 
-## Contract Map
+- The repo does not assess contract safety.
+- It does not manage upgrades, ownership, or deployment permissions.
+- It only answers one question: "which deployer could have created this address?"
 
-```
-src/
-├── JBAddressRegistry.sol     — Registry: registerAddress (create/create2), deployerOf mapping
-└── interfaces/
-    └── IJBAddressRegistry.sol — Interface
-```
-
-## Key Operations
+## Main Components
 
-### Registration (create)
-```
-Deployer → JBAddressRegistry.registerAddress(deployer, nonce)
-  → Compute address via RLP encoding of [deployer, nonce]
-  → Store deployerOf[computedAddress] = deployer
-  → Emit AddressRegistered
-```
+| Component | Responsibility |
+| --- | --- |
+| `JBAddressRegistry` | Verifies deterministic address derivation and stores `deployerOf[address]` |
+| `IJBAddressRegistry` | Minimal public interface for registration and lookup |
 
-### Registration (create2)
-```
-Deployer → JBAddressRegistry.registerAddress(deployer, salt, bytecode)
-  → Compute address via keccak256(0xff ++ deployer ++ salt ++ keccak256(bytecode))
-  → Store deployerOf[computedAddress] = deployer
-  → Emit AddressRegistered
-```
+## Runtime Model
 
-### Verification
-```
-Frontend → JBAddressRegistry.deployerOf(hookAddress)
-  → Returns deployer address (or address(0) if unregistered)
-  → Frontend checks deployer against trusted deployer list
+```text
+caller
+  -> provides deployer plus CREATE nonce or CREATE2 salt+bytecode
+  -> registry recomputes the target address
+  -> registry stores the deployer for that address if it was not already registered
 ```
 
-## Design Decisions
+## Critical Invariants
 
-**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.
+- Registration is permissionless because correctness comes from deterministic address derivation, not caller authority.
+- Re-registration must stay impossible.
+- CREATE and CREATE2 derivations must match EVM address derivation exactly; this repo is useless if the reconstruction is even slightly wrong.
 
-**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.
+## Where Complexity Lives
 
-**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.
+- Almost all of the risk is concentrated in a tiny amount of derivation logic.
+- The repo is simple enough that overengineering is a bigger risk than underengineering.
 
 ## Dependencies
 
-- `@sphinx-labs/plugins` — Deployment tooling (devDependency only)
+- None that matter semantically beyond Solidity's address derivation rules
+
+## Safe Change Guide
 
-No runtime Solidity dependencies — this is a standalone contract.
+- Treat derivation logic as cryptographic plumbing. Prefer no change over clever change.
+- If you touch nonce handling or bytecode hashing, add or retain tests for both CREATE and CREATE2 paths.
+- Do not turn this registry into a trust oracle. Keep the scope narrow.

package/AUDIT_INSTRUCTIONS.md

@@ -1,147 +1,52 @@
-# Audit Instructions -- nana-address-registry-v6
+# Audit Instructions
 
-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.
+This repo is a small registry, but it participates in deployer verification across the ecosystem. Treat incorrect registration as a security boundary failure.
 
-## Compiler and Version Info
+## Objective
 
-| Setting | Value |
-|---------|-------|
-| Solidity version | 0.8.28 |
-| 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.
+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
 
 ## Scope
 
-**In scope -- all Solidity in `src/`:**
-```
-src/JBAddressRegistry.sol              # Registry implementation (~127 lines)
-src/interfaces/IJBAddressRegistry.sol  # Interface (~27 lines)
-```
-
-**Out of scope:** Test files, deployment scripts, forge-std.
-
-## Architecture
-
-### JBAddressRegistry
-
-A standalone, stateless-logic contract with a single storage mapping:
-
-```
-mapping(address addr => address deployer) public deployerOf;
-```
-
-Two public `registerAddress` overloads accept deployer parameters, compute the deterministic address, and store the mapping. No validation is performed beyond address computation and a nonce range check.
-
-### Registration (create)
-
-`registerAddress(address deployer, uint256 nonce)`:
-1. Calls `_addressFrom(deployer, nonce)` to compute the `create` address via RLP encoding
-2. Stores `deployerOf[computedAddress] = deployer`
-3. Emits `AddressRegistered(computedAddress, deployer, msg.sender)`
-
-### Registration (create2)
-
-`registerAddress(address deployer, bytes32 salt, bytes calldata bytecode)`:
-1. Computes `address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0xff), deployer, salt, keccak256(bytecode))))))`
-2. Stores `deployerOf[computedAddress] = deployer`
-3. Emits `AddressRegistered(computedAddress, deployer, msg.sender)`
-
-### RLP Encoding (_addressFrom)
-
-The internal `_addressFrom(address origin, uint256 nonce)` function implements RLP encoding of `[origin, nonce]` for `create` address computation. It handles 10 nonce ranges covering `0` through `type(uint64).max`:
-
-| Nonce Range | RLP Prefix Byte | Nonce Length Prefix |
-|-------------|----------------|---------------------|
-| `0` | `0xd6` | `0x80` (empty byte) |
-| `1 - 0x7f` | `0xd6` | (none, raw byte) |
-| `0x80 - 0xff` | `0xd7` | `0x81` |
-| `0x100 - 0xffff` | `0xd8` | `0x82` |
-| `0x10000 - 0xffffff` | `0xd9` | `0x83` |
-| `0x1000000 - 0xffffffff` | `0xda` | `0x84` |
-| `0x100000000 - 0xffffffffff` | `0xdb` | `0x85` |
-| `0x10000000000 - 0xffffffffffff` | `0xdc` | `0x86` |
-| `0x1000000000000 - 0xffffffffffffff` | `0xdd` | `0x87` |
-| `0x100000000000000 - 0xffffffffffffffff` | `0xde` | `0x88` |
-
-The final address is extracted from `keccak256(rlp_data)` via inline assembly: `mstore(0, hash); addr := mload(0)`.
-
-Nonces above `type(uint64).max` revert with `JBAddressRegistry_NonceTooLarge`.
-
-## Priority Audit Areas
-
-### 1. RLP Encoding Correctness (Highest Priority)
-
-The `_addressFrom` function is the only non-trivial logic in the contract. Verify:
-
-- **Every nonce range boundary is correct.** The if/else chain must produce correct RLP for every boundary value: `0`, `1`, `0x7f`, `0x80`, `0xff`, `0x100`, `0xffff`, `0x10000`, etc., up to `type(uint64).max`. An off-by-one at any boundary would silently produce wrong addresses.
-- **RLP prefix bytes are correct.** The first byte (`0xd6`-`0xde`) encodes the total length of the list. Verify each prefix matches the actual encoded data length (20-byte address + nonce encoding + overhead).
-- **Nonce encoding is correct.** For nonce `0`, the RLP encoding is `0x80` (empty byte string), not `0x00`. For nonces `1-0x7f`, the nonce IS the RLP encoding (single byte). For `0x80+`, a length prefix is prepended.
-- **Assembly address extraction.** The final `mstore(0, hash); addr := mload(0)` extracts the low 160 bits of the keccak256 hash. Verify this is equivalent to `address(uint160(uint256(hash)))`.
-- **Comparison with reference implementations.** Cross-check against the Ethereum Yellow Paper, OpenZeppelin's `Create2` library, and the linked StackExchange reference (https://ethereum.stackexchange.com/a/87840/68134).
-
-### 2. create2 Address Computation
-
-The `create2` overload uses `abi.encodePacked(bytes1(0xff), deployer, salt, keccak256(bytecode))`. Verify:
-- This matches the EIP-1014 specification exactly.
-- The `bytes calldata bytecode` parameter is hashed correctly (constructor arguments must be included by the caller; the contract does not append them).
-- No length ambiguity in the packed encoding (each component has fixed size: 1 + 20 + 32 + 32 = 85 bytes).
-
-### 3. Overwrite Behavior
-
-`_registerAddress` unconditionally overwrites `deployerOf[addr]`. Verify:
-- A re-registration with the same parameters produces the same result (idempotent).
-- A re-registration with different parameters that happen to compute the same address (collision) would overwrite. Since address collisions require a keccak256 collision, this is cryptographically infeasible -- but confirm there is no cheaper attack vector.
-- The `caller` field in the `AddressRegistered` event correctly reflects `msg.sender`, not the `deployer` parameter.
+In scope:
+- `src/JBAddressRegistry.sol`
+- `src/interfaces/IJBAddressRegistry.sol`
+- deployment scripts in `script/`
 
-### 4. Gas and DoS
+## System Model
 
-The contract has no loops, no arrays, and no unbounded storage growth beyond the mapping. Verify:
-- `registerAddress` has bounded gas cost regardless of inputs.
-- The `bytecode` parameter in the `create2` overload is hashed in memory. For very large bytecode, this could consume significant memory gas but cannot cause an OOG in the registry itself (the caller pays).
+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
 
-## Invariants to Verify
+## Critical Invariants
 
-1. **Determinism**: For any `(deployer, nonce)` pair, `_addressFrom` always returns the same address, and that address matches what the EVM would produce for a `create` deployment from `deployer` at `nonce`.
-2. **create2 correctness**: For any `(deployer, salt, bytecode)` triple, the computed address matches what the EVM would produce for a `create2` deployment.
-3. **No side effects**: `registerAddress` only modifies `deployerOf[computedAddress]` and emits one event. No other state is touched.
-4. **Nonce boundary completeness**: Every valid nonce (0 through `type(uint64).max`) produces a correct RLP encoding. No nonce in this range falls through without being encoded.
+1. Provenance cannot be forged
+Only the actual deployer path the registry intends to trust may create a successful registration for a contract.
 
-## Testing Setup
+2. One contract maps to one authoritative deployer record
+No aliasing or overwrite path should let a later caller replace provenance unexpectedly.
 
-```bash
-cd nana-address-registry-v6
-npm install
-forge build
-forge test
+3. Registration metadata is stable
+Nonce, salt, or address truncation must not allow collisions or stale reads.
 
-# Run edge case tests
-forge test --match-contract JBAddressRegistryEdge -vvv
+## Threat Model
 
-# Run nonce truncation regression test
-forge test --match-path test/regression/NonceTruncation.t.sol -vvv
+Prioritize:
+- zero-address or malformed registration attempts
+- deterministic deployment edge cases
+- overwrite or replay behavior
+- any assumption that `msg.sender` is sufficient proof without deployment linkage
 
-# Run fork tests
-forge test --match-contract Fork -vvv
+## Build And Verification
 
-# Write a PoC
-forge test --match-path test/audit/ExploitPoC.t.sol -vvv
-```
+Standard workflow:
+- `npm install`
+- `forge build`
+- `forge test`
 
-Go break it.
+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/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 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/README.md

@@ -1,99 +1,77 @@
 # Juicebox Address Registry
 
-Knowing who deployed a contract is the first step toward trusting it. This registry lets anyone prove a contract's deployer on-chain -- no access control and no admin keys.
+`@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.
 
-`JBAddressRegistry` maps contract addresses to their deployers using deterministic address computation. Provide the deployer address and deployment parameters, and the registry verifies the relationship and stores it permanently. Frontend clients can then look up any registered contract to see who deployed it, which is especially useful for vetting Juicebox pay and cash-out hooks before interacting with them.
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
 
-## Deployed Address
+## Overview
 
-`JBAddressRegistry` is deployed at the same address on all supported networks via deterministic `create2` deployment:
+The registry supports both `create` and `create2` style deployments:
 
-```
-0x2d9b78cb37ca724cfb9b32cd8e9a5dc1c88bc7bb
-```
-
-| Network | Chain ID |
-|---------|----------|
-| Ethereum | 1 |
-| Optimism | 10 |
-| Arbitrum | 42161 |
-| Base | 8453 |
-| Ethereum Sepolia | 11155111 |
-| Optimism Sepolia | 11155420 |
-| Arbitrum Sepolia | 421614 |
-| Base Sepolia | 84532 |
-
-## Architecture
+- 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
 
-| Contract | Description |
-|----------|-------------|
-| `JBAddressRegistry` | Standalone registry. Computes deployed addresses deterministically from deployer parameters and stores the deployer in `deployerOf`. No constructor arguments, no access control, no external dependencies. |
+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.
 
-### Interface
+Use this repo when deployer provenance matters. Do not confuse it with an allowlist, audit registry, or trust oracle.
 
-| Type | Description |
-|------|-------------|
-| `IJBAddressRegistry` | Interface exposing `deployerOf`, both `registerAddress` overloads, and the `AddressRegistered` event. |
+If the question is "is this hook safe?" this repo can only tell you who deployed it, not whether the code is good.
 
-### How It Works
+## Key Contract
 
-Anyone can register a contract by providing its deployer and deployment parameters:
+| Contract | Role |
+| --- | --- |
+| `JBAddressRegistry` | Standalone registry that stores `deployerOf[address]` and exposes overloaded `registerAddress` entrypoints. |
 
-- **`create` deployments**: Provide the deployer address and the nonce at the time of deployment. The registry reconstructs the address using RLP encoding (the same encoding the EVM uses internally to compute `create` addresses).
-- **`create2` deployments**: Provide the deployer address, the `create2` salt, and the full deployment bytecode (creation code + encoded constructor arguments). The registry computes `keccak256(0xff ++ deployer ++ salt ++ keccak256(bytecode))`.
+## Mental Model
 
-In both cases, the registry stores the mapping `deployerOf[computedAddress] = deployer` and emits an `AddressRegistered` event. Frontend clients can then look up any contract's deployer to verify trust.
+The registry is intentionally narrow:
 
-No access control is needed -- only the correct deployer + parameters can produce a given address, so registrations cannot be faked.
+1. reconstruct an address from deployment inputs
+2. bind that address to a deployer once
+3. expose the result for other systems and clients
 
-```solidity
-// Register a contract deployed via create.
-registry.registerAddress(deployer, nonce);
+Anything beyond that is out of scope by design.
 
-// Register a contract deployed via create2.
-registry.registerAddress(deployer, salt, bytecode);
+## Install
 
-// Look up who deployed a contract.
-address deployer = registry.deployerOf(contractAddress);
+```bash
+npm install @bananapus/address-registry-v6
 ```
 
-### Events
-
-| Event | Fields | Emitted When |
-|-------|--------|-------------|
-| `AddressRegistered` | `address indexed addr`, `address indexed deployer`, `address caller` | A contract address is registered via either `registerAddress` overload. `caller` is `msg.sender`, which may differ from the deployer. |
-
-### Risks
+## Development
 
-Hooks have token minting access, making malicious hooks dangerous. A registered deployer does not guarantee a hook is safe -- it only tells you who deployed it. Clients should warn project owners and users about any potential for unintended or adversarial behavior, especially for unknown hooks.
-
-Deployers can be exploited or act maliciously. Clients should still communicate risk to users even when the deployer is a known entity.
-
-### Limitations
+```bash
+npm install
+forge build
+forge test
+```
 
-- 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.
-- 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.
+Useful scripts:
 
-## Deployment
+- `npm run test:fork`
+- `npm run deploy:mainnets`
+- `npm run deploy:testnets`
 
-The deploy script uses [Sphinx](https://github.com/sphinx-labs/sphinx) for deterministic multi-chain deployment. The registry is deployed via `create2` with the salt `_JBAddressRegistryV6_`, ensuring the same address on every chain. The script skips deployment if the bytecode is already present at the computed address.
+## Deployment Notes
 
-A helper library `AddressRegistryDeploymentLib` is provided in `script/helpers/` to resolve deployed addresses from Sphinx deployment artifacts at runtime.
+The deploy script uses Sphinx for deterministic deployment. This package is intentionally small and independent because many other repos use it to record clone factories and helper deployments.
 
-## Install
+## Repository Layout
 
-```bash
-npm install
+```text
+src/
+  JBAddressRegistry.sol
+  interfaces/
+test/
+  unit, edge, fork, audit, and regression coverage
+script/
+  Deploy.s.sol
+  helpers/
 ```
 
-## Develop
+## Risks And Notes
 
-| Command | Description |
-|---------|-------------|
-| `forge build` | Compile contracts |
-| `forge test` | Run unit tests |
-| `FOUNDRY_PROFILE=CI forge test` | Run fork tests (requires `RPC_ETHEREUM_MAINNET` env var) |
-| `forge coverage --match-path "./src/*.sol" --report lcov --report summary` | Generate coverage report |
-| `npm run deploy:mainnets` | Propose mainnet deployment via Sphinx |
-| `npm run deploy:testnets` | Propose testnet deployment via Sphinx |
+- 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

package/RISKS.md

@@ -1,4 +1,21 @@
-# RISKS.md -- nana-address-registry-v6
+# Juicebox Address Registry Risk Register
+
+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.
+
+## How to use this file
+
+- Read `Priority risks` first; the biggest risks here are almost all interpretive, not balance-sheet failures.
+- Use the detailed sections to distinguish what the registry proves from what users may incorrectly infer from it.
+- Treat `Invariants to Verify` as the minimal safety envelope for deterministic registration.
+
+## Priority risks
+
+| Priority | Risk | Why it matters | Primary controls |
+|----------|------|----------------|------------------|
+| 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. |
+| 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. |
+| 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. |
+
 
 ## 1. Trust Assumptions