## eip: TBD
title: Onchain Representation for Audits
description: Proposal to define a contract parseable representation of Audit reports.
author: Richard Meissner (@rimeissner), ...
discussions-to: TBD
status: Draft
type: Standards Track
category: ERC
created: 2023-06-22

## Abstract

The proposal aims to create a standard for an onchain representation of audit reports that can be parsed by contracts to extract relevant information about the audits, such as who performed the audits and what standards have been verified.

## Motivation

Audits are an integral part of the smart contract security framework. They are commonly used to ensure that smart contracts don't have bugs, follow best practises and correctly implement standards such ERC-20 or ERC-721. Many essential parts of the Blockchain ecosystem are secured by smart contract by now. Some examples for this are:

- Bridges - Most bridge consist out of bridgehead or a lockbox that secures the tokens that should be bridged. If any of these contracts are faulty it might be possible to bring the operation of the bridge to an halt or take full control.
- Token contracts - Every token in the Ethereum ecosystem is a smart contract. Apps that interact with these tokens rely that they follow the known token standards. Tokens that behave differently can cause unexpected behaviour and might cause a loss of funds.
- Smart contract accounts - With ERC-4337 more visibility has been created for smart contract based account. They provide extreme flexibility and can cater to many different use cases. A concept that has been used are modules, which allow to extend the functionality of a smart contract accounts. ERC-6900 is a recent standard that defines how to register and design plugins that can be registered on an account.
- ….

The usage and impact smart contracts will have on the day to day operations of decentralized applications will steadily increase. To provide strong guarantees about security and allow better composability it is important that it is possible to verify onchain that a contract has been audited.

While this information alone is no guarantee that there are no bug are flaws in a contract, it can provide an important building block to create security systems for smart contracts, which are necessary for maximum of flexibility while maintaining security.

- TODO: Outline generation and potential (on-chain) usage

## Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

### Open Questions/ Notes

- How to handle upgradable contracts and proxies?
- It is important to keep the overhead for auditors as low as possible!
- ...

### Audit Properties

- ~~Findings~~ (see Rationale)
- Considerations
- Link to [EthTrust](https://entethalliance.github.io/eta-registry/security-levels-spec.html#req-R-follow-erc-standards)
- Based on https://github.com/safe-global/safe-contracts/blob/main/docs/Safe_Audit_Report_1_4_0.pdf
- TODO: Create matrix for defining severity based on impact and likelihood
- `severity`
- `critical`
- `high`
- `medium`
- `low`
- `warning`
- `informational`
- `status`
- `open`
- `acknowledged`
- `won't fix`
- `fixed`
- VM type
- `EVM`
- `zkSync`
- Auditor
- `name` - Name of the auditor (i.e. for displaying to the user)
- `uri` - Uri to retrieve more information about the auditor
- Audit
- `auditor` - Information on the auditor
- `ercs` - Make it easy to validate which standard are supported and that they are correctly/ completely implemented.
- ~~`findings` - List of the severity and status of findings~~
- `vmType` - Indicate for which type of VM the deployment and runtime code was generated
- `deploymentCodeHash` - Hash of the deployment code of the audited contract
- `runtimeCodeHash` - Hash of the runtime code of the audited contract
- `auditHash` - Allows to verify that the full audit report belongs to this representation
- `auditUri` - Uri to retrieve the full audit

### Auditor Verification

- Signature
- Type
- `SECP256K1`
- Data is the encoded representation of `r`, `s` and `v`
- `BLS`
- TBD
- `ERC1271`
- Data is the abi encode representation of `chainid`, `address` and the `signature bytes`
- `SECP256R1`
- Data is the encoded representation of `r`, `s` and `v`
- Data
- TODO: How to assign a specific Signing key to an auditors
- Auditors should publicly share the public part of the signature. This could for example be done on their website.
- As an extension to this ERC it would be possible to build a public repository, but this is out of scope for this proposal.

### Data types

struct Auditor {
    string name;
    string uri;
}

enum VMType {
    EVM;
    zkSync;
}

struct AuditSummary {
    Auditor auditor;
    uint256[] ercs;
    VMType vmType;
    bytes32 deploymentCodeHash;
    bytes32 runtimeCodeHash;
    bytes32 auditHash;
    string auditUri;
}

### Signing

For signing [EIP-712](https://eips.ethereum.org/EIPS/eip-712) will be used. For this the main type is the `AuditSummary` and as the `EIP712Domain` the following definition applies:

struct EIP712Domain {
    string name;
    string version;
}

EIP712Domain auditDomain = EIP712Domain("ERC-XXXX: On-Chain Audit Representation", "1.0");

The generated signature can then be attached to the `AuditSummary` to generate a new `SignedAuditSummary` object:

enum SignatureType {
    ECDSA,
    BLS,
    ERC1271
}

struct Signature {
    SignatureType type;
    bytes data;
}

struct SignedAuditSummary extends AuditSummary {
    Signature auditorSignature;
}

- TODO signature format
- How to support contract signatures

## Rationale

- `vmType`
- As contracts are very dependent on the environment that they are executed/run in, it is also very important to know for an audit what the target environment is.
- For the correct interpretation of `deploymentCodeHash` and `runtimeCodeHash` this information is also required.
- `standards` vs `ercs`
- Limiting the scope to audits related to EVM based smart contract accounts, allows a better definition of parameters.
- `findings`
~~- As descriptions are very extensive and hard to handle on-chain only the most critical information has to be chosen. For this the severity and the status had the highest priority, because solely based on this information it is already possible to make some deduction on the state of the contract~~.
- Different audit teams use different representations and it will be very hard to align on a common one (at least it is out of scope for this ERC). The most important information is that there is no critical vulnerability. **This fact should be the condition for the auditor to sign the audit representation in the first place.**
- `deploymentCodeHash` and `runtimeCodeHash` vs `network` and `address`
- Definition
- `network` - Specifies on which network the address verified or uint256(0) if not applicable
- `address` - Address of the deployed instance on a specific network of the contract or address(0) if not used
- `network` and `address` are quite limiting and don't have a verifiable connection without the code hashes. On the other hand `deploymentCodeHash` and `runtimeCodeHash` can link an address to a contract very specifically (on any network). This even allows to connect the same audit summary to multiple deployed instances of a contract.
- Why ERC-712?
- ERC-712 as a base for tooling compatibility (i.e. for signing)
- Extensions
- Add support for more standards and networks

## Backwards Compatibility

No backward compatibility issues found.

## Reference Implementation

- TODO: Simple script generate struct and sign the data

TBD.

## Security Considerations

Needs discussion.

## Copyright

Copyright and related rights waived via [CC0](https://www.notion.so/LICENSE.md).