Skip to content

Commit a81438b

Browse files
rmeissnerrmeissner
authored
Add EIP: Onchain Representation for Audits
Merged by EIP-Bot.
1 parent a6876a7 commit a81438b

2 files changed

Lines changed: 192 additions & 0 deletions

File tree

‎EIPS/eip-7512.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
eip: 7512
3+
title: Onchain Representation for Audits
4+
description: Proposal to define a contract parseable representation of Audit reports.
5+
author: Richard Meissner - Safe (@rmeissner), Robert Chen - OtterSec (@chen-robert), Matthias Egli - ChainSecurity (@MatthiasEgli), Jan Kalivoda - Ackee (@jaczkal), Michael Lewellen - OpenZeppelin (@cylon56), Shay Zluf - Hats Finance (@shayzluf)
6+
discussions-to: https://ethereum-magicians.org/t/erc-7512-onchain-audit-representation/15683
7+
status: Draft
8+
type: Standards Track
9+
category: ERC
10+
created: 2023-09-05
11+
requires: 712
12+
---
13+
14+
15+
## Abstract
16+
17+
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.
18+
19+
## Motivation
20+
21+
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 practices and correctly implement standards such [ERC-20](./eip-20.md) or [ERC-721](./eip-721.md)). Many essential parts of the Blockchain ecosystem are secured by smart contract by now. Some examples for this are:
22+
23+
- 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.
24+
- 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.
25+
- Smart contract accounts - With [ERC-4337](./eip-4337.md) 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](./eip-6900.md)) is a recent standard that defines how to register and design plugins that can be registered on an account.
26+
- Hooks and Callbacks - With more protocol allowing hooks to interact with their protocol and different token standard which trigger callbacks on a transfer (i.e. [ERC-1155](./eip-1155.md)) it is important to make sure that these interactions are well curated to minimize the security risks as much as possible.
27+
28+
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. Creating a system that can verify that an audit has been made for a specific address will strengthen the security guarantees of the whole smart contract ecosystem.
29+
30+
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.
31+
32+
### Example
33+
34+
Imagine a hypothetical [ERC-1155](./eip-1155.md) token bridge. The goal is to create a scalable system where it is possible to easily register new tokens that can be bridged. To minimize the risk of malicious or faulty tokens being registered, audits will be used and verified onchain.
35+
36+
37+
![Onchain Audit Example Use Case](../assets/eip-7512/example_use_case.png)
38+
39+
For showing the details of the flow more clearly, the diagram separates the Bridge and the Verifier. Theoretically both can live in the same contract.
40+
41+
There are four parties:
42+
43+
- User: The end user that wants to bridge their token
44+
- Bridge Operator: The operator is maintaining the bridge
45+
- Bridge: The contract the user will interact with to trigger the bridging
46+
- Validator: The contract that validates that a token can be bridged
47+
48+
As a first (1) step the bridge operator should define the keys/accounts for the auditors from which audits are accepted for the token registration process.
49+
50+
With this the user (or token owner) can trigger the registration flow (2). There are two steps (3 and 6) that will be performed: verify that the provided audit is valid and has been signed by a trusted auditor (4) and check that the token contract implements [ERC-1155](./eip-1155.md) (7).
51+
52+
With the checks being done it is still recommended to have some manual check in place by the operator to activate a token for bridging (10). This step could be omitted if there is a strong trust in the auditor or if an ERC provides strong compatibility guarantees.
53+
54+
Once the token is available on the bridge the users can start using it (11).
55+
56+
## Specification
57+
58+
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.
59+
60+
### Audit Properties
61+
62+
- Auditor
63+
- `name` - Name of the auditor (i.e. for displaying to the user)
64+
- `uri` - Uri to retrieve more information about the auditor
65+
- `authors` - A list of authors that contributed to this audit. This SHOULD be the persons that audited the contracts and created the audit.
66+
- Audit
67+
- `auditor` - Information on the auditor
68+
- `contract` - MUST be the `chainId` and `address` of the deployed contract the audit is related to.
69+
- `issuedAt` - MUST contain the information when the original audit (identified by the `auditHash`) was issued
70+
- `ercs` - A list of ERCs that are implemented by the target contract. The ERCs listed MUST be fully implemented. This list MAY be empty.
71+
- `auditHash` - MUST be the hash of the original audit. This allows to verify that this onchain information belongs to a specific audit.
72+
- `auditUri` - SHOULD point to a source where the audit can be retrieved
73+
74+
### Auditor Verification
75+
76+
- Signature
77+
- Type
78+
- `SECP256K1`
79+
- Data is the encoded representation of `r`, `s` and `v`
80+
- `BLS`
81+
- TBD
82+
- `ERC1271`
83+
- Data is the abi encode representation of `chainId`, `address`, `blocknumber` and the `signature bytes`
84+
- `SECP256R1`
85+
- Data is the encoded representation of `r`, `s` and `v`
86+
- Data
87+
88+
### Data types
89+
90+
```solidity
91+
struct Auditor {
92+
string name;
93+
string uri;
94+
string[] authors;
95+
}
96+
97+
struct Contract {
98+
bytes32 chaidId;
99+
address address;
100+
}
101+
102+
struct AuditSummary {
103+
Auditor auditor;
104+
uint256 issuedAt;
105+
uint256[] ercs;
106+
Contract contract;
107+
bytes32 auditHash;
108+
string auditUri;
109+
}
110+
```
111+
112+
### Signing
113+
114+
For signing [EIP-712](./eip-712.md) will be used. For this the main type is the `AuditSummary` and as the `EIP712Domain` the following definition applies:
115+
116+
```solidity
117+
struct EIP712Domain {
118+
string name;
119+
string version;
120+
}
121+
122+
EIP712Domain auditDomain = EIP712Domain("ERC-7652: Onchain Audit Representation", "1.0");
123+
```
124+
125+
The generated signature can then be attached to the `AuditSummary` to generate a new `SignedAuditSummary` object:
126+
127+
```solidity
128+
enum SignatureType {
129+
SECP256K1,
130+
BLS,
131+
ERC1271,
132+
SECP256R1
133+
}
134+
135+
struct Signature {
136+
SignatureType type;
137+
bytes data;
138+
}
139+
140+
struct SignedAuditSummary extends AuditSummary {
141+
uint256 signedAt;
142+
Signature auditorSignature;
143+
}
144+
```
145+
146+
## Rationale
147+
148+
The current ERC does not have any mentions of the `findings` of an audits. This was done as it would first be necessary to align on the definition of severities. This is a very challenging tasks, which is out of scope of this ERC. Therefore it is important to note that this ERC proposes that a signed audit summary indicates that a specific contract instance (specified by `chainId` and `address`) has no ciritical bugs and is "safe to use". Furthermore it indicates that this contract instance correctly implements the listed ERCs. This normally corresponds to the final audit revision for a contract which is then connected to the deployment.
149+
150+
### Further Considerations
151+
152+
- `standards` vs `ercs`
153+
- Limiting the scope to audits related to EVM based smart contract accounts, allows a better definition of parameters.
154+
- `chainId` and `address`
155+
- Behaviour of a contract depends on state. State is depending on instance (i.e. deployment setup and constructor args). Therefore just relying on the code hashes is not secure enough.
156+
- `contract` vs `contracts`
157+
- Many audits are related to multiple contracts that make up a protocol. Still for an initial version it was chosen to only reference one contract per audit summary. If muliple contracts have been audited the same summary can be used with different contract instances. This way it is also clear which contract the provided information (i.e. `ercs`) reference. The only downside is that this requires multiple signing passes by the auditors.
158+
- Why [EIP-712](./eip-712.md)?
159+
- [EIP-712](./eip-712.md) as a base for tooling compatibility (i.e. for signing)
160+
- How to assign a specific Signing key to an auditors
161+
- Auditors should publicly share the public part of the signature. This could for example be done on their website.
162+
- As an extension to this ERC it would be possible to build a public repository, but this is out of scope for this proposal.
163+
- Polymorphic contracts and Proxies
164+
- This ERC quite explicitly does **not** mention polymorphic contracts and proxies. These are important to be considered, but this is currently left to the auditors and the code that makes use of this ERC.
165+
166+
### Future Extensions
167+
168+
- Add support for more standards and networks
169+
- Better support for polymorphic contracts and audits
170+
- Management of signing keys for auditors
171+
- Definition of findings of an audit
172+
173+
## Backwards Compatibility
174+
175+
No backward compatibility issues found.
176+
177+
## Reference Implementation
178+
179+
TBD.
180+
181+
The following features will be implemented in a reference implementation:
182+
183+
- Script to trigger signing based on a json representing the audit summary
184+
- Contract to verify signed audit summary
185+
186+
## Security Considerations
187+
188+
Needs discussion.
189+
190+
## Copyright
191+
192+
Copyright and related rights waived via [CC0](../LICENSE.md).

‎assets/eip-7512/example_use_case.png‎

79.8 KB
Loading

0 commit comments

Comments
 (0)