---
eip: <to be assigned>
title: Indexing Internal Deployments
description: Registration and indexing of deployments made from factory-style contracts
author: Ser Doggo (@fubuloubu)
discussions-to: <URL>
status: Draft
type: Standards
category: ERC
created: 2022-06-20
---

## Abstract
<!--Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does.-->

Create standard behavior around handling deployments from "Factory contracts" (contracts that deploy other contracts internally), so that all Deployments from a factory can be efficiently indexed by external tooling.

## Motivation
<!--The motivation section should describe the "why" of this EIP. What problem does it solve? Why should someone want to implement this standard? What benefit does it provide to the Ethereum ecosystem? What use cases does this EIP address?-->

It is a fairly typical pattern in Ethereum programming to do "Factory Deployments", which is a single contract that deploys multiple contracts of another type.
Great examples of this paradigm are the Uniswap Router and Pool contracts ([v1](https://github.com/Uniswap/v1-contracts/blob/master/contracts/uniswap_factory.vy#L4) [v2](https://github.com/Uniswap/v2-core/blob/master/contracts/interfaces/IUniswapV2Factory.sol#L4) [v3](https://github.com/Uniswap/v3-core/blob/main/contracts/interfaces/IUniswapV3Factory.sol#L23)), Yearn Registry and Vault contracts ([link](https://github.com/yearn/yearn-vaults/blob/main/contracts/Registry.vy#L48)), and many other protocols like them.

However, there are some problems with these approaches. For external tooling, it is often very difficult to detect if a contract deployment was made internally, because it does not show up in the Receipt structure of a transaction, and one has to dive deeply into the trace to detect these issues. A common pattern around this is to create an event representing that deployment, so it can efficiently be detected by event queries.

These event definitions have never been standardized, and there are significant variations in how these events are defined. There may also be additional event arguments useful for filtering purposes, such as which tokens are used for deposits, or what version was being used, etc. A good solution for this use case should take this into account.

## Specification
<!--The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->

This ERC defines a single function that MUST be implemented by the Factory contract, `deploymentEventId`, and requires an event definition of a specific structure.
The event ID of that event definition MUST be the same as the value emitted by `deploymentEventId`.
Additionally, there SHOULD only be a single contract type (we are calling `Deployment` for the purposes of this ERC) deployed using this ERC.

### `deploymentEventId`

This method is a pure method that returns the event ID value that an external indexer will use to find the right events necessary to extract Deployments made from this factory.
`eventId` MUST correspond to the event ID of an event definition emitted whenever a contract is deployed.
This value SHOULD NOT change over time, or it may affect how external indexers might index these deployments.

- name: deploymentEventId
  type: function
  stateMutability: view
  outputs:
  - name: eventId
    type: bytes32

### Deployment Event Definition

The "Deployment Event" is any event definition that corresponds with the deployment of a new contract by the Factory.
The event definition MUST correspond with the event ID returned by `deploymentEventId`.
The event definition MUST contain at least 1 unindexed argument.
The event definition MUST have its first _unindexed_ argument be the address of the deployed contract, emitted at the time of deployment.
There SHOULD NOT be another event definition fulfilling the same use case of tracking deployments.
The event definition MAY have other indexed or unindexed arguments per application requirements.

### Example

An example of how this might be implemented in practice (written in Vyper):

event Deployment:
    factory: indexed(address)  # Can define indexed args
    deployment: address  # NOTE: Must be 1st unindexed arg
    ...  # Can have other args too


deployment: address = create_from_factory(self.factory, ...)
log Deployment(self.factory, deployment, ...)  # Hook event

A indexer might look something like this (psuedo-code written in Python):

def find_deployments(factory, **filter_args) -> Iterator[Address]:
    try:
        event_id = factory.deploymentEventId()
    except Exception:
        return  # If this fails, does not implement this ERC
    
    for event in web3_provider.eth_filter(topic0=event_id, **filter_args):
        # If this fails, event is not correctly formed per ERC
        yield to_checksum_address(event.data[:32])

## Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages.-->

Requiring a _specific_ event definition may prevent certain use cases from being covered, as additional data might be helpful to track, especially with indexed args which can be used to filter event stream.

The deployment contract's address is an _unindexed_ argument due to the fact that it should be a unique occurance, and does not make sense to track separately as it should only appear once with that unique value. It may be helpful for search purposes, but this usecase can be fulfilled by other ways of obtaining the transaction ID of the deployment, such as linking from the Deployment event used to spawn that contract.

The function `deploymentEventId` is helpful for external indexers to detect support for this ERC. Other methods of detecting support could be helpful, but since this call is intended to be made externally, it didn't seem particularly helpful to require more complex ways of signaling support.

## Backwards Compatibility
<!--All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->

No backwards compatibility issues.

## Test Cases
<!--Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/eip-####/`.-->

TODO

## Reference Implementation
<!--An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. If the implementation is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/eip-####/`.-->

TODO

## Security Considerations
<!--All EIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. EIP submissions missing the "Security Considerations" section will be rejected. An EIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.-->

TODO

## Copyright
Copyright and related rights waived via [CC0](../LICENSE.md).