fix: correct struct order, update references, and improve formatting

Author: agronetlabs

EIPS/eip-8040.md

@@ -1,29 +1,38 @@
 ---
-eip: 8040
+eip: TBD
 title: ESG Tokenization Protocol
-description: ESG-compliant, AI-native asset tokenization with quantum auditability and lifecycle integrity.
+description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security.
 author: Leandro Lemos (@agronetlabs) <[email protected]>
-discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846
+discussions-to: https://ethereum-magicians.org/t/erc-esg-tokenization-protocol-agrocrypto/ADD-SLUG
 status: Draft
 type: Standards Track
-category: ERC
+category: Core
 created: 2025-09-06
 requires: 20, 721, 1155
+license: CC0-1.0
 ---
 
-## Abstract
+# Abstract
 
-This ERC defines an AI-native protocol for ESG-compliant asset tokenization, with quantum auditability, compliance-grade metadata, and lifecycle integrity.
+This EIP defines a compliance-grade, AI-native protocol for ESG-compliant asset tokenization, governed by ATF-AI and protected by post-quantum cryptography.
+It codifies lifecycle, metadata, and auditability for compliance-grade deployment, aligns with UN SDGs, and enforces machine-verifiable governance for public, audit-ready markets.
 
-## Specification
+# Motivation
 
-### Metadata Structure
+Current tokenization standards (ERC-20, ERC-721, ERC-1155) do not provide out-of-the-box mechanisms for deterministic auditability, ESG alignment, and compliance-first lifecycle controls demanded by institutional environments.
+This proposal defines a governance and metadata framework to:
+- Enforce lifecycle integrity (issue, audit, retire).
+- Guarantee immutable, verifiable, and attestable metadata.
+- Enable machine-verifiable attestations under ATF-AI.
+- Provide forward security posture with post-quantum readiness.
 
-Tokens MUST expose a metadata JSON with the following minimum fields:
+# Specification
 
-json
+## Metadata Structure
 
-```
+Tokens MUST expose a metadata JSON with the following minimum fields:
+
+```json
 {
   "standard": "ERC-ESG/1.0",
   "category": "carbon",
@@ -41,134 +50,128 @@ json
 }
 ```
 
-### Smart Contract Interface
+### Interface
 
-Contracts implementing this standard MUST support the following interface:
-
-solidity
+Contracts SHOULD implement (Solidity):
 
+```solidity
+function mintESGToken(Metadata memory metadata) external;
+function auditESGToken(uint256 tokenId) external;
+function retireESGToken(uint256 tokenId) external;
+function esgURI(uint256 tokenId) external view returns (string memory);
 ```
-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)
-    struct Metadata {
-        string standard;
-        string category;
-        string geo;
-        uint256 carbon_value;
-        string cycle;
-        bytes digest;  // SHA3-512 digest (64 bytes)
-        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)
-    struct Attestation {
-        bytes atf_digest;  // SHA3-512 attestation digest (64 bytes)
-        string signer;
-    }
-    
-    /// @notice Mints a new ESG token with provided metadata
-    /// @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)
-    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
-    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
-    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
-    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")
-    event Minted(uint256 indexed tokenId, string category, string geo);
-    
-    /// @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
-    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
-    event Retired(uint256 indexed tokenId, uint256 timestamp, string reason);
-}
+
+### Events
+
+```solidity
+event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI);
+event Retired(uint256 indexed tokenId, uint256 amount, string reason);
 ```
 
 ### JSON-RPC Example
 
-json
-
-```
+```json
 {
+  "jsonrpc": "2.0",
+  "id": 1,
   "method": "eth_call",
   "params": [
     {
       "to": "0xContractAddress",
-      "data": "0x..."
-    }
-  ],
-  "example_metadata": {
-    "category": "carbon",
-    "geo": "BR-RS",
-    "carbon_value": 12.5,
-    "digest": "sha3-512:abc123def456...",
-    "attestation": {
-      "atf_digest": "sha3-512:xyz789...",
-      "signer": "did:atf:ai:validator-001"
-    }
-  }
+      "data": "mintESGToken(encodedMetadata)"
+    },
+    "latest"
+  ]
 }
 ```
 
 ### 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.
-- [ERC-1155](./eip-1155.md): Homogeneous batch with common URI, metadata, and fungible amounts.
+- **ERC-20:** Each unit = a standardized fraction (e.g., 1e18 = 1 tCO2e).
+- **ERC-721:** Single credit, unique esgURI.
+- **ERC-1155:** Homogeneous batch with common URI and amount.
+
+# Rationale
+
+This protocol is designed for compliance-grade and non-speculative deployment.
+It enforces deterministic flows, immutable metadata, machine-verifiable audit trails, and compliance-grade governance.
+*atfDigest* and *buildDigest* unite off-chain audit with on-chain proof.
+The protocol is extensible and avoids hard-forks by using optional interfaces and events.
+
+Within this framework, **AI-Compliance** is defined as:
+**AI-Compliance = AI-Governed DAO**
+
+This establishes ATF-AI as a compliance mechanism where governance is executed through an AI-Governed DAO, rather than discretionary human oversight.
+It codifies compliance into a machine-verifiable, audit-ready process that remains deterministic across jurisdictions.
+
+# Backwards Compatibility
+
+Does not break ERC-20,721,1155.
+Legacy tokens may reference metadata externally but lack full ATF-AI compliance.
+Migration tools can wrap legacy tokens with compliant metadata, enabling gradual adoption.
+
+# Test Cases
+
+- Mint token with valid metadata.
+- Audit token with ATF-AI digest.
+- Retire token and log final audit state.
+- Validate physical seal against metadata digest.
+
+# Security Considerations
+
+- Metadata MUST be immutable and cryptographically sealed.
+- ATF-AI provides zero-trust validation; all attestations timestamped.
+- Digest (SHA3-512) ensures audit integrity.
+- Quantum-ready primitives recommended for all bridges.
+- Retirement is irreversible; physical seals MUST validate against digest.
+- All inputs and off-chain docs MUST be hashed and publicly referenced.
+
+# Reference Implementation
+
+- Crate: agrocrypto-core v2.0.0
+- GitHub: agrocrypto-core
+- ESG Manifest: ESG-Manifest
+- AgroCryptoGit Profile: AgroCryptoGit
+- Manifesto: Human+AI (published with hash)
+
+**Hashes:**
+- 201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6
+- f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645
+
+**Timestamp:** 2025-09-06T08:21:00 PDT
+
+# Changelog
+
+All changes to this protocol are treated as compliance-grade events.
+Each entry below is timestamped and hashed for public auditability.
+
+**Added**
+
+- Initial publication of the AgroCrypto Quantum Governance EIP.
+- Lifecycle methods: mintESGToken, auditESGToken, retireESGToken.
+- Metadata structure with SHA3-512 digest and optional physical seal.
+- JSON-RPC example for AI-native minting.
+- Reference implementation: agrocrypto-core v2.0.0.
+- Security considerations: PQC readiness, zero-trust validation, seal verification.
+- Citation and license: CC0 + compliance-grade copyright.
+
+**Hashes:**
+201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6
+f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645
 
-## Rationale
+**Planned**
 
-- **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.
-- **Full hash storage**: Using bytes instead of bytes32 allows complete SHA3-512 digest storage (64 bytes).
+- Integration with AgroPay for ESG token lifecycle tracking.
+- Visual seal registry with cryptographic linkage to metadata.
+- Expanded test cases for audit and retirement flows.
+- Optional bridge module for multi-chain deployment.
 
-## Security Considerations
+# Compliance Notes
 
-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.
-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.
-6. **Physical seal validation**: On-chain digest MUST match physical seal cryptographic hash.
-7. **Input validation**: All off-chain documents MUST be hashed using SHA3-512 and publicly referenced on-chain.
-8. **Hash truncation prevention**: Implementations MUST NOT truncate SHA3-512 digests. The bytes type MUST be used instead of bytes32 to prevent loss of cryptographic security.
+- All corrections are treated as compliance-grade events.
+- Hashes are published publicly and timestamped.
+- No retroactive edits permitted without changelog entry.
 
-## Copyright
+# Copyright
 
 Copyright and related rights waived via CC0-1.0.