ERC-8040 - ESG Tokenization Protocol

{
  "standard": "ERC-8040/1.0",
  "category": "carbon",
  "geo": "BR-RS",
  "carbon_value": 12.5,
  "cycle": "2025-Q3",
  "digest": "sha3-512:...",
  "physical_id": "seal:XYZ123",
  "attestation": {
    "atf_digest": "sha3-512:...",
    "signer": "did:atf:ai:..."
  },
  "status": "issued|audited|retired",
  "evidence": "cid:Qm..."
}

pragma solidity ^0.8.0;

interface IERC8040 {
    /// @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 of the metadata or source document.
        string physical_id;
        Attestation attestation;
        string status;
        string evidence;
    }

    /// @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;
        string signer;
    }

    /// @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 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.
    /// @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 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.
    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, 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 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.
    event Retired(uint256 indexed tokenId, uint256 timestamp, string reason);
}

{
  "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"
    }
  }
}