ILatticeRegistry

Git Source

Title: ILatticeRegistry

Author: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80)

Read / admin surface of the LatticeRegistry singleton — the two-tier, immutable, deploy-once address book that lets every Lattice diamond reuse canonical facet bytecode instead of re-CREATEing byte-identical facets on every deployment.

• Tier A (permissionless, trustless): attest / resolve. A content-addressed index from a runtime codehash to the FIRST address attested with it. attest is self-verifying (it reads deployed.codehash on-chain — impossible to spoof) and first-write-wins. No curation, no admin. resolve answers ONE question: "where is a contract with exactly this code?". It is a code-identity lookup, NOT a selector source and not a statement about behaviour. Two addresses with one codehash behave the same only when the diamond delegatecalls them AND the facet meets every assumption below; Lattice facets do, arbitrary contracts need not:

1. no reads of the facet's OWN storage on any path (a direct call or staticcall reads the facet's storage, which can differ between two instances of the same code);
2. a pure ERC-8153 exportSelectors() (a view exporter can answer differently per instance, and a staticcall cannot enforce pure);
3. no proxy used as a facet (a proxy's codehash says nothing about the code it forwards to);
4. selectors come from Tier B (getSelectors / getCut), never from resolve. register mirrors a curated facet into Tier A only when its codehash is unmapped, so a curated record can name a different address than resolve returns for the same codehash.

• Tier B (curated, append-only): register / setLatest + views. Ownable2Step (→ multisig) governs ONLY this namespace. A (nameHash, version) record is IMMUTABLE once written (invariant I1) — never repointed; latest(nameHash) is a curator-movable convenience pointer that security-critical consumers ignore in favour of pinning an exact version (invariant I3). Curated facets MUST implement ERC-8153 exportSelectors(); register pulls and validates the selectors and pins keccak256(blob), and the live-read views re-verify against that pin so an impure or lying exportSelectors() can never drift the cut a consumer receives (invariant I2 for selectors).

EXPORTER CALLS ARE BOUNDED. Every exportSelectors() read (at register and on each live read) forwards at most 100,000 gas and accepts at most 8,192 bytes of return data; a call that runs out of gas, reverts, or returns more is treated as a non-conformant export. Return data is decoded by hand with exactly the acceptance rule of abi.decode(ret, (bytes)) (any in-bounds offset, trailing bytes ignored), so a malformed encoding is reported as LatticeRegistry__NotERC8153 at registration and as LatticeRegistry__SelectorDrift on a live read, never as an empty revert or a Panic.

version is a semver value packed into a uint64 as major (16 bits) | minor (24) | patch (24) ((major << 48) | (minor << 24) | patch), so lexicographic uint64 ordering equals semver ordering. The registry treats it as an OPAQUE, ordered key; it never decodes the fields. Packed version 0 (i.e. 0.0.0) is RESERVED as the "latest unset" sentinel and is not registrable.

Functions

attest

Permissionlessly record that deployed carries a given runtime codehash (first-write-wins).

function attest(address deployed) external;

Parameters

resolve

Resolve a runtime codehash to the first address attested with it (0 if none).

function resolve(bytes32 codehash) external view returns (address deployed);

Parameters

Returns

register

Register a new curated facet under (nameHash, version) (owner-only, append-only).

function register(bytes32 nameHash, uint64 version, address facet) external;

Parameters

setLatest

Point latest(nameHash) at an already-registered version (owner-only).

function setLatest(bytes32 nameHash, uint64 version) external;

Parameters

get

Read the exact record for (nameHash, version).

function get(bytes32 nameHash, uint64 version) external view returns (Record memory record);

Parameters

Returns

latest

Read the record currently flagged as latest for a name.

function latest(bytes32 nameHash) external view returns (Record memory record);

Parameters

Returns

getMany

Batch get: one record per key, in order. A key with version == 0 reads the record latest(nameHash) points at, the way a factory recipe entry with version 0 resolves.

function getMany(RecordKey[] calldata keys) external view returns (Record[] memory records);

Parameters

Returns

latestMany

Batch latest: the record each name's latest pointer flags, in order.

function latestMany(bytes32[] calldata nameHashes) external view returns (Record[] memory records);

Parameters

Returns

getSelectors

Live-read and drift-verify the facet's selectors for (nameHash, version).

function getSelectors(bytes32 nameHash, uint64 version) external view returns (bytes4[] memory selectors);

Parameters

Returns

getCut

Live-read, drift-verify, and assemble a ready-to-apply Add FacetCut for (nameHash, version).

function getCut(bytes32 nameHash, uint64 version) external view returns (FacetCut memory cut);

Parameters

Returns

nameHash

Compute the registry key for a canonical facet name: keccak256(bytes(name)).

function nameHash(string calldata name) external pure returns (bytes32);

Parameters

Returns

register

register by canonical name string instead of its precomputed hash (owner-only).

function register(string calldata name, uint64 version, address facet) external;

Parameters

setLatest

setLatest by canonical name string (owner-only).

function setLatest(string calldata name, uint64 version) external;

Parameters

get

get the exact record for a canonical name string.

function get(string calldata name, uint64 version) external view returns (Record memory record);

Parameters

Returns

latest

latest record for a canonical name string.

function latest(string calldata name) external view returns (Record memory record);

Parameters

Returns

getSelectors

getSelectors for a canonical name string.

function getSelectors(string calldata name, uint64 version) external view returns (bytes4[] memory selectors);

Parameters

Returns

getCut

getCut for a canonical name string.

function getCut(string calldata name, uint64 version) external view returns (FacetCut memory cut);

Parameters

Returns

owner

The current owner of the curated Tier-B namespace.

function owner() external view returns (address);

Returns

pendingOwner

The address that may call acceptOwnership to complete a pending handover (0 if none).

function pendingOwner() external view returns (address);

Returns

transferOwnership

Begin a two-step ownership handover to newOwner (owner-only; pass address(0) to cancel).

function transferOwnership(address newOwner) external;

Parameters

acceptOwnership

Complete a pending ownership handover (pending-owner-only).

function acceptOwnership() external;

Events

Attested

Emitted the first time a runtime codehash is attested into the Tier-A resolver.

event Attested(bytes32 indexed codehash, address indexed deployed);

Parameters

Registered

Emitted when a new curated (nameHash, version) record is written.

event Registered(
        bytes32 indexed nameHash, uint64 indexed version, address indexed facet, bytes32 codehash, bytes32 selectorsHash
    );

Parameters

LatestSet

Emitted when the latest convenience pointer for a name is set or moved (rollbacks allowed).

event LatestSet(bytes32 indexed nameHash, uint64 indexed version);

Parameters

OwnershipTransferStarted

Emitted when a two-step ownership handover is initiated by the current owner.

event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner);

Parameters

OwnershipTransferred

Emitted when ownership is transferred (construction, and on acceptOwnership).

event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);

Parameters

Errors

LatticeRegistry__ZeroAddress

Thrown when a constructor / handover would set a zero owner.

error LatticeRegistry__ZeroAddress();

LatticeRegistry__Unauthorized

Thrown when a non-owner calls an onlyOwner function.

error LatticeRegistry__Unauthorized(address caller);

Parameters

LatticeRegistry__NotPendingOwner

Thrown when an account other than the pending owner calls acceptOwnership.

error LatticeRegistry__NotPendingOwner(address caller);

Parameters

LatticeRegistry__EmptyCode

Thrown when attest / register targets an address with no runtime code (EOA / empty — I4).

error LatticeRegistry__EmptyCode(address target);

Parameters

LatticeRegistry__InvalidVersion

Thrown when register uses the reserved sentinel version 0 (0.0.0).

error LatticeRegistry__InvalidVersion();

LatticeRegistry__RecordExists

Thrown when register would overwrite an existing (nameHash, version) record (I1).

error LatticeRegistry__RecordExists(bytes32 nameHash, uint64 version);

Parameters

LatticeRegistry__RecordNotFound

Thrown when a view / setLatest references a (nameHash, version) that was never registered.

error LatticeRegistry__RecordNotFound(bytes32 nameHash, uint64 version);

Parameters

LatticeRegistry__LatestUnset

Thrown when latest is read for a name whose pointer was never set.

error LatticeRegistry__LatestUnset(bytes32 nameHash);

Parameters

LatticeRegistry__NotERC8153

Thrown when a curated facet does not satisfy the ERC-8153 selector contract at register (call reverts or runs out of its 100,000-gas budget / returns fewer than 64 or more than 8,192 bytes / an encoding abi.decode(ret, (bytes)) would reject / empty selectors / length not a multiple of 4 / duplicates / a blob that self-includes exportSelectors() (0x0ef22643), which must never be cut).

error LatticeRegistry__NotERC8153(address facet);

Parameters

LatticeRegistry__SelectorDrift

Thrown by the live-read views when keccak256(exportSelectors()) no longer equals the pinned selectorsHash — an impure or mutated facet (invariant I2 for selectors). A live read that fails the bounds LatticeRegistry__NotERC8153 lists (revert, gas, size, malformed encoding) is also reported as drift.

error LatticeRegistry__SelectorDrift(address facet);

Parameters

LatticeRegistry__CodeDrift

Thrown by the live-read views when the facet's current codehash no longer equals the codehash pinned at registration — defends against a metamorphic (CREATE2 + selfdestruct + redeploy) address swap that keeps exportSelectors() byte-identical (invariant I2 for code).

error LatticeRegistry__CodeDrift(address facet);

Parameters

Structs

Record

A curated Tier-B facet record, immutable once written (invariant I1).

struct Record {
        address facet;
        uint64 version;
        uint48 registeredAt;
        bytes32 codehash;
        bytes32 selectorsHash;
    }

Properties

RecordKey

One lookup for getMany: a curated name and the version to read.

struct RecordKey {
        bytes32 nameHash;
        uint64 version;
    }

Properties