Address ERC-8040 review feedback

Author: agronetlabs

ERCS/erc-8040.md

@@ -1,7 +1,7 @@
 ---
 eip: 8040
 title: ESG Tokenization Protocol
-description: ESG-compliant, AI-native asset tokenization with quantum auditability and lifecycle integrity.
+description: Environmental, Social, and Governance (ESG) asset tokenization with metadata, attestations, and lifecycle integrity.
 author: Leandro Lemos (@agronetlabs) <leandro@agronet.io>
 discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846
 status: Draft
@@ -13,18 +13,22 @@ requires: 20, 721, 1155
 
 ## Abstract
 
-This ERC defines an AI-native protocol for ESG-compliant asset tokenization, with quantum auditability, compliance-grade metadata, and lifecycle integrity.
+This ERC defines an overlay interface and metadata schema for representing Environmental, Social, and Governance (ESG) assets with existing token standards. Compliant contracts expose ESG metadata through a token-specific URI and an optional on-chain metadata view, record attestations as cryptographic digests, and emit events when assets are minted, audited, attested, or retired. The interface is intended to be implemented alongside [ERC-20](./eip-20.md), [ERC-721](./eip-721.md), or [ERC-1155](./eip-1155.md) so that ESG assets can keep their normal transfer semantics while adding machine-readable lifecycle state.
 
 ## 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](https://www.rfc-editor.org/rfc/rfc2119) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174).
+
+This ERC is an overlay for tokenized ESG assets. Implementations maintain normal token ownership and transfer behavior through a base token standard, and add this ERC's functions for ESG metadata retrieval, audit recording, attestation recording, and retirement. Each token has a lifecycle status of `issued`, `audited`, or `retired`.
+
 ### Metadata Structure
 
-Tokens MUST expose a metadata JSON with the following minimum fields:
+Tokens MUST expose a metadata JSON document with the following minimum fields. Implementations MUST make this document available from `esgURI(uint256 tokenId)`. Implementations MAY also return the same values through `getMetadata(uint256 tokenId)` when storing the metadata on-chain.
 
 
 ```json
 {
-  "standard": "ERC-ESG/1.0",
+  "standard": "ERC-8040/1.0",
   "category": "carbon",
   "geo": "BR-RS",
   "carbon_value": 12.5,
@@ -40,86 +44,97 @@ Tokens MUST expose a metadata JSON with the following minimum fields:
 }
 ```
 
+The `standard` field identifies the metadata version. The `category` field describes the ESG asset class. The `geo` field identifies the geographic area for the asset. The `carbon_value` field represents the asset value for carbon assets. The `digest`, `physical_id`, `attestation`, and `evidence` fields bind the token to source records, external attestations, and supporting documentation. The `status` field records the lifecycle state.
+
 ### Smart Contract Interface
 
 Contracts implementing this standard MUST support the following interface:
 
 ```solidity
-
 pragma solidity ^0.8.0;
 
 interface IERC8040 {
-    /// @notice Metadata structure for ESG tokens
-    /// @dev All digest fields use bytes to support SHA3-512 (64 bytes)
+    /// @notice Metadata structure for Environmental, Social, and Governance tokens.
+    /// @dev Digest fields use bytes to support SHA3-512 values without truncation.
     struct Metadata {
         string standard;
         string category;
         string geo;
         uint256 carbon_value;
         string cycle;
-        bytes digest;  // SHA3-512 digest (64 bytes)
+        bytes digest; // SHA3-512 digest of the metadata or source document.
         string physical_id;
         Attestation attestation;
         string status;
         string evidence;
     }
     
-    /// @notice Attestation structure for AI-native validation
-    /// @dev atf_digest uses bytes to support SHA3-512 (64 bytes)
+    /// @notice Attestation structure for an external audit or validation result.
+    /// @dev atf_digest is a SHA3-512 digest of the attestation record.
     struct Attestation {
-        bytes atf_digest;  // SHA3-512 attestation digest (64 bytes)
+        bytes atf_digest;
         string signer;
     }
     
-    /// @notice Mints a new ESG token with provided metadata
-    /// @param metadata The ESG metadata structure
+    /// @notice Mints a new ESG token with provided metadata.
+    /// @dev The caller MUST be authorized by the implementation to issue ESG assets.
+    ///      The initial lifecycle status MUST be issued.
+    /// @param metadata The ESG metadata structure.
     /// @return tokenId The ID of the newly minted token
     function mintESGToken(Metadata memory metadata) external returns (uint256 tokenId);
     
-    /// @notice Audits an existing ESG token
-    /// @param tokenId The token to audit
-    /// @param auditDigest SHA3-512 digest of the audit report (64 bytes)
+    /// @notice Records an audit for an existing ESG token.
+    /// @dev The caller MUST be authorized by the implementation to audit ESG assets.
+    ///      The lifecycle status MUST become audited after a successful audit.
+    /// @param tokenId The token to audit.
+    /// @param auditDigest SHA3-512 digest of the audit report.
     function auditESGToken(uint256 tokenId, bytes memory auditDigest) external;
     
-    /// @notice Retires an ESG token permanently
-    /// @param tokenId The token to retire
-    /// @param reason Human-readable retirement reason
+    /// @notice Retires an ESG token permanently.
+    /// @dev The caller MUST be the token owner, an approved operator, or otherwise
+    ///      authorized by the implementation. Retired tokens MUST NOT be reactivated.
+    /// @param tokenId The token to retire.
+    /// @param reason Human-readable retirement reason.
     function retireESGToken(uint256 tokenId, string memory reason) external;
     
-    /// @notice Returns the ESG metadata URI for a token
-    /// @param tokenId The token ID
-    /// @return The URI string pointing to off-chain metadata
+    /// @notice Returns the ESG metadata Uniform Resource Identifier (URI) for a token.
+    /// @param tokenId The token ID.
+    /// @return The URI string pointing to the metadata JSON document.
     function esgURI(uint256 tokenId) external view returns (string memory);
     
-    /// @notice Returns the complete on-chain metadata for a token
-    /// @param tokenId The token ID
-    /// @return The complete Metadata structure
+    /// @notice Returns the complete on-chain metadata for a token.
+    /// @param tokenId The token ID.
+    /// @return The complete Metadata structure.
     function getMetadata(uint256 tokenId) external view returns (Metadata memory);
     
-    /// @notice Emitted when a new ESG token is minted
-    /// @param tokenId The ID of the minted token
-    /// @param category The ESG category (e.g., "carbon")
-    /// @param geo Geographic identifier (e.g., "BR-RS")
+    /// @notice Emitted when a new ESG token is minted.
+    /// @param tokenId The ID of the minted token.
+    /// @param category The ESG category, such as carbon.
+    /// @param geo Geographic identifier, such as an ISO 3166-2 subdivision code.
     event Minted(uint256 indexed tokenId, string category, string geo);
+
+    /// @notice Emitted when an ESG token is audited.
+    /// @param tokenId The ID of the audited token.
+    /// @param auditDigest SHA3-512 digest of the audit report.
+    event Audited(uint256 indexed tokenId, bytes auditDigest);
     
-    /// @notice Emitted when a token is attested by AI validator
-    /// @param tokenId The ID of the attested token
-    /// @param atfDigest SHA3-512 digest of the attestation (64 bytes)
-    /// @param esgURI The URI of the ESG metadata
+    /// @notice Emitted when a token receives an external attestation.
+    /// @param tokenId The ID of the attested token.
+    /// @param atfDigest SHA3-512 digest of the attestation record.
+    /// @param esgURI The URI of the ESG metadata.
     event Attested(uint256 indexed tokenId, bytes atfDigest, string esgURI);
     
-    /// @notice Emitted when a token is permanently retired
-    /// @param tokenId The ID of the retired token
-    /// @param timestamp The retirement timestamp
-    /// @param reason Human-readable retirement reason
+    /// @notice Emitted when a token is permanently retired.
+    /// @param tokenId The ID of the retired token.
+    /// @param timestamp The retirement timestamp.
+    /// @param reason Human-readable retirement reason.
     event Retired(uint256 indexed tokenId, uint256 timestamp, string reason);
 }
 ```
 
 ### JSON-RPC Example
 
 ```json
-
 {
   "method": "eth_call",
   "params": [
@@ -143,22 +158,24 @@ interface IERC8040 {
 
 ### Mapping & Compatibility
 
-- [ERC-20](./eip-20.md): Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e).
-- [ERC-721](./eip-721.md): Single credit with unique esgURI and immutable metadata.
+This ERC does not replace [ERC-20](./eip-20.md), [ERC-721](./eip-721.md), or [ERC-1155](./eip-1155.md). A compliant contract implements this ERC in addition to at least one base token standard.
+
+- [ERC-20](./eip-20.md): Each unit represents a standardized fraction, such as 1e18 units representing one metric tonne of carbon dioxide equivalent (tCO2e).
+- [ERC-721](./eip-721.md): Single credit with unique `esgURI` and immutable metadata.
 - [ERC-1155](./eip-1155.md): Homogeneous batch with common URI, metadata, and fungible amounts.
 
 ## Rationale
 
-- **Deterministic flows**: Lifecycle follows strict state transitions (issued → audited → retired).
-- **Immutable metadata**: SHA3-512 digest ensures tamper-proof records with 512-bit security.
-- **Machine-verifiable audit trails**: ATF-AI validates compliance deterministically.
-- **Post-quantum readiness**: SHA3-512 hash functions provide quantum-resistant cryptography.
+- **Deterministic flows**: Lifecycle follows strict state transitions (`issued` to `audited` to `retired`).
+- **Immutable metadata**: SHA3-512 digests bind metadata and evidence documents to the token record.
+- **Machine-verifiable audit trails**: Attestation digests and events allow off-chain systems to verify audit records deterministically.
+- **Post-quantum readiness**: SHA3-512 hash functions provide preimage resistance suitable for long-lived audit records.
 - **Full hash storage**: Using bytes instead of bytes32 allows complete SHA3-512 digest storage (64 bytes).
 
 ## Security Considerations
 
 1. **Metadata immutability**: All metadata fields MUST be cryptographically sealed after minting.
-2. **Zero-trust validation**: ATF-AI provides deterministic validation; all attestations are timestamped.
+2. **Validation independence**: Implementations MUST NOT rely on unauthenticated off-chain statements. Attestations MUST be represented by verifiable digests and events.
 3. **Digest integrity**: SHA3-512 (64 bytes) ensures audit-trail integrity. Implementations MUST use bytes type to store complete 512-bit digests.
 4. **Post-quantum cryptography**: Hash functions and signature schemes MUST be quantum-resistant. SHA3-512 provides 512-bit security suitable for post-quantum scenarios.
 5. **Irreversible retirement**: Once retired, tokens cannot be reactivated.
@@ -168,4 +185,4 @@ interface IERC8040 {
 
 ## Copyright
 
-Copyright and related rights waived via CC0-1.0.
+Copyright and related rights waived via [CC0](../LICENSE.md).