forked from DecentralizedClimateFoundation/DCIPs
93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
---
|
|
eip: 6372
|
|
title: Contract clock
|
|
description: An interface for exposing a contract's clock value and details
|
|
author: Hadrien Croubois (@Amxx), Francisco Giordano (@frangio)
|
|
discussions-to: https://ethereum-magicians.org/t/eip-6372-contract-clock/12689
|
|
status: Review
|
|
type: Standards Track
|
|
category: ERC
|
|
created: 2023-01-25
|
|
---
|
|
|
|
## Abstract
|
|
|
|
Many contracts rely on some clock for enforcing delays and storing historical data. While some contracts rely on block numbers, others use timestamps. There is currently no easy way to discover which time-tracking function a contract internally uses. This EIP proposes to standardize an interface for contracts to expose their internal clock and thus improve composability and interoperability.
|
|
|
|
## Motivation
|
|
|
|
Many contracts check or store time-related information. For example, timelock contracts enforce a delay before an operation can be executed. Similarly, DAOs enforce a voting period during which stakeholders can approve or reject a proposal. Last but not least, voting tokens often store the history of voting power using timed snapshots.
|
|
|
|
Some contracts do time tracking using timestamps while others use block numbers. In some cases, more exotic functions might be used to track time.
|
|
|
|
There is currently no interface for an external observer to detect which clock a contract uses. This seriously limits interoperability and forces devs to make risky assumptions.
|
|
|
|
## 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.
|
|
|
|
Compliant contracts MUST implement the `clock` and `CLOCK_MODE` functions as specified below.
|
|
|
|
```solidity
|
|
interface IERC6372 {
|
|
function clock() external view returns (uint48);
|
|
function CLOCK_MODE() external view returns (string);
|
|
}
|
|
```
|
|
|
|
### Methods
|
|
|
|
#### clock
|
|
|
|
This function returns the current timepoint according to the mode the contract is operating on. It MUST be a **non-decreasing** function of the chain, such as `block.timestamp` or `block.number`.
|
|
|
|
```yaml
|
|
- name: clock
|
|
type: function
|
|
stateMutability: view
|
|
inputs: []
|
|
outputs:
|
|
- name: timepoint
|
|
type: uint48
|
|
```
|
|
|
|
#### CLOCK_MODE
|
|
|
|
This function returns a machine-readable string description of the clock the contract is operating on.
|
|
|
|
This string MUST be formatted like a URL query string (a.k.a. `application/x-www-form-urlencoded`), decodable in standard JavaScript with `new URLSearchParams(CLOCK_MODE)`.
|
|
|
|
- If operating using **block number**:
|
|
- If the block number is that of the `NUMBER` opcode (`0x43`), then this function MUST return `mode=blocknumber&from=default`.
|
|
- If it is any other block number, then this function MUST return `mode=blocknumber&from=<CAIP-2-ID>`, where `<CAIP-2-ID>` is a CAIP-2 Blockchain ID such as `eip155:1`.
|
|
- If operating using **timestamp**, then this function MUST return `mode=timestamp`.
|
|
- If operating using any other mode, then this function SHOULD return a unique identifier for the encoded `mode` field.
|
|
|
|
```yaml
|
|
- name: CLOCK_MODE
|
|
type: function
|
|
stateMutability: view
|
|
inputs: []
|
|
outputs:
|
|
- name: descriptor
|
|
type: string
|
|
```
|
|
|
|
### Expected properties
|
|
|
|
- The `clock()` function MUST be non-decreasing.
|
|
|
|
## Rationale
|
|
|
|
`clock` returns `uint48` as it is largely sufficient for storing realistic values. In timestamp mode, `uint48` will be enough until the year 8921556. Even in block number mode, with 10,000 blocks per second, it would be enough until the year 2861. Using a type smaller than `uint256` allows storage packing of timepoints with other associated values, greatly reducing the cost of writing and reading from storage.
|
|
|
|
Depending on the evolution of the blockchain (particularly layer twos), using a smaller type, such as `uint32` might cause issues fairly quickly. On the other hand, anything bigger than `uint48` appears wasteful.
|
|
|
|
## Security Considerations
|
|
|
|
No known security issues.
|
|
|
|
## Copyright
|
|
|
|
Copyright and related rights waived via [CC0](../LICENSE.md).
|