ERC-8349 Index-based multi-facet proxy
Draft · Other · created 2026-07-25
A standard for a modular proxy that bundles multiple implementation modules (facets) into a single address, where which facet executes is identified directly by a 1-byte routing index appended to the end of the calldata, instead of by the function selector.
Why it is needed
ERC-2535 (Diamond), a modular proxy standard that bundles multiple contracts (facets) into a single address, also uses the 4-byte function selector that identifies each function as the routing identifier. But the function selector was originally meant as an identifier for compatibility with external tools like wallets, block explorers, and SDKs, not as a value indicating which facet should execute. Bundling these two concerns together means that as a protocol grows, the routing metadata scales with the number of externally exposed functions rather than the number of facets, collisions where independently built facets happen to share the same function selector must constantly be guarded against, and replacing a single facet requires reworking every function selector it owns. This happens because two distinct concerns, routing (which module to execute) and compatibility (which standard interface was called), are mixed into a single selector.
What to implement
function getFacets() external view returns (address[] memory);: Returns the list of addresses of all currently installed facets.function getFacetEntries() external view returns (Facet[] memory);: Returns the full routing table pairing routing indices with facet addresses.function getFacetAt(uint8 index) external view returns (address);: Returns the facet address installed at a specific routing index (the zero address if the slot is empty).function getFacetCount() external view returns (uint16);: Returns the number of installed facets.function getFirstFreeSlot() external view returns (uint8);: Returns the lowest empty routing index (reverts if every slot is full).
In depth
Protocol routing: a 1-byte index appended to the end of calldata
Cento's Protocol Routing calls by appending a routing index (1 byte) to the end of the calldata. The preceding portion may be an ABI-encoded function call, raw bytes, or nothing at all. The router MUST (1) receive the indexed call, (2) extract the index from the last byte of the calldata, (3) verify that the index points to an active facet, (4) strip the routing byte from the calldata to be delegated, and (5) delegate execution to that facet via DELEGATECALL. The router must forward the remaining calldata as is, and the facet interprets it as standard ABI decoding, raw parsing, or, if the calldata is empty, as a call to its receive function. The router must also forward all available gas and return the return value (including reverts) directly to the caller.
Compatibility routing: standard selectors work as is
Standardized Ethereum interfaces such as ERC-165 (interface detection) and ERC-173 (ownership) are still called with their existing 4-byte function selectors. The router MUST detect standard interface selectors and dispatch them through the Interface Compatibility adapter to the corresponding Compatibility Function, without appending a routing index. This path coexists with Protocol Routing without interference. Any standard interface that uses selectors SHOULD also be supported through compatibility routing.
Exactly one routing index per facet, 8-bit width
Each installed facet SHALL be associated with exactly one routing index in the routing table. The Facet struct consists of a uint8 index field and an address facet field. The routing index is standardized at 8 bits (0 to 255), supporting up to 256 facets while adding only 1 byte of calldata overhead. Even if the same facet implements multiple protocol functions, no additional routing metadata is needed, and protocol function selectors do not need to be globally unique across other facets. Extending the index width to support more facets is out of scope for this standard.
Facet management handled through atomicUpdate
Implementations MUST perform upgrades at the facet level rather than the function level, and MUST support facet installation, replacement, and removal. IFacetManager.atomicUpdate(setF, addI, remI, migrator, _calldata) atomically handles installation, replacement, and removal of multiple facets, registration and deregistration of supported interface identifiers (bytes4), and execution of storage migration within a single transaction. If a migration contract is provided, it MUST be executed via DELEGATECALL immediately after the routing metadata is updated, and the entire update MUST revert if the migration fails. All facet changes after initialization MUST go through this interface, and implementations MUST emit an AtomicUpdate event on every atomic update.
Querying the routing table via IObservability
getFacets() returns the list of installed facet addresses, getFacetEntries() returns the full mapping of (index, address) pairs, getFacetAt(index) returns the facet address at a specific slot, getFacetCount() returns the number of installed facets, and getFirstFreeSlot() returns the first empty routing slot (reverting if all slots are full). All of these functions are view functions that do not change state, making them safe for repeated calls by wallets, explorers, SDKs, governance, and audit tools.
Initial state and ERC-165 reporting obligations
At deployment, the router MUST be initialized with three core facets installed at standard indices: IFacetManager at index 0, the Ownership mechanism at index 1, and IERC165 and IObservability at index 2. The router MUST accurately report the interface identifiers it supports, including 0x01ffc9a7 (IERC165), 0x5378f98e (IFacetManager), and 0x1c60a259 (IObservability), and MUST also report the interface identifiers exposed by installed facets through ERC-165. Emitting an AtomicUpdate event on initial deployment is optional.
Storage layout is not prescribed
This standard defines routing semantics independently of storage layout and neither requires nor prohibits any particular storage layout model. The reference implementation manages shared protocol state using ERC-7201 storage namespaces and tracks routing index occupancy with a bitmap-based data structure (LibBitmap). The reference implementation consists of CentoRouter.sol, the FacetManager, Observability, and Ownership facets, the IFacetManager/IObservability/IERC173 interfaces, and the LibCento library, and does not include deployment scripts or tests.
This is not yet a finalized proposal
This standard is currently in Draft status, proposed as an alternative design coexisting with ERC-2535 (Diamond). It is still under discussion, so details may change or stall.
Things to watch out for
- Access control: atomicUpdate() must be restricted so that only authorized parties can call it. Sensitive upgrades should consider governance mechanisms such as timelocks or multisig, and all routing metadata changes should be logged.
- DELEGATECALL risk: Delegated code executes in the router's storage space, so conflicting storage layouts between facets can corrupt state, and a malicious facet could drain funds or damage state. Conflicts should be prevented with namespaces such as ERC-7201, all facets should be audited before installation, and atomic updates should be protected with appropriate authorization and governance.
- Facet validity checks: The router must refuse to install the following as facets: externally owned accounts (EOAs, which would silently succeed with no code when delegated to), empty contracts with no code, and EOAs delegated via EIP-7702 (which create a secondary authorization path outside the router's control).
- Routing input validation: The router must validate and revert, before execution, on empty calldata, indices that do not point to a registered facet, delegation to the zero address, and delegation to itself. Skipping this validation can cause gas exhaustion from a CALLDATACOPY underflow, silent failure from delegation to the zero address, or the unexpected situation of the router delegating to itself.
- Handling empty calldata: Removing the routing index from empty calldata can cause the computed length to underflow, making CALLDATACOPY attempt to copy a massive region of memory and exhaust gas. The receive() function should consume empty calldata first, or fallback() should include an explicit length check.