docs: cut the CREATE2, front-running and registry essays from the interface

[thedavidmeister]

Closes #125

ICloneableFactoryV4 was 240 lines, ~175 of them NatSpec prose, structured as a
document with markdown # headings inside comment blocks, attached to a
two-function interface. Three blocks argued rather than described:

• the "Neither dominates" trade-off framing plus a nine-line tutorial on why
  cross-chain CREATE2 identity needs matching factory AND implementation
  addresses — EVM mechanics, not a property of this interface;
• a five-line analogy to Zoltu deployment, a different deployment scheme, after
  the front-running bullets have already stated the property;
• a worked design discussion of rain.deploy's address registry, naming another
  repo's product and reasoning about its rebinding windows.

Cut. What survives is the normative content they buried: the exact salt
preimages, the MUST-NOT-mix-caller-derived-values rule, the atomic-initialize
chain, the tx.origin and gas obligations on implementations, the permitted
shape of resolving names from data, and the disjointness property. The four #
headings go with them; the paragraphs stand without.

The cross-network statement is kept as one line, because
predictDeterministicAddressOpenSalt points at it, and the "reproduce the exact
data bytes, ABI encoding and all" caveat is kept as the consumer-facing cost of
open-salt.

Branch shape

Branched off origin/main and merges 2026-09-21-issue-133-create-address-chain-claim
and 2026-09-21-issue-165-open-salt-must-not-property. This cut deletes the
sentence #133 rewrites and removes the heading immediately above the clause #165
rewrites, so it cannot land independently of either without conflicting. Their
diffs appear here unchanged.

Overlap with open PRs on this file

• docs: the open-salt address fixes the implementation's address, not its code #191 rewrites the sentence this cut leaves standing at the end of the
  front-running block. Only the Zoltu analogy ahead of it is deleted here, so
  docs: the open-salt address fixes the implementation's address, not its code #191's replacement survives the merge; resolve in its favour.
• docs: scope the open-salt safety property to the transaction, not the block #189 rewrites the chain-state bullet this cut trims. The lead sentence is left
  exactly as main has it so nothing here pre-empts docs: scope the open-salt safety property to the transaction, not the block #189's correction; resolve by
  taking docs: scope the open-salt safety property to the transaction, not the block #189's sentence and keeping the registry discussion deleted. docs: scope the open-salt safety property to the transaction, not the block #189 also
  adds a bullet after the one deleted here — keep it.
• docs: scope the open-salt domain tag's NatSpec to what the tags give #101 touches only the open-salt domain tag's @dev at the top of the file and
  does not overlap.

Comment-only. No source, ABI or bytecode change.

QA

• Discriminating tests: n/a — comment-only change; tests never assert NatSpec
  text.
• Mutations applied: n/a — no executable src line changes, so there is nothing
  to mutate.
• Oracle: src/lib/LibICloneableFactoryV4.sol — every surviving normative
  statement was checked against the implementation it constrains
  (effectiveSalt / effectiveOpenSalt, predictCloneAddress,
  cloneAndInitialize). The deleted blocks constrained nothing in this repo.
• Category check: the category is "NatSpec that argues instead of describing".
  Swept the whole file for the shape: no markdown headings remain in any comment
  block in src/interface/ICloneableFactoryV4.sol, and the surviving prose is
  statements about this interface's own functions. src/lib/LibICloneableFactoryV4.sol
  and the remaining src/interface/*.sol carry their own instances, filed
  separately ([F22] [LOW] Library header names only the predictions as reading address(this), but cloneAndInitialize reads it too #126, [F23] [LOW] DelegatedImplementation name and doc assert EIP-7702, but the condition is any 0xef-leading code #127, [F30] [LOW] Library header claims the derivation "cannot drift from the spec"; only the tag is shared, the preimage shape is duplicated #134, [F45] [INFO] LibICloneableFactoryV4's @notice narrates the repo split by issue number and claims test coverage #149, [F46] [INFO] ICloneableV2.initialize NatSpec is a rationale essay on ABI erasure and delegatecall patterns #150, [F51] [INFO] predictDeterministicAddressOpenSalt NatSpec calls the deployer/data swap "the entire difference" from predictDeterministicAddress, omitting the distinct domain tag #155). src/interface/deprecated/**
  is frozen.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 40 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 2ecb2a2b-18be-4108-93dc-8cd5cfa7edc6

📥 Commits

Reviewing files that changed from the base of the PR and between 710dff5 and b5e4d1d.

📒 Files selected for processing (1)

• src/interface/ICloneableFactoryV4.sol

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}