From 82c225a340d8c4cb45e64fea1692986aa7f79a49 Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Tue, 7 Oct 2025 16:09:42 -0700 Subject: [PATCH 01/53] Add AgroCrypto Quantum Governance ESG Tokenization Protocol (ERC draft) Initial submission of ERC draft implementing ESG token lifecycle governance with AI-native compliance and metadata auditability. Provides methods `mintESGToken`, `auditESGToken`, and `retireESGToken` compatible with ERC-20/721/1155. --- ERCS/eip-agrocrypto-quantum.md | 350 +++++++++++++++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 ERCS/eip-agrocrypto-quantum.md diff --git a/ERCS/eip-agrocrypto-quantum.md b/ERCS/eip-agrocrypto-quantum.md new file mode 100644 index 00000000000..ceb4eb5c16f --- /dev/null +++ b/ERCS/eip-agrocrypto-quantum.md @@ -0,0 +1,350 @@ +--- + +eip: TBD + +title: AgroCrypto Quantum Governance — ESG Tokenization Protocol + +description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security. + +author: Leandro Lemos (@agronetlabs) + +discussions-to: https://ethereum-magicians.org/t/erc-esg-tokenization-protocol-agrocrypto/ADD-SLUG + +status: Draft + +type: Standards Track + +category: Core + +created: 2025-09-06 + +requires: 20, 721, 1155 + +license: CC0-1.0 + +--- + + + +\# Abstract + + + +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 + + + +\## Metadata Structure + + + +Tokens MUST expose a metadata JSON with the following minimum fields: + + + +```json + +{ + +  "standard": "ERC-ESG/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..." + +} + +``` + + + +\### Interface + + + +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); + +``` + + + +\### Events + + + +```solidity + +event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); + +event Retired(uint256 indexed tokenId, uint256 amount, string reason); + +``` + + + +\### JSON-RPC Example + + + +```json + +eth\_call \[ + +  "0xContractAddress", + +  "mintESGToken", + +  { + +  "metadata": { + +  "category": "carbon", + +  "geo": "BR-RS", + +  "digest": "sha3-512:..." + +  } + +  } + +] + +``` + + + +\### Mapping \& Compatibility + + + +\- \*\*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 + + + +\# Copyright + + + +Copyright and related rights waived via CC0-1.0. + +© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. + + + +\# Changelog + + + +All changes to this protocol are treated as compliance-grade events. + +Each entry below is timestamped and hashed for public auditability. + + + +\## \[1.0.0] — 2025-09-06 + + + +\*\*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 + + + +\## \[1.0.1] — TBA + + + +\*\*Planned\*\* + + + +\- 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. + + + +\# Compliance Notes + + + +\- All corrections are treated as compliance-grade events. + +\- Hashes are published publicly and timestamped. + +\- No retroactive edits permitted without changelog entry. + + + +© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. + From 0b424a6dd6899e79ce7c4beb50a1a659ad818980 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 8 Oct 2025 01:54:59 +0000 Subject: [PATCH 02/53] Initial plan From 0bcef555e972a3be7a06ac2160ade0cf2ec56c9b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 8 Oct 2025 01:58:29 +0000 Subject: [PATCH 03/53] Apply EIP-8040 editor feedback: rename file, update YAML, fix escaped underscores Co-authored-by: agronetlabs <221334392+agronetlabs@users.noreply.github.com> --- ERCS/{eip-agrocrypto-quantum.md => eip-8040.md} | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) rename ERCS/{eip-agrocrypto-quantum.md => eip-8040.md} (96%) diff --git a/ERCS/eip-agrocrypto-quantum.md b/ERCS/eip-8040.md similarity index 96% rename from ERCS/eip-agrocrypto-quantum.md rename to ERCS/eip-8040.md index ceb4eb5c16f..4e0f23ee619 100644 --- a/ERCS/eip-agrocrypto-quantum.md +++ b/ERCS/eip-8040.md @@ -1,8 +1,8 @@ --- -eip: TBD +eip: 8040 -title: AgroCrypto Quantum Governance — ESG Tokenization Protocol +title: ESG Tokenization Protocol description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security. @@ -14,7 +14,7 @@ status: Draft type: Standards Track -category: Core +category: ERC created: 2025-09-06 @@ -58,17 +58,17 @@ Tokens MUST expose a metadata JSON with the following minimum fields:   "geo": "BR-RS", -  "carbon\_value": 12.5, +  "carbon_value": 12.5,   "cycle": "2025-Q3",   "digest": "sha3-512:...", -  "physical\_id": "seal:XYZ123", +  "physical_id": "seal:XYZ123",   "attestation": { -  "atf\_digest": "sha3-512:...", +  "atf_digest": "sha3-512:...",   "signer": "did:atf:ai:..." @@ -126,7 +126,7 @@ event Retired(uint256 indexed tokenId, uint256 amount, string reason); ```json -eth\_call \[ +eth_call [   "0xContractAddress", From d03e5a5987496881d94c4a403f22d6dc30ea9d88 Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Thu, 16 Oct 2025 20:57:54 -0300 Subject: [PATCH 04/53] Remove all backslash escape characters from markdown formatting --- ERCS/eip-8040.md | 352 ++--------------------------------------------- 1 file changed, 12 insertions(+), 340 deletions(-) diff --git a/ERCS/eip-8040.md b/ERCS/eip-8040.md index 4e0f23ee619..73017ba5fc6 100644 --- a/ERCS/eip-8040.md +++ b/ERCS/eip-8040.md @@ -1,350 +1,22 @@ ---- +# EIP-8040 -eip: 8040 +## Title -title: ESG Tokenization Protocol +This is an example EIP document. -description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security. +### Abstract -author: Leandro Lemos (@agronetlabs) +This EIP proposes a standard for something important. -discussions-to: https://ethereum-magicians.org/t/erc-esg-tokenization-protocol-agrocrypto/ADD-SLUG +### Motivation -status: Draft +The motivation behind this EIP is to improve the Ethereum ecosystem. -type: Standards Track +### Specification -category: ERC +- Point 1 +- Point 2 -created: 2025-09-06 +### Conclusion -requires: 20, 721, 1155 - -license: CC0-1.0 - ---- - - - -\# Abstract - - - -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 - - - -\## Metadata Structure - - - -Tokens MUST expose a metadata JSON with the following minimum fields: - - - -```json - -{ - -  "standard": "ERC-ESG/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..." - -} - -``` - - - -\### Interface - - - -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); - -``` - - - -\### Events - - - -```solidity - -event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); - -event Retired(uint256 indexed tokenId, uint256 amount, string reason); - -``` - - - -\### JSON-RPC Example - - - -```json - -eth_call [ - -  "0xContractAddress", - -  "mintESGToken", - -  { - -  "metadata": { - -  "category": "carbon", - -  "geo": "BR-RS", - -  "digest": "sha3-512:..." - -  } - -  } - -] - -``` - - - -\### Mapping \& Compatibility - - - -\- \*\*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 - - - -\# Copyright - - - -Copyright and related rights waived via CC0-1.0. - -© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. - - - -\# Changelog - - - -All changes to this protocol are treated as compliance-grade events. - -Each entry below is timestamped and hashed for public auditability. - - - -\## \[1.0.0] — 2025-09-06 - - - -\*\*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 - - - -\## \[1.0.1] — TBA - - - -\*\*Planned\*\* - - - -\- 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. - - - -\# Compliance Notes - - - -\- All corrections are treated as compliance-grade events. - -\- Hashes are published publicly and timestamped. - -\- No retroactive edits permitted without changelog entry. - - - -© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. - +This EIP aims to provide clarity and improvement. From c6dc9a7f0b5d61ee1cc7e95aed6a2a37ac7aa944 Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Thu, 16 Oct 2025 21:11:44 -0300 Subject: [PATCH 05/53] Add ERC-8040 ESG Tokenization Protocol documentation This commit introduces the ERC-8040 ESG Tokenization Protocol, detailing its standards, metadata structure, smart contract interface, and security considerations. It also includes a changelog and compliance notes for governance. --- ERCS/eip-8040.md | 251 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 239 insertions(+), 12 deletions(-) diff --git a/ERCS/eip-8040.md b/ERCS/eip-8040.md index 73017ba5fc6..a61094ba56c 100644 --- a/ERCS/eip-8040.md +++ b/ERCS/eip-8040.md @@ -1,22 +1,249 @@ -# EIP-8040 +--- +eip: 8040 +title: ESG Tokenization Protocol +description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security. +author: Leandro Lemos (@agronetlabs) +discussions-to: https://ethereum-magicians.org/t/erc-esg-tokenization-protocol-agrocrypto/ADD-SLUG +status: Draft +type: Standards Track +category: ERC +created: 2025-09-06 +requires: 20, 721, 1155 +license: CC0-1.0 +--- -## Title +# Abstract -This is an example EIP document. +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. -### Abstract +# Motivation -This EIP proposes a standard for something important. +ESG tokenization requires: +- Immutable audit trails +- Machine-verifiable compliance +- Post-quantum cryptographic security +- Deterministic lifecycle management +- Integration with AI-governed DAOs -### Motivation +# Specification -The motivation behind this EIP is to improve the Ethereum ecosystem. +## Metadata Structure -### Specification +Tokens MUST expose a metadata JSON with the following minimum fields: -- Point 1 -- Point 2 +```json +{ + "standard": "ERC-ESG/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..." +} +``` -### Conclusion +## Smart Contract Interface -This EIP aims to provide clarity and improvement. +Contracts implementing this standard MUST support the following interface: + +```solidity +pragma solidity ^0.8.0; + +interface IESCG8040 { + + struct Metadata { + string standard; + string category; + string geo; + uint256 carbon_value; + string cycle; + bytes32 digest; + string physical_id; + Attestation attestation; + string status; + string evidence; + } + + struct Attestation { + bytes32 atf_digest; + string signer; + } + + // Core Functions + function mintESGToken(Metadata memory metadata) external returns (uint256 tokenId); + + function auditESGToken(uint256 tokenId, bytes32 auditDigest) external; + + function retireESGToken(uint256 tokenId, string memory reason) external; + + function esgURI(uint256 tokenId) external view returns (string memory); + + function getMetadata(uint256 tokenId) external view returns (Metadata memory); + + // Events + event Minted(uint256 indexed tokenId, string category, string geo); + + event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); + + event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); +} +``` + +## Events + +```solidity +event Minted(uint256 indexed tokenId, string category, string geo); + +event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); + +event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); +``` + +## JSON-RPC Example + +```json +{ + "method": "eth_call", + "params": [ + { + "to": "0xContractAddress", + "data": "0x..." + } + ], + "example_metadata": { + "category": "carbon", + "geo": "BR-RS", + "carbon_value": 12.5, + "digest": "sha3-512:abc123def456..." + } +} +``` + +## Mapping & Compatibility + +- **ERC-20**: Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e). +- **ERC-721**: Single credit with unique esgURI and immutable metadata. +- **ERC-1155**: Homogeneous batch with common URI, metadata, and fungible amounts. + +# Rationale + +This protocol enforces: + +- **Deterministic Flows**: Lifecycle follows strict state transitions (issued → audited → retired) +- **Immutable Metadata**: SHA3-512 digest ensures tamper-proof records +- **Machine-Verifiable Audit Trails**: ATF-AI validates compliance deterministically +- **Post-Quantum Readiness**: Hash functions support quantum-resistant cryptography + +### AI-Compliance Definition + +**AI-Compliance = AI-Governed DAO** + +Governance is executed through an AI-Governed DAO rather than discretionary human oversight. This establishes a deterministic, audit-ready compliance mechanism across all jurisdictions. + +### Technical Rationale + +- `atfDigest` and `buildDigest` unite off-chain audit with on-chain proof +- Protocol is extensible via optional interfaces to prevent hard-forks +- Zero-trust validation ensures all attestations are timestamped and verifiable + +# Backwards Compatibility + +This standard does not break ERC-20/721/1155 compatibility. + +- Legacy tokens may reference metadata externally but lack full ATF-AI compliance +- Migration tools can wrap legacy tokens with compliant metadata +- Gradual adoption is supported through optional interface implementation + +# Test Cases + +| Test Case | Expected Outcome | +|-----------|------------------| +| Mint token with valid metadata | Token created with immutable metadata | +| Mint token with invalid digest | Transaction reverts | +| Audit token with ATF-AI digest | Token status transitions to "audited" | +| Retire token with valid reason | Token irreversibly marked as "retired" | +| Validate physical seal against digest | Seal verification succeeds/fails deterministically | +| Query esgURI for audited token | Returns immutable URI reference | + +# 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 +3. **Digest Integrity**: SHA3-512 ensures audit-trail integrity +4. **Post-Quantum Cryptography**: Hash functions and signature schemes MUST be quantum-resistant +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 and publicly referenced on-chain + +# Reference Implementation + +- **Repository**: [agrocrypto-core](https://github.com/AgroCryptoLabs/agrocrypto-core) +- **Version**: v2.0.0 +- **Authors**: AgroCrypto Labs LLC +- **License**: CC0-1.0 + +### Reference Hashes (for auditability) + +``` +201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6 +f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 +``` + +**Timestamp**: 2025-09-06T08:21:00 PDT + +# Copyright + +Copyright and related rights waived via CC0-1.0. + +© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. + +# Changelog + +All changes to this protocol are treated as compliance-grade events. Each entry is timestamped and hashed for public auditability. + +## [1.0.0] — 2025-09-06 + +**Added** +- Initial publication of ERC-8040 ESG Tokenization Protocol +- Lifecycle methods: `mintESGToken`, `auditESGToken`, `retireESGToken` +- Metadata structure with SHA3-512 digest and optional physical seal +- JSON-RPC examples for AI-native minting +- Reference implementation: agrocrypto-core v2.0.0 +- Security considerations: PQC readiness, zero-trust validation, seal verification +- Comprehensive test cases for all lifecycle transitions +- AI-Compliance definition and AI-Governed DAO integration + +**Hashes**: +``` +201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6 +f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 +``` + +## [1.0.1] — Planned + +**Planned Features** +- Integration with AgroPay for ESG token lifecycle tracking +- Visual seal registry with cryptographic linkage to metadata +- Expanded test cases for multi-jurisdiction audit flows +- Optional bridge module for multi-chain deployment +- Enhanced JSON-RPC documentation + +# Compliance Notes + +- All corrections are treated as compliance-grade events +- Hashes are published publicly and timestamped +- No retroactive edits permitted without changelog entry +- All amendments require consensus from ATF-AI governance + +--- + +**© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework** + +--- From 458492686921760bb2eb58d81343c91159ab7b59 Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Thu, 16 Oct 2025 23:23:01 -0300 Subject: [PATCH 06/53] fix(ERC-8040): rename file to match preamble header --- ERCS/{eip-8040.md => erc-8040.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ERCS/{eip-8040.md => erc-8040.md} (100%) diff --git a/ERCS/eip-8040.md b/ERCS/erc-8040.md similarity index 100% rename from ERCS/eip-8040.md rename to ERCS/erc-8040.md From 222b249a155565537b48ff9ab9fa9c5688e1f86c Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Thu, 16 Oct 2025 23:26:24 -0300 Subject: [PATCH 07/53] chore(ERC-8040): fix preamble format for validator compliance --- ERCS/erc-8040.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index a61094ba56c..3cff5ec7997 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -1,15 +1,15 @@ --- eip: 8040 title: ESG Tokenization Protocol -description: Standard for AI-native, compliance-grade, quantum-auditable asset tokenization with lifecycle integrity, provenance, and post-quantum security. +description: AI-native ESG asset tokenization protocol ensuring lifecycle integrity and quantum-grade auditability. author: Leandro Lemos (@agronetlabs) -discussions-to: https://ethereum-magicians.org/t/erc-esg-tokenization-protocol-agrocrypto/ADD-SLUG +discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/19840 status: Draft type: Standards Track category: ERC created: 2025-09-06 requires: 20, 721, 1155 -license: CC0-1.0 +license: CC0 --- # Abstract From eb796291c4ff0950aed5fc030a91f85fe3364b8b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 03:36:21 +0000 Subject: [PATCH 08/53] Initial plan From 5e32171c67f8c60d0f175347cb6f04ef0c0a4f2f Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Fri, 17 Oct 2025 01:03:28 -0300 Subject: [PATCH 09/53] fix(ERC-8040): switch to erc:, set discussions-to=25846, drop license --- ERCS/erc-8040.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 3cff5ec7997..900ceafdb43 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -1,15 +1,14 @@ --- -eip: 8040 +erc: 8040 title: ESG Tokenization Protocol -description: AI-native ESG asset tokenization protocol ensuring lifecycle integrity and quantum-grade auditability. +description: AI-native ESG asset tokenization with lifecycle integrity, attestations, audit trail, and PQC readiness. author: Leandro Lemos (@agronetlabs) -discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/19840 +discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 status: Draft type: Standards Track category: ERC created: 2025-09-06 requires: 20, 721, 1155 -license: CC0 --- # Abstract From 906540d7634266d12feed59828c0e8d8251ade70 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 04:26:57 +0000 Subject: [PATCH 10/53] Initial plan From 03df4d7faa2dd17868d77add2e3f6e6812f185a7 Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Fri, 17 Oct 2025 01:46:19 -0300 Subject: [PATCH 11/53] docs: add ERC-8040 canonical links (release, discussion, spec) --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index f27235fd984..05efbbcd08a 100644 --- a/README.md +++ b/README.md @@ -24,3 +24,9 @@ If you would like to become an EIP Editor, please read [EIP-5069](https://eips.e The canonical URL for an ERC that has achieved draft status at any point is at . For example, the canonical URL for EIP-1 is . Consider any document not published at as a working paper. Additionally, consider published EIPs with a status of "draft", "review", or "last call" to be incomplete drafts, and note that their specification is likely to be subject to change. + +## ERC-8040 — ESG Tokenization Protocol + +- Release: https://github.com/agronetlabs/ERCs/releases/tag/v1.0.0 +- Discussion (Magicians): https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 +- Spec file: ERCS/erc-8040.md From bd1c4ceaeaff2fdfa67351927fa1be60fc82b650 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 18 Oct 2025 00:17:09 +0000 Subject: [PATCH 12/53] Initial plan From 8cfa952e04c5286d40237c795b9cbab276a157a5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 18 Oct 2025 00:47:49 +0000 Subject: [PATCH 13/53] Initial plan From e5a94674e48524c51cb7f382cb661941a696798f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 18 Oct 2025 00:52:21 +0000 Subject: [PATCH 14/53] Replace ERC-8040 content with corrected version - Updated description in header - Changed interface name from IESCG8040 to IERC8040 - Added proper links to ERC-20, ERC-721, and ERC-1155 references - Removed unnecessary sections (Motivation, Backwards Compatibility, Test Cases, Reference Implementation, Changelog, Compliance Notes) - Simplified structure to focus on core specification - Updated discussions-to URL Co-authored-by: agronetlabs <221334392+agronetlabs@users.noreply.github.com> --- ERCS/erc-8040.md | 177 ++++++++--------------------------------------- 1 file changed, 30 insertions(+), 147 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 3cff5ec7997..0694ac6c7aa 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -1,33 +1,23 @@ --- eip: 8040 title: ESG Tokenization Protocol -description: AI-native ESG asset tokenization protocol ensuring lifecycle integrity and quantum-grade auditability. +description: ESG-compliant, AI-native asset tokenization with quantum auditability and lifecycle integrity. author: Leandro Lemos (@agronetlabs) -discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/19840 +discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 status: Draft type: Standards Track category: ERC created: 2025-09-06 requires: 20, 721, 1155 -license: CC0 --- -# Abstract +## Abstract -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. +This ERC defines an AI-native protocol for ESG-compliant asset tokenization, with quantum auditability, compliance-grade metadata, and lifecycle integrity. -# Motivation +## Specification -ESG tokenization requires: -- Immutable audit trails -- Machine-verifiable compliance -- Post-quantum cryptographic security -- Deterministic lifecycle management -- Integration with AI-governed DAOs - -# Specification - -## Metadata Structure +### Metadata Structure Tokens MUST expose a metadata JSON with the following minimum fields: @@ -49,15 +39,14 @@ Tokens MUST expose a metadata JSON with the following minimum fields: } ``` -## Smart Contract Interface +### Smart Contract Interface Contracts implementing this standard MUST support the following interface: ```solidity pragma solidity ^0.8.0; -interface IESCG8040 { - +interface IERC8040 { struct Metadata { string standard; string category; @@ -70,43 +59,32 @@ interface IESCG8040 { string status; string evidence; } - struct Attestation { bytes32 atf_digest; string signer; } - - // Core Functions + function mintESGToken(Metadata memory metadata) external returns (uint256 tokenId); - function auditESGToken(uint256 tokenId, bytes32 auditDigest) external; - function retireESGToken(uint256 tokenId, string memory reason) external; - function esgURI(uint256 tokenId) external view returns (string memory); - function getMetadata(uint256 tokenId) external view returns (Metadata memory); - - // Events + event Minted(uint256 indexed tokenId, string category, string geo); - event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); - event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); } ``` -## Events +### Events ```solidity event Minted(uint256 indexed tokenId, string category, string geo); - event Attested(uint256 indexed tokenId, bytes32 atfDigest, string esgURI); - event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); ``` -## JSON-RPC Example +### JSON-RPC Example ```json { @@ -126,124 +104,29 @@ event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); } ``` -## Mapping & Compatibility - -- **ERC-20**: Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e). -- **ERC-721**: Single credit with unique esgURI and immutable metadata. -- **ERC-1155**: Homogeneous batch with common URI, metadata, and fungible amounts. - -# Rationale - -This protocol enforces: - -- **Deterministic Flows**: Lifecycle follows strict state transitions (issued → audited → retired) -- **Immutable Metadata**: SHA3-512 digest ensures tamper-proof records -- **Machine-Verifiable Audit Trails**: ATF-AI validates compliance deterministically -- **Post-Quantum Readiness**: Hash functions support quantum-resistant cryptography - -### AI-Compliance Definition +### Mapping & Compatibility -**AI-Compliance = AI-Governed DAO** +- **[ERC-20](https://eips.ethereum.org/EIPS/eip-20)**: Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e). +- **[ERC-721](https://eips.ethereum.org/EIPS/eip-721)**: Single credit with unique esgURI and immutable metadata. +- **[ERC-1155](https://eips.ethereum.org/EIPS/eip-1155)**: Homogeneous batch with common URI, metadata, and fungible amounts. -Governance is executed through an AI-Governed DAO rather than discretionary human oversight. This establishes a deterministic, audit-ready compliance mechanism across all jurisdictions. +## Rationale -### Technical Rationale +- Deterministic flows: Lifecycle follows strict state transitions (issued → audited → retired). +- Immutable metadata: SHA3-512 digest ensures tamper-proof records. +- Machine-verifiable audit trails: ATF-AI validates compliance deterministically. +- Post-quantum readiness: Hash functions support quantum-resistant cryptography. -- `atfDigest` and `buildDigest` unite off-chain audit with on-chain proof -- Protocol is extensible via optional interfaces to prevent hard-forks -- Zero-trust validation ensures all attestations are timestamped and verifiable +## Security Considerations -# Backwards Compatibility +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 ensures audit-trail integrity. +4. Post-quantum cryptography: Hash functions and signature schemes MUST be quantum-resistant. +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 and publicly referenced on-chain. -This standard does not break ERC-20/721/1155 compatibility. - -- Legacy tokens may reference metadata externally but lack full ATF-AI compliance -- Migration tools can wrap legacy tokens with compliant metadata -- Gradual adoption is supported through optional interface implementation - -# Test Cases - -| Test Case | Expected Outcome | -|-----------|------------------| -| Mint token with valid metadata | Token created with immutable metadata | -| Mint token with invalid digest | Transaction reverts | -| Audit token with ATF-AI digest | Token status transitions to "audited" | -| Retire token with valid reason | Token irreversibly marked as "retired" | -| Validate physical seal against digest | Seal verification succeeds/fails deterministically | -| Query esgURI for audited token | Returns immutable URI reference | - -# 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 -3. **Digest Integrity**: SHA3-512 ensures audit-trail integrity -4. **Post-Quantum Cryptography**: Hash functions and signature schemes MUST be quantum-resistant -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 and publicly referenced on-chain - -# Reference Implementation - -- **Repository**: [agrocrypto-core](https://github.com/AgroCryptoLabs/agrocrypto-core) -- **Version**: v2.0.0 -- **Authors**: AgroCrypto Labs LLC -- **License**: CC0-1.0 - -### Reference Hashes (for auditability) - -``` -201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6 -f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 -``` - -**Timestamp**: 2025-09-06T08:21:00 PDT - -# Copyright +## Copyright Copyright and related rights waived via CC0-1.0. - -© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. - -# Changelog - -All changes to this protocol are treated as compliance-grade events. Each entry is timestamped and hashed for public auditability. - -## [1.0.0] — 2025-09-06 - -**Added** -- Initial publication of ERC-8040 ESG Tokenization Protocol -- Lifecycle methods: `mintESGToken`, `auditESGToken`, `retireESGToken` -- Metadata structure with SHA3-512 digest and optional physical seal -- JSON-RPC examples for AI-native minting -- Reference implementation: agrocrypto-core v2.0.0 -- Security considerations: PQC readiness, zero-trust validation, seal verification -- Comprehensive test cases for all lifecycle transitions -- AI-Compliance definition and AI-Governed DAO integration - -**Hashes**: -``` -201672f1605f30a361254cacbb073d8de7b806ba392ef82ca4723e17f4d39dd6 -f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 -``` - -## [1.0.1] — Planned - -**Planned Features** -- Integration with AgroPay for ESG token lifecycle tracking -- Visual seal registry with cryptographic linkage to metadata -- Expanded test cases for multi-jurisdiction audit flows -- Optional bridge module for multi-chain deployment -- Enhanced JSON-RPC documentation - -# Compliance Notes - -- All corrections are treated as compliance-grade events -- Hashes are published publicly and timestamped -- No retroactive edits permitted without changelog entry -- All amendments require consensus from ATF-AI governance - ---- - -**© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework** - ---- From 01f32cbab69145903131bd533fa662ad8b55cd22 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 18 Oct 2025 00:55:57 +0000 Subject: [PATCH 15/53] Fix ERC reference links to use relative paths - Changed ERC-20, ERC-721, and ERC-1155 links from absolute URLs to relative paths (./eip-20.md, ./eip-721.md, ./eip-1155.md) - All validator checks now pass (eipw, markdownlint) Co-authored-by: agronetlabs <221334392+agronetlabs@users.noreply.github.com> --- ERCS/erc-8040.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 0694ac6c7aa..ed307679122 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -106,9 +106,9 @@ event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); ### Mapping & Compatibility -- **[ERC-20](https://eips.ethereum.org/EIPS/eip-20)**: Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e). -- **[ERC-721](https://eips.ethereum.org/EIPS/eip-721)**: Single credit with unique esgURI and immutable metadata. -- **[ERC-1155](https://eips.ethereum.org/EIPS/eip-1155)**: Homogeneous batch with common URI, metadata, and fungible amounts. +- **[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. ## Rationale From 7429fd15166181d7338410d5ed34ee88782a9e4b Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Fri, 17 Oct 2025 21:57:57 -0300 Subject: [PATCH 16/53] Update ERCS/erc-8040.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ERCS/erc-8040.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index ed307679122..f5a18cb546f 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -15,6 +15,10 @@ requires: 20, 721, 1155 This ERC defines an AI-native protocol for ESG-compliant asset tokenization, with quantum auditability, compliance-grade metadata, and lifecycle integrity. + +## Motivation + +ESG asset tokenization currently lacks standardized protocols for ensuring compliance, auditability, and lifecycle integrity. Existing standards do not address the unique requirements of ESG assets, such as verifiable environmental impact, AI-driven attestation, and quantum-resistant audit trails. This ERC introduces a unified protocol to enable transparent, secure, and compliant tokenization of ESG assets, facilitating interoperability and trust across platforms. ## Specification ### Metadata Structure From 47d9180a9f58628d67838c8d32cbceba06fc2686 Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Fri, 17 Oct 2025 21:58:07 -0300 Subject: [PATCH 17/53] Update ERCS/erc-8040.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ERCS/erc-8040.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index f5a18cb546f..1cba109bda5 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -9,6 +9,7 @@ type: Standards Track category: ERC created: 2025-09-06 requires: 20, 721, 1155 +license: CC0-1.0 --- ## Abstract From 2043ff44ec4537e07ffd7f57e46c0b95cd710248 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 18 Oct 2025 01:22:09 +0000 Subject: [PATCH 18/53] Initial plan From b8b953b5129dacf54bc5b07516e9f0bc21489198 Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Fri, 17 Oct 2025 23:32:45 -0300 Subject: [PATCH 19/53] Finalize ERC-8040: filename rename and markdown-link lint fixes --- ERCS/erc-8040.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 900ceafdb43..4ca4f495f81 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -13,7 +13,7 @@ requires: 20, 721, 1155 # Abstract -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. +This ERC 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. # Motivation @@ -154,7 +154,7 @@ Governance is executed through an AI-Governed DAO rather than discretionary huma # Backwards Compatibility -This standard does not break ERC-20/721/1155 compatibility. +This standard does not break [**ERC-20**](https://eips.ethereum.org/EIPS/eip-20), [**ERC-721**](https://eips.ethereum.org/EIPS/eip-721), and [**ERC-1155**](https://eips.ethereum.org/EIPS/eip-1155) compatibility. - Legacy tokens may reference metadata externally but lack full ATF-AI compliance - Migration tools can wrap legacy tokens with compliant metadata @@ -185,7 +185,7 @@ This standard does not break ERC-20/721/1155 compatibility. - **Repository**: [agrocrypto-core](https://github.com/AgroCryptoLabs/agrocrypto-core) - **Version**: v2.0.0 -- **Authors**: AgroCrypto Labs LLC +- **Authors**: Leandro Lemos - **License**: CC0-1.0 ### Reference Hashes (for auditability) @@ -201,8 +201,6 @@ f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 Copyright and related rights waived via CC0-1.0. -© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework. - # Changelog All changes to this protocol are treated as compliance-grade events. Each entry is timestamped and hashed for public auditability. @@ -225,8 +223,6 @@ All changes to this protocol are treated as compliance-grade events. Each entry f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 ``` -## [1.0.1] — Planned - **Planned Features** - Integration with AgroPay for ESG token lifecycle tracking - Visual seal registry with cryptographic linkage to metadata @@ -234,15 +230,4 @@ f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 - Optional bridge module for multi-chain deployment - Enhanced JSON-RPC documentation -# Compliance Notes -- All corrections are treated as compliance-grade events -- Hashes are published publicly and timestamped -- No retroactive edits permitted without changelog entry -- All amendments require consensus from ATF-AI governance - ---- - -**© 2023–2025 AgroCrypto Labs LLC — compliance-grade framework** - ---- From d25edfc6f634ff32e673067da8c10364dcc615fa Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Fri, 17 Oct 2025 23:34:32 -0300 Subject: [PATCH 20/53] Update ERCS/erc-8040.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ERCS/erc-8040.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 4ca4f495f81..f32e7d88e6d 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -183,7 +183,7 @@ This standard does not break [**ERC-20**](https://eips.ethereum.org/EIPS/eip-20) # Reference Implementation -- **Repository**: [agrocrypto-core](https://github.com/AgroCryptoLabs/agrocrypto-core) +- **Repository**: [agrocrypto-core](https://github.com/agronetlabs/agrocrypto-core) - **Version**: v2.0.0 - **Authors**: Leandro Lemos - **License**: CC0-1.0 From 32974f277d49821d8f96fe7e2e3b399abec62bad Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Fri, 17 Oct 2025 23:34:42 -0300 Subject: [PATCH 21/53] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 05efbbcd08a..39d669ea927 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,6 @@ Consider any document not published at as a working ## ERC-8040 — ESG Tokenization Protocol -- Release: https://github.com/agronetlabs/ERCs/releases/tag/v1.0.0 +- Reference implementation release (external): https://github.com/agronetlabs/ERCs/releases/tag/v1.0.0 - Discussion (Magicians): https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 - Spec file: ERCS/erc-8040.md From 96843f305cefd137154a527b03fafce76d8c4b00 Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Sat, 18 Oct 2025 00:12:45 -0300 Subject: [PATCH 22/53] =?UTF-8?q?ERC-8040:=20links=20corrigidos=20(relativ?= =?UTF-8?q?os),=20copyright,=20padr=C3=A3o=20EIP-1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ERCS/erc-8040.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index f32e7d88e6d..6d4e3bffa57 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -1,8 +1,8 @@ --- -erc: 8040 +eip: 8040 title: ESG Tokenization Protocol description: AI-native ESG asset tokenization with lifecycle integrity, attestations, audit trail, and PQC readiness. -author: Leandro Lemos (@agronetlabs) +author: Leandro Lemos discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 status: Draft type: Standards Track @@ -127,9 +127,9 @@ event Retired(uint256 indexed tokenId, uint256 timestamp, string reason); ## Mapping & Compatibility -- **ERC-20**: Each unit represents a standardized fraction (e.g., 1e18 = 1 tCO2e). -- **ERC-721**: Single credit with unique esgURI and immutable metadata. -- **ERC-1155**: Homogeneous batch with common URI, metadata, and fungible amounts. +- [**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. # Rationale @@ -153,12 +153,7 @@ Governance is executed through an AI-Governed DAO rather than discretionary huma - Zero-trust validation ensures all attestations are timestamped and verifiable # Backwards Compatibility - -This standard does not break [**ERC-20**](https://eips.ethereum.org/EIPS/eip-20), [**ERC-721**](https://eips.ethereum.org/EIPS/eip-721), and [**ERC-1155**](https://eips.ethereum.org/EIPS/eip-1155) compatibility. - -- Legacy tokens may reference metadata externally but lack full ATF-AI compliance -- Migration tools can wrap legacy tokens with compliant metadata -- Gradual adoption is supported through optional interface implementation +This standard does not break [**ERC-20**](./eip-20.md), [**ERC-721**](./eip-721.md), and [**ERC-1155**](./eip-1155.md) compatibility. # Test Cases @@ -197,16 +192,10 @@ f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 **Timestamp**: 2025-09-06T08:21:00 PDT -# Copyright - -Copyright and related rights waived via CC0-1.0. - # Changelog All changes to this protocol are treated as compliance-grade events. Each entry is timestamped and hashed for public auditability. -## [1.0.0] — 2025-09-06 - **Added** - Initial publication of ERC-8040 ESG Tokenization Protocol - Lifecycle methods: `mintESGToken`, `auditESGToken`, `retireESGToken` @@ -231,3 +220,5 @@ f81783bcda0f70958b05732651fb7ca30a0cef4c3acf0bf45ca4dfa3e7a23645 - Enhanced JSON-RPC documentation +## Copyright +Copyright and related rights waived via [CC0](../LICENSE.md). From 907ea698f5f4b9b001e760e3ec443252de9309ec Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Sat, 18 Oct 2025 00:19:23 -0300 Subject: [PATCH 23/53] Update ERCS/erc-8040.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ERCS/erc-8040.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index 6d4e3bffa57..c87a45bb104 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -13,7 +13,7 @@ requires: 20, 721, 1155 # Abstract -This ERC 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. +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. # Motivation From a97fecf6ccc34e5b3aca8600c1d0f5308cefc4a0 Mon Sep 17 00:00:00 2001 From: AgroNet Labs Date: Sat, 18 Oct 2025 00:19:34 -0300 Subject: [PATCH 24/53] Update ERCS/erc-8040.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ERCS/erc-8040.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index c87a45bb104..2c7e05ddc3a 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -153,7 +153,7 @@ Governance is executed through an AI-Governed DAO rather than discretionary huma - Zero-trust validation ensures all attestations are timestamped and verifiable # Backwards Compatibility -This standard does not break [**ERC-20**](./eip-20.md), [**ERC-721**](./eip-721.md), and [**ERC-1155**](./eip-1155.md) compatibility. +This standard does not break [**ERC-20**](./erc-20.md), [**ERC-721**](./erc-721.md), and [**ERC-1155**](./erc-1155.md) compatibility. # Test Cases From f48076e2418b013ca6178cd42395d418dfa80887 Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Sat, 18 Oct 2025 00:49:33 -0300 Subject: [PATCH 25/53] fix: clean up YAML header, remove duplicates, finalize description --- ERCS/erc-8040.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ERCS/erc-8040.md b/ERCS/erc-8040.md index cdb4bacb2a3..63f4cd2e8f0 100644 --- a/ERCS/erc-8040.md +++ b/ERCS/erc-8040.md @@ -1,10 +1,8 @@ --- eip: 8040 title: ESG Tokenization Protocol -description: AI-native ESG asset tokenization with lifecycle integrity, attestations, audit trail, and PQC readiness. +description: Protocol for tokenizing ESG assets with AI compliance and full auditability. author: Leandro Lemos -description: ESG-compliant, AI-native asset tokenization with quantum auditability and lifecycle integrity. -author: Leandro Lemos (@agronetlabs) discussions-to: https://ethereum-magicians.org/t/erc-8040-esg-tokenization-protocol/25846 status: Draft type: Standards Track From 9e90164a753b81e5b3efafe7946ab50aaa5dbfcf Mon Sep 17 00:00:00 2001 From: Leandro Lemos - AgroNet Labs Date: Sun, 19 Oct 2025 21:41:43 -0300 Subject: [PATCH 26/53] =?UTF-8?q?ERC-8040:=20ESG=20Tokenization=20Protocol?= =?UTF-8?q?=20=E2=80=94=20clean=20commit=20(author=20reaffirmed)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ERCS/erc-2333.md | 45 +-- ERCS/erc-2334.md | 45 ++- ERCS/erc-2335.md | 65 ++-- ERCS/erc-3009.md | 68 ++-- ERCS/erc-601.md | 2 +- ERCS/erc-6123.md | 8 +- ERCS/erc-7730.md | 369 +++++++++++++++++-- ERCS/erc-7828.md | 83 +++-- ERCS/erc-7836.md | 4 +- ERCS/erc-7936.md | 2 +- ERCS/erc-8004.md | 368 ++++++++++++------ ERCS/erc-8040.md | 177 +-------- README.md | 6 - assets/erc-3009/EIP712.sol | 69 ++++ assets/erc-3009/EIP712Domain.sol | 10 + assets/erc-3009/{EIP2612.sol => ERC2612.sol} | 30 +- assets/erc-3009/{EIP3009.sol => ERC3009.sol} | 36 +- assets/erc-3009/IERC20Internal.sol | 33 ++ assets/erc-7730/erc7730-v1.schema.json | 54 ++- assets/erc-7730/example-erc20.json | 1 + assets/erc-7730/example-main.json | 1 + 21 files changed, 924 insertions(+), 552 deletions(-) create mode 100644 assets/erc-3009/EIP712.sol create mode 100644 assets/erc-3009/EIP712Domain.sol rename assets/erc-3009/{EIP2612.sol => ERC2612.sol} (55%) rename assets/erc-3009/{EIP3009.sol => ERC3009.sol} (79%) create mode 100644 assets/erc-3009/IERC20Internal.sol diff --git a/ERCS/erc-2333.md b/ERCS/erc-2333.md index 9df52e9d71b..5ec9968e623 100644 --- a/ERCS/erc-2333.md +++ b/ERCS/erc-2333.md @@ -1,33 +1,26 @@ --- eip: 2333 title: BLS12-381 Key Generation +description: BLS12-381 Key Generation using a hierarchical tree author: Carl Beekhuizen (@CarlBeek) -discussions-to: https://github.com/ethereum/EIPs/issues/2337 -status: Stagnant +discussions-to: https://ethereum-magicians.org/t/bls-keys-related-erc-discussion-erc-2333-2334-2335/19774 +status: Review type: Standards Track category: ERC created: 2019-09-30 --- -## Simple Summary - -This EIP is a method based on a tree structure for deriving BLS private keys from a single source of entropy while providing a post-quantum cryptographic fallback for each key. - ## Abstract This standard is a method for deriving a tree-hierarchy of BLS12-381 keys based on an entropy seed. Starting with the aforementioned seed, a tree of keys is built out using only the parent node's private key and the index of the desired child. This allows for a practically limitless number of keys to be derived for many different purposes while only requiring knowledge of a single ancestor key in the tree. This allows for keys, or families thereof, to be provisioned for different purposes by further standards. In addition to the above, this method of deriving keys provides an emergency backup signature scheme that is resistant to quantum computers for in the event that BLS12-381 is ever deemed insecure. -## A note on purpose - -This specification is designed not only to be an Ethereum 2.0 standard, but one that is adopted by the wider community who have adopted [BLS signatures over BLS12-381](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/). It is therefore important also to consider the needs of the wider industry along with those specific to Ethereum. As a part of these considerations, it is the intention of the author that this standard eventually migrate to a more neutral repository in the future. - ## Motivation ### Deficiencies of the existing mechanism -The curve BLS12-381 used for BLS signatures within Ethereum 2.0 (alongside many other projects) mandates a new key derivation scheme. The most commonly used scheme for key derivation within Ethereum 1.x is [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) (also known as HD derivation) which deems keys greater than the curve order invalid. Based on the order of the private key subgroup of BLS12-381 and the size of the entropy utilised, more than 54% of keys generated by BIP32 would be invalid. (secp256k1 keys derived by BIP32 are invalid with probability less than 1 in 2-127.) +The curve BLS12-381 used for BLS signatures within the Beacon chain (alongside many other projects) mandates a new key derivation scheme. The most commonly used scheme for key derivation within Ethereum for secp256k1 keys is [BIP32](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki) (also known as HD derivation) which deems keys greater than the curve order invalid. Based on the order of the private key subgroup of BLS12-381 and the size of the entropy utilised, more than 54% of keys generated by BIP32 would be invalid. (secp256k1 keys derived by BIP32 are invalid with probability less than 1 in 2-127.) ### Establishing a multi-chain standard early on @@ -78,8 +71,8 @@ Every key generated via the key derivation process derives a child key via a set ##### Definitions -* `HKDF-Extract` is as defined in [RFC5869](https://tools.ietf.org/html/rfc5869), instantiated with SHA256 -* `HKDF-Expand` is as defined in [RFC5869](https://tools.ietf.org/html/rfc5869), instantiated with SHA256 +* `HKDF-Extract` is as defined in [RFC5869](https://www.rfc-editor.org/rfc/rfc5869), instantiated with SHA256 +* `HKDF-Expand` is as defined in [RFC5869](https://www.rfc-editor.org/rfc/rfc5869), instantiated with SHA256 * `K = 32` is the digest size (in octets) of the hash function (SHA256) * `L = K * 255` is the HKDF output size (in octets) * `""` is the empty string @@ -107,7 +100,7 @@ Every key generated via the key derivation process derives a child key via a set ##### Definitions -* `I2OSP` is as defined in [RFC3447](https://ietf.org/rfc/rfc3447.txt) (Big endian decoding) +* `I2OSP` is as defined in [RFC3447](https://www.rfc-editor.org/rfc/rfc3447) (Big endian decoding) * `flip_bits` is a function that returns the bitwise negation of its input * `""` is the empty string * `a | b` is the concatenation of `a` with `b` @@ -150,9 +143,9 @@ Every key generated via the key derivation process derives a child key via a set * `HKDF-Expand` is as defined in RFC5869, instantiated with hash H. * `L` is the integer given by `ceil((3 * ceil(log2(r))) / 16)`.(`L=48`) * `"BLS-SIG-KEYGEN-SALT-"` is an ASCII string comprising 20 octets. -* `OS2IP` is as defined in [RFC3447](https://ietf.org/rfc/rfc3447.txt) (Big endian encoding) -* `I2OSP` is as defined in [RFC3447](https://ietf.org/rfc/rfc3447.txt) (Big endian decoding) -* `r` is the order of the BLS 12-381 curve defined in [the v4 draft IETF BLS signature scheme standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-04) `r=52435875175126190479447740508185965837690552500527637822603658699938581184513` +* `OS2IP` is as defined in [RFC3447](https://www.rfc-editor.org/rfc/rfc3447) (Big endian encoding) +* `I2OSP` is as defined in [RFC3447](https://www.rfc-editor.org/rfc/rfc3447) (Big endian decoding) +* `r` is the order of the BLS 12-381 curve defined in the draft IETF BLS signature scheme standard.`r=52435875175126190479447740508185965837690552500527637822603658699938581184513` ##### Procedure @@ -190,7 +183,7 @@ The child key derivation function takes in the parent's private key and the inde ### `derive_master_SK` -The child key derivation function takes in the parent's private key and the index of the child and returns the child private key. The seed should ideally be derived from a mnemonic, with the intention being that [BIP39 mnemonics](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki), with the associated [mnemonic_to_seed method](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#from-mnemonic-to-seed) be used. +The child key derivation function takes in the parent's private key and the index of the child and returns the child private key. The seed should ideally be derived from a mnemonic, with the intention being that the [BIP-39 mnemonic_to_seed method](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki) be used. ##### Inputs @@ -219,21 +212,21 @@ The Lamport signatures used within this scheme have 255 bits worth of security, ### SHA256 -SHA256 is used as the hash function throughout this standard as it is the hash function chosen by the [IETF BLS signature proposed standard](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/). Using a single hash function for everything decreases the number of cryptographic primitives required to implement the entire BLS standardised key-stack while reducing the surface for flaws in the overall system. +SHA256 is used as the hash function throughout this standard as it is the hash function chosen by the IETF BLS signature proposed standard. Using a single hash function for everything decreases the number of cryptographic primitives required to implement the entire BLS standardised key-stack while reducing the surface for flaws in the overall system. ### `hkdf_mod_r()` -The function `hkdf_mod_r()` in this standard is the same as the `KeyGen` function described in the [proposed standard](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/) and therefore the private key obtained from `KeyGen` is equal to that obtained from `hkdf_mod_r` for the same seed bytes. This means that common engineering can be done when implementing this function. Additionally because of its inclusion in an IETF standard, it has had much scrutiny by many cryptographers and cryptanalysts, thereby lending credence to its safety as a key derivation mechanism. +The function `hkdf_mod_r()` in this standard is the same as the `KeyGen` function described in the draft IETF signature standard and therefore the private key obtained from `KeyGen` is equal to that obtained from `hkdf_mod_r` for the same seed bytes. This means that common engineering can be done when implementing this function. Additionally because of its inclusion in an IETF standard, it has had much scrutiny by many cryptographers and cryptanalysts, thereby lending credence to its safety as a key derivation mechanism. While `hkdf_mod_r()` has modulo bias, the magnitude of this bias is minuscule (the output size of HKDF is set to 48 bytes which is greater 2128 time larger than the curve order). This bias is deemed acceptable in light of the simplicity of the constant time scheme. ### Only using hardened keys -Widely accepted standards that existed before this one ([BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)) utilise the notion of hardened and non-hardened keys whereas this specification only offers the former. Non-hardened keys are primarily useful in a UTXO system in which having one's balance spilt amongst many accounts does not present much additionally complexity, but such keys are much less useful outside of this context. Further complicating matters is the problem of deriving non-hardened keys using a post-quantum signature scheme as non-hardened keys are made possible by the very group arithmetic quantum computers gain an advantage over. +Widely accepted standards that existed before this one ([BIP32](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki)) utilise the notion of hardened and non-hardened keys whereas this specification only offers the former. Non-hardened keys are primarily useful in a UTXO system in which having one's balance spilt amongst many accounts does not present much additionally complexity, but such keys are much less useful outside of this context. Further complicating matters is the problem of deriving non-hardened keys using a post-quantum signature scheme as non-hardened keys are made possible by the very group arithmetic quantum computers gain an advantage over. ## Backwards Compatibility -There are no major backwards compatibility issues brought upon by this EIP as it is not designed for use within Ethereum 1.0 as it currently stands. That said, this standard is not compatible with BIP32/ BIP44 style paths as paths specified by these systems make use of non-hardened keys, something that does not exist within this standard. +There are no major backwards compatibility issues brought upon by this EIP as it is not designed for use with secp256k1 keys. That said, this standard is not compatible with BIP32/ BIP44 style paths as paths specified by these systems make use of non-hardened keys, something that does not exist within this standard. ## Test Cases @@ -246,14 +239,14 @@ child_index = 0 child_SK = 20397789859736650942317412262472558107875392172444076792671091975210932703118 ``` -This test case can be extended to test the entire mnemonic-to-`child_SK` stack, assuming [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated: +This test case can be extended to test the entire mnemonic-to-`child_SK` stack, assuming [BIP39](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki) is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated: ```test mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" passphrase = "TREZOR" ``` -This test case can be extended to test the entire `mnemonic-to -child_SK` stack, assuming [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated: +This test case can be extended to test the entire `mnemonic-to -child_SK` stack, assuming [BIP39](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki) is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated: ```text mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" @@ -807,9 +800,9 @@ compressed_lamport_PK = 0xdd635d27d1d52b9a49df9e5c0c622360a4dd17cba7db4e89bce3cb child_SK = 20397789859736650942317412262472558107875392172444076792671091975210932703118 ``` -## Implementation +## Security Considerations -* [Python](https://github.com/ethereum/eth2.0-deposit-cli) +None. ## Copyright diff --git a/ERCS/erc-2334.md b/ERCS/erc-2334.md index 13b4d448c84..bd0b68239bc 100644 --- a/ERCS/erc-2334.md +++ b/ERCS/erc-2334.md @@ -1,32 +1,25 @@ --- eip: 2334 title: BLS12-381 Deterministic Account Hierarchy +description: BLS12-381 Deterministic account hierarchy structure author: Carl Beekhuizen (@CarlBeek) -discussions-to: https://github.com/ethereum/EIPs/issues/2338 -status: Stagnant +discussions-to: https://ethereum-magicians.org/t/bls-keys-related-erc-discussion-erc-2333-2334-2335/19774 +status: Review type: Standards Track category: ERC created: 2019-09-30 requires: 2333 --- -## Simple Summary - -This EIP defines the purpose of a given key, or family thereof, within a tree of keys. When combined with [EIP-2333](./eip-2333.md), the combination of a seed and knowledge of the desired purpose of a key is sufficient to determine a key pair. - ## Abstract -A standard for allocating keys generated by [EIP-2333](./eip-2333.md) to a specific purpose. It defines a `path` which is a string that parses into the indices to be used when traversing the tree of keys that [EIP-2333](./eip-2333.md) generates. - -## A note on purpose - -This specification is designed not only to be an Ethereum 2.0 standard, but one that is adopted by the wider community who have adopted [BLS signatures over BLS12-381](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/). It is therefore important also to consider the needs of the wider industry along with those specific to Ethereum. As a part of these considerations, it is the intention of the author that this standard eventually migrate to a more neutral repository in the future. +A standard for allocating keys generated by [ERC-2333](./eip-2333.md) to a specific purpose. It defines a `path` which is a string that parses into the indices to be used when traversing the tree of keys that [ERC-2333](./eip-2333.md) generates. ## Motivation -Ethereum 2.0 alongside many other projects will use BLS signatures over BLS12-381, an [IETF proposed standard](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/). This new scheme requires a new key derivation mechanism, which is established within [EIP-2333](./eip-2333.md). This new scheme is incompatible with the current form of this specification ([BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)) due to the: exclusive use of hardened keys, the increased number of keys per level, not using [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) for key derivation. It is therefore necessary to establish a new *path* for traversing the [EIP-2333](./eip-2333.md) key-tree. +The Beacon chain uses BLS signatures over BLS12-381. This new scheme requires a new key derivation mechanism, which is established within [ERC-2333](./eip-2333.md). This new scheme is incompatible with [BIP44](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki) due to the exclusive use of hardened keys, the increased number of keys per level, not using [BIP32](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki) for key derivation. It is therefore necessary to establish a new *path* for traversing the [ERC-2333](./eip-2333.md) key-tree. -The path structure specified in this EIP aims to be more general than [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) by not having UTXO-centric features [which gave rise to the 4 different types of wallet paths being used within Ethereum 1.0](https://github.com/ethereum/EIPs/issues/84#issuecomment-292324521) and gave rise to (draft) [EIP-600](./eip-600.md) & [EIP-601](./eip-601.md) +The path structure specified in this ERC aims to be more general than [BIP44](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki) by not having UTXO-centric features which gave rise to the 4 different types of wallet paths being used within Ethereum in the past and gave rise to (draft) [ERC-600](./eip-600.md) & [ERC-601](./eip-601.md) ## Specification @@ -40,14 +33,14 @@ m / purpose / coin_type / account / use #### Notation -The notation used within the path is specified within the [EIP-2333](./eip-2333.md), but is summarized again below for convenience. +The notation used within the path is specified within the [ERC-2333](./eip-2333.md), but is summarized again below for convenience. * `m` Denotes the master node (or root) of the tree * `/` Separates the tree into depths, thus `i / j` signifies that `j` is a child of `i` ### Purpose -The `purpose` is set to `12381` which is the name of the new curve (BLS12-381). In order to be in compliance with this standard, the [EIP-2333](./eip-2333.md) MUST be implemented as the KDF and therefore, the purpose `12381` MAY NOT be used unless this is the case. +The `purpose` is set to `12381` which is the name of the new curve (BLS12-381). In order to be in compliance with this standard, the [ERC-2333](./eip-2333.md) MUST be implemented as the KDF and therefore, the purpose `12381` MAY NOT be used unless this is the case. ### Coin Type @@ -61,25 +54,25 @@ The `coin_type` here reflects the coin number for an individual coin thereby act This level is designed to provide a set of related keys that can be used for any purpose. The idea being that a single account has many uses which are related yet should remain separate for security reasons. It is required to support this level in the tree, although, for many purposes it will remain `0`. -### Eth2 Specific Parameters +### Beacon Chain Specific Parameters #### Coin type -The coin type used for the BLS12-381 keys in Ethereum 2 is `3600`. +The coin type used for the BLS12-381 keys in Ethereum is `3600`. #### Validator keys -Each Eth2 validator has two keys, one for withdrawals and transfers (called the *withdrawal key*), and the other for performing their duties as a validator (henceforth referred to as the *signing key*). +Each Beacon chain validator has two keys, one for withdrawals and transfers (called the *withdrawal key*), and the other for performing their duties as a validator (henceforth referred to as the *signing key*). The path for withdrawal keys is `m/12381/3600/i/0` where `i` indicates the `i`th set of validator keys. The path for the signing key is `m/12381/3600/i/0/0` where again, `i` indicates the `i`th set of validator keys. Another way of phrasing this is that the signing key is the `0`th child of the associated withdrawal key for that validator. -**Note:** If the above description of key paths is not feasible in a specific use case (eg. with secret-shared or custodial validators), then the affected keys may be omitted and derived via another means. Implementations of this EIP, must endeavour to use the appropriate keys for the given use case to the extent that is reasonably possible. (eg, in the case of custodial staking, the user making the deposits will follow this standard for their withdrawal keys which has no bearing on how the service provide derives the corresponding signing keys.) +**Note:** If the above description of key paths is not feasible in a specific use case (eg. with secret-shared or custodial validators), then the affected keys may be omitted and derived via another means. Implementations of this ERC, must endeavour to use the appropriate keys for the given use case to the extent that is reasonably possible. (eg, in the case of custodial staking, the user making the deposits will follow this standard for their withdrawal keys which has no bearing on how the service provide derives the corresponding signing keys.) ## Rationale -`purpose`, `coin_type`, and `account` are widely-adopted terms as per [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and therefore reusing these terms and their associated meanings makes sense. +`purpose`, `coin_type`, and `account` are widely-adopted terms as per [BIP43](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0043.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki) and therefore reusing these terms and their associated meanings makes sense. The purpose needs to be distinct from these standards as the KDF and path are not inter-compatible and `12381` is an obvious choice. @@ -87,18 +80,22 @@ The purpose needs to be distinct from these standards as the KDF and path are no `use` will commonly be determined at the application level providing distinct keys for non-intersecting use cases. -### Eth2 Specific Parameters +### Beacon Chain Specific Parameters -A new coin type is chosen for Eth2 keys to help ensure a clean separation between Eth2 and Eth1 keys. Although the distinction between Eth1 ETH and Eth2 ETH is subtle, they are distinct entities and there are services which only distinguish between coins by their coin name (eg. [ENS' multichain address resolution](./eip-2304.md)). `3600` is chosen specifically because it is the square of the Eth1's `coin_type` (`3600==60^2`) thereby signaling that it is second instantiation of Ether the currency. +A new coin type is chosen for Beacon Chain BLS keys to help ensure a clean separation between BLS12-381 and secp256k1 keys. `3600` is chosen specifically because it is the square of the Ethereum's secp256k1 `coin_type` (`3600==60^2`). -The primary reason validators have separate signing and withdrawal keys is to allow for the different security concerns of actions within Eth2. The signing key is given to the validator client where it signs messages as per the requirements of being a validator, it is therefore a "hot key". If this key is compromised, the worst that can happen (locally) is that a slashable message is signed, resulting in the validator being slashed and forcibly exited. The withdrawal key is only needed when a validator wishes to perform an action not related to validating and has access to the full funds at stake for that validator. The withdrawal key therefore has higher security concerns and should be handled as a "cold key". By having the signing key be a child of the withdrawal key, secure storage of the withdrawal key is sufficient to recover the signing key should the need arise. +The primary reason validators have separate signing and withdrawal keys is to allow for the different security concerns of actions within the Beacon Chain. The signing key is given to the validator client where it signs messages as per the requirements of being a validator, it is therefore a "hot key". If this key is compromised, the worst that can happen (locally) is that a slashable message is signed, resulting in the validator being slashed and forcibly exited. The withdrawal key is only needed when a validator wishes to perform an action not related to validating and has access to the full funds at stake for that validator. The withdrawal key therefore has higher security concerns and should be handled as a "cold key". By having the signing key be a child of the withdrawal key, secure storage of the withdrawal key is sufficient to recover the signing key should the need arise. ## Backwards Compatibility -[BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) are the commonly used standards for this purpose within Ethereum 1.0, however they have not been `Accepted` as standards as yet. Due to the use of a new KDF within [EIP-2333](./eip-2333.md), a new path standard is required. This EIP implements this, with minor changes. +[BIP43](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0043.mediawiki) and [BIP44](https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki). Due to the use of a new KDF within [ERC-2333](./eip-2333.md), a new path standard is required. This ERC implements this, with minor changes. `purpose` `12381` paths do not support hardened keys and therefore the `'` character is invalid. +## Security Considerations + +None. + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). diff --git a/ERCS/erc-2335.md b/ERCS/erc-2335.md index 8edd8685ad3..ed3a2afc0de 100644 --- a/ERCS/erc-2335.md +++ b/ERCS/erc-2335.md @@ -1,36 +1,29 @@ --- eip: 2335 title: BLS12-381 Keystore +description: Keystore for storing BLS12-381 keys author: Carl Beekhuizen (@CarlBeek) -discussions-to: https://github.com/ethereum/EIPs/issues/2339 -status: Stagnant +discussions-to: https://ethereum-magicians.org/t/bls-keys-related-erc-discussion-erc-2333-2334-2335/19774 +status: Review type: Standards Track category: ERC created: 2019-09-30 requires: 2333, 2334 --- -## Simple Summary - -A JSON format for the storage and interchange of BLS12-381 private keys. - ## Abstract A keystore is a mechanism for storing private keys. It is a JSON file that encrypts a private key and is the standard for interchanging keys between devices as until a user provides their password, their key is safe. -## A note on purpose - -This specification is designed not only to be an Ethereum 2.0 standard, but one that is adopted by the wider community who have adopted the BLS12-381 signature standard. It is therefore important also to consider the needs of the wider industry along with those specific to Ethereum. As a part of these considerations, it is the intention of the author that this standard eventually migrate to a more neutral repository in the future. - ## Motivation The secure storage and exchange of keys is a vital component of the user experience as people are expected to hold their own keys. It allows users to control access to individual keys and their use by applications. -In Ethereum 1, [the Web3 Secret Storage Definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) fulfills these requirements, however it is not perfectly suitable for these purposes moving forward. Specifically the problems with the existing standard are: +In Ethereum, Web3 Secret Storage (commonly referred to as "keystores") fulfills these requirements, however it is not perfectly suitable for these purposes moving forward. Specifically the problems with the existing standard are: -* __The use of Keccak256.__ Eth1 keystores use Keccak for their checksum, a sensible choice considering its usage within Ethereum 1. BLS12-381 [signatures](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00), [keys (EIP-2333)](./eip-2333.md), and key-storage are inter-chain standards, the establishment and proliferation of which hinges on them being neutral to all chains, something which Keccak is not. +* __The use of Keccak256.__ Web3 Secret Stores use Keccak for their checksum. BLS signatures, [keys (ERC-2333)](./eip-2333.md), and key-storage are inter-chain standards, the establishment and proliferation of which hinges on them being neutral to all chains, something which Keccak is not. -* __A lack of abstraction.__ Eth1 keystores are a result of an iterative design process whereby functionality was added and modified as needed without considering how abstractions could simplify the notion of different properties. +* __A lack of abstraction.__ Web3 Secret Stores are a result of an iterative design process whereby functionality was added and modified as needed without considering how abstractions could simplify the notion of different properties. ## Specification @@ -54,10 +47,10 @@ A module is comprised of a `function`, which defines which cryptographic constru The decryption key is an intermediate key which is used both to verify the user-supplied password is correct, as well as for the final secret decryption. This key is simply derived from the password, the `function`, and the `params` specified by the`kdf` module as per the keystore file. -| KDF | `"function"` | `"params"` | `"message"` | Definition | -|----------------|--------------|------------------------------------------------------------------------------------------|-------------|--------------------------------------------------| -| PBKDF2-SHA-256 | `"pbkdf2"` |
  • `"c"`
  • `"dklen"`
  • `"prf: "hmac-sha256"`
  • `"salt"`
| | [RFC 2898](https://www.ietf.org/rfc/rfc2898.txt) | -| scrypt | `"scrypt"` |
  • `"dklen"`
  • `"n"`
  • `"p"`
  • `"r"`
  • `"salt"`
| | [RFC 7914](https://tools.ietf.org/html/rfc7914) | +| KDF | `"function"` | `"params"` | `"message"` | Definition | +|----------------|--------------|------------------------------------------------------------------------------------------|-------------|----------------------------------------------------| +| PBKDF2-SHA-256 | `"pbkdf2"` |
  • `"c"`
  • `"dklen"`
  • `"prf: "hmac-sha256"`
  • `"salt"`
| | [RFC 2898](https://www.rfc-editor.org/rfc/rfc2898) | +| scrypt | `"scrypt"` |
  • `"dklen"`
  • `"n"`
  • `"p"`
  • `"r"`
  • `"salt"`
| | [RFC 7914](https://www.rfc-editor.org/rfc/rfc7914) | ### Password verification @@ -90,7 +83,7 @@ The password verification step verifies that the password is correct with respec | Hash | `"function"` | `"params"` | `"message"` | Definition | |------------|-----------------|------------|-------------|-------------------------------------------------| -| SHA-256 | `"sha256"` | | | [RFC 6234](https://tools.ietf.org/html/rfc6234) | +| SHA-256 | `"sha256"` | | | [RFC 6234](https://www.rfc-editor.org/rfc/rfc6234) | ### Secret decryption @@ -98,29 +91,29 @@ The `cipher.function` encrypts the secret using the decryption key, thus to decr | Cipher | `"function"` | `"params"` | `"message"` | Definition | |----------------------|-----------------|--------------------------|-------------|-------------------------------------------------| -| AES-128 Counter Mode | `"aes-128-ctr"` |
  • `"iv"`
| | [RFC 3686](https://tools.ietf.org/html/rfc3686) | +| AES-128 Counter Mode | `"aes-128-ctr"` |
  • `"iv"`
| | [RFC 3686](https://www.rfc-editor.org/rfc/rfc3686) | -## Description +### Description This field is an optional field to help explain the purpose and identify a particular keystores in a user-friendly manner. While this field can, and should, be used to help distinguish keystores from one-another, the `description` **is not necessarily unique**. -## PubKey +### PubKey -The `pubkey` is the public key associated with the private key secured within the keystore. It is stored here to improve user experience and security which is achieved by not requiring users to enter their password just to obtain their public keys. This field is required if the secret being stored within the keystore is a private key. The encoding of the `pubkey` is specified in the in the appropriate signature standard (eg. [BLS12-381 signature standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00)), but can be seen as a byte-string in the abstract and should be directly compatible with the appropriate signature library. +The `pubkey` is the public key associated with the private key secured within the keystore. It is stored here to improve user experience and security which is achieved by not requiring users to enter their password just to obtain their public keys. This field is required if the secret being stored within the keystore is a private key. The encoding of the `pubkey` is specified in the in the appropriate signature standard (eg. [ERC-2333](./eip-2333.md)), but can be seen as a byte-string in the abstract and should be directly compatible with the appropriate signature library. -## Path +### Path -The `path` indicates where in the key-tree a key originates from. It is a string defined by [EIP-2334](./eip-2334.md), if no path is known or the path is not relevant, the empty string, `""` indicates this. The `path` can specify an arbitrary depth within the tree and the deepest node within the tree indicates the depth of the key stored within this file. +The `path` indicates where in the key-tree a key originates from. It is a string defined by [ERC-2334](./eip-2334.md), if no path is known or the path is not relevant, the empty string, `""` indicates this. The `path` can specify an arbitrary depth within the tree and the deepest node within the tree indicates the depth of the key stored within this file. -## UUID +### UUID -The `uuid` provided in the keystore is a randomly generated UUID as specified by [RFC 4122](https://tools.ietf.org/html/rfc4122). It is used as a 128-bit proxy for referring to a particular set of keys or account. +The `uuid` provided in the keystore is a randomly generated UUID as specified by [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122). It is used as a 128-bit proxy for referring to a particular set of keys or account. -## Version +### Version The `version` is set to `4`. -## JSON schema +### JSON schema The keystore, at its core, is constructed with modules which allow for the configuration of the cryptographic constructions used password hashing, password verification and secret decryption. Each module is composed of: `function`, `params`, and `message` which corresponds with which construction is to be used, what the configuration for the construction is, and what the input is. @@ -193,9 +186,13 @@ The keystore, at its core, is constructed with modules which allow for the confi } ``` +## Security Considerations + +None. + ## Rationale -The rationale behind the design of this specification is largely the same as that behind the [Ethereum 1 keystore definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) except for the lack of support for Keccak (explained in [motivation above](#motivation)) and the notion of modules. +The rationale behind the design of this specification is largely the same as that behind the Ethereum Web3 Secret Storage Definition except for the lack of support for Keccak (explained in [motivation above](#motivation)) and the notion of modules. Modules provide a very useful level of abstraction which allow the Key-Derivation-Function, Checksum, and Cipher to be thought of as instances of the same thing allowing for their substitution with minimal effort. @@ -203,7 +200,7 @@ The `version` is set to 4 to prevent collisions with the existing Ethereum keyst ## Backwards Compatibility -This specification is not backwards compatible with the [existing keystore standard](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) due to the lack of Keccak256 checksums as explained above. While this format is capable of supporting Keccak checksums via the Checksum module, it would defeat the purpose of this standard to include it as this standard could no longer be considered neutral with respect to other projects in the industry. +This specification is not backwards compatible with the Ethereum Web3 Secret Storage Definition due to the lack of Keccak256 checksums as explained above. While this format is capable of supporting Keccak checksums via the Checksum module, it would defeat the purpose of this standard to include it as this standard could no longer be considered neutral with respect to other projects in the industry. ## Test Cases @@ -288,13 +285,9 @@ Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f` } ``` -## Implementation - -Implementations exist in the following languages: +## Security Considerations -* [Python3](https://github.com/ethereum/eth2.0-deposit-cli) -* [TypeScript](https://github.com/nodefactoryio/bls-keystore) -* [Go](https://github.com/wealdtech/go-eth2-wallet-encryptor-keystorev4/) +None. ## Copyright diff --git a/ERCS/erc-3009.md b/ERCS/erc-3009.md index ca68b8f3d42..92af1e2b7ad 100644 --- a/ERCS/erc-3009.md +++ b/ERCS/erc-3009.md @@ -1,19 +1,16 @@ --- eip: 3009 title: Transfer With Authorization +description: Transfer fungible assets via a signed authorization author: Peter Jihoon Kim (@petejkim), Kevin Britz (@kbrizzle), David Knott (@DavidLKnott) -discussions-to: https://github.com/ethereum/EIPs/issues/3010 -status: Stagnant +discussions-to: https://ethereum-magicians.org/t/erc-3009-transfer-with-authorization/25698 +status: Draft type: Standards Track category: ERC created: 2020-09-28 requires: 20, 712 --- -## Simple Summary - -A contract interface that enables transferring of fungible assets via a signed authorization. - ## Abstract A set of functions to enable meta-transactions and atomic interactions with [ERC-20](./eip-20.md) token contracts via signatures conforming to the [EIP-712](./eip-712.md) typed message signing specification. @@ -21,29 +18,38 @@ A set of functions to enable meta-transactions and atomic interactions with [ERC This enables the user to: - delegate the gas payment to someone else, -- pay for gas in the token itself rather than in ETH, +- pay gas in the token itself rather than in ETH, - perform one or more token transfers and other operations in a single atomic transaction, - transfer ERC-20 tokens to another address, and have the recipient submit the transaction, - batch multiple transactions with minimal overhead, and - create and perform multiple transactions without having to worry about them failing due to accidental nonce-reuse or improper ordering by the miner. +Please note that this ERC does not apply to smart contract accounts, as the `transfer` and `approve`/`transferFrom` functions from the ERC-20 standards can directly be used. + + + ## Motivation -There is an existing spec, [EIP-2612](./eip-2612), that also allows meta-transactions, and it is encouraged that a contract implements both for maximum compatibility. The two primary differences between this spec and EIP-2612 are that: +There is an existing spec, [ERC-2612](./eip-2612.md), that also allows meta-transactions, and it is encouraged that a contract implements both for maximum compatibility. The two primary differences between this spec and ERC-2612 are that: -- EIP-2612 uses sequential nonces, but this uses random 32-byte nonces, and that -- EIP-2612 relies on the ERC-20 `approve`/`transferFrom` ("ERC-20 allowance") pattern. +- ERC-2612 uses sequential nonces, but this uses random 32-byte nonces, and that +- ERC-2612 relies on the ERC-20 `approve`/`transferFrom` ("ERC-20 allowance") pattern. -The biggest issue with the use of sequential nonces is that it does not allow users to perform more than one transaction at time without risking their transactions failing, because: +The biggest issue with the use of sequential nonces is that it does not allow users to perform more than one transaction at a time without risking their transactions failing, because: - DApps may unintentionally reuse nonces that have not yet been processed in the blockchain. - Miners may process the transactions in the incorrect order. This can be especially problematic if the gas prices are very high and transactions often get queued up and remain unconfirmed for a long time. Non-sequential nonces allow users to create as many transactions as they want at the same time. -The ERC-20 allowance mechanism is susceptible to the [multiple withdrawal attack](https://blockchain-projects.readthedocs.io/multiple_withdrawal.html)/[SWC-114](https://swcregistry.io/docs/SWC-114), and encourages antipatterns such as the use of the "infinite" allowance. The wide-prevalence of upgradeable contracts have made the conditions favorable for these attacks to happen in the wild. +The ERC-20 allowance mechanism is susceptible to the /, and encourages antipatterns such as the use of the "infinite" allowance. The wide prevalence of upgradeable contracts has made the conditions favorable for these attacks to happen in the wild. -The deficiencies of the ERC-20 allowance pattern brought about the development of alternative token standards such as the [ERC-777](./eip-777) and [ERC-677](https://github.com/ethereum/EIPs/issues/677). However, they haven't been able to gain much adoption due to compatibility and potential security issues. +The deficiencies of the ERC-20 allowance pattern brought about the development of alternative token standards such as the [ERC-777](./eip-777.md) and . However, they haven't been able to gain much adoption due to compatibility and potential security issues. ## Specification @@ -197,7 +203,7 @@ Params := { Authorizer, Nonce } ``` // "‖" denotes concatenation. -Digest := Keecak256( +Digest := Keccak256( 0x1901 ‖ DomainSeparator ‖ Keccak256(ABIEncode(TypeHash, Params...)) ) @@ -294,7 +300,7 @@ One might say transaction ordering is one reason why sequential nonces are prefe - For native Ethereum transactions, when a transaction with a nonce value that is too-high is submitted to the network, it will stay pending until the transactions consuming the lower unused nonces are confirmed. - However, for meta-transactions, when a transaction containing a sequential nonce value that is too high is submitted, instead of staying pending, it will revert and fail immediately, resulting in wasted gas. - The fact that miners can also reorder transactions and include them in the block in the order they want (assuming each transaction was submitted to the network by different meta-transaction relayers) also makes it possible for the meta-transactions to fail even if the nonces used were correct. (e.g. User submits nonces 3, 4 and 5, but miner ends up including them in the block as 4,5,3, resulting in only 3 succeeding) -- Lastly, when using different applications simultaneously, in absence of some sort of an off-chain nonce-tracker, it is not possible to determine what the correct next nonce value is if there exists nonces that are used but haven't been submitted and confirmed by the network. +- Lastly, when using different applications simultaneously, in the absence of some sort of an off-chain nonce tracker, it is not possible to determine what the correct next nonce value is if there exists nonces that are used but haven't been submitted and confirmed by the network. - Under high gas price conditions, transactions can often "get stuck" in the pool for a long time. Under such a situation, it is much more likely for the same nonce to be unintentionally reused twice. For example, if you make a meta-transaction that uses a sequential nonce from one app, and switch to another app to make another meta-transaction before the previous one confirms, the same nonce will be used if the app relies purely on the data available on-chain, resulting in one of the transactions failing. - In conclusion, the only way to guarantee transaction ordering is for relayers to submit transactions one at a time, waiting for confirmation between each submission (and the order in which they should be submitted can be part of some off-chain metadata), rendering sequential nonce irrelevant. @@ -310,9 +316,9 @@ One might say transaction ordering is one reason why sequential nonces are prefe ## Backwards Compatibility -New contracts benefit from being able to directly utilize EIP-3009 in order to create atomic transactions, but existing contracts may still rely on the conventional ERC-20 allowance pattern (`approve`/`transferFrom`). +New contracts benefit from being able to directly utilize [ERC-3009](./eip-3009.md) in order to create atomic transactions, but existing contracts may still rely on the conventional ERC-20 allowance pattern (`approve`/`transferFrom`). -In order to add support for EIP-3009 to existing contracts ("parent contract") that use the ERC-20 allowance pattern, a forwarding contract ("forwarder") can be constructed that takes an authorization and does the following: +In order to add support for ERC-3009 to existing contracts ("parent contract") that use the ERC-20 allowance pattern, a forwarding contract ("forwarder") can be constructed that takes an authorization and does the following: 1. Extract the user and deposit amount from the authorization 2. Call `receiveWithAuthorization` to transfer specified funds from the user to the forwarder @@ -372,7 +378,7 @@ contract DepositForwarder { "Failed to transfer the minted tokens" ); - uint256 remainder = _token.balanceOf(address(this); + uint256 remainder = _token.balanceOf(address(this)); if (remainder > 0) { require( _token.transfer(from, remainder), @@ -385,13 +391,16 @@ contract DepositForwarder { } ``` + + +## Reference Implementation -## Implementation +### `EIP3009.sol` -**EIP3009.sol** ```solidity abstract contract EIP3009 is IERC20Transfer, EIP712Domain { // keccak256("TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)") @@ -454,7 +463,8 @@ abstract contract EIP3009 is IERC20Transfer, EIP712Domain { } ``` -**IERC20Transfer.sol** +### `IERC20Transfer.sol` + ```solidity abstract contract IERC20Transfer { function _transfer( @@ -465,14 +475,16 @@ abstract contract IERC20Transfer { } ``` -**EIP712Domain.sol** +### `EIP712Domain.sol` + ```solidity abstract contract EIP712Domain { bytes32 public DOMAIN_SEPARATOR; } ``` -**EIP712.sol** +### `EIP712.sol` + ```solidity library EIP712 { // keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)") @@ -494,8 +506,8 @@ library EIP712 { EIP712_DOMAIN_TYPEHASH, keccak256(bytes(name)), keccak256(bytes(version)), - address(this), - bytes32(chainId) + chainId, + address(this) ) ); } @@ -521,15 +533,15 @@ library EIP712 { } ``` -A fully working implementation of EIP-3009 can be found in [this repository](../assets/eip-3009/EIP3009.sol). The repository also includes [an implementation of EIP-2612](../assets/eip-3009/EIP2612.sol) that uses the EIP-712 library code presented above. +A fully working implementation of ERC-3009 can be found in [this repository](../assets/eip-3009/ERC3009.sol). The repository also includes [an implementation of ERC-2612](../assets/eip-3009/ERC2612.sol) that uses the EIP-712 library code presented above. ## Security Considerations -Use `receiveWithAuthorization` instead of `transferWithAuthorization` when calling from other smart contracts. It is possible for an attacker watching the transaction pool to extract the transfer authorization and front-run the `transferWithAuthorization` call to execute the transfer without invoking the wrapper function. This could potentially result in unprocessed, locked up deposits. `receiveWithAuthorization` prevents this by performing an additional check that ensures that the caller is the payee. Additionally, if there are multiple contract functions accepting receive authorizations, the app developer could dedicate some leading bytes of the nonce could as the identifier to prevent cross-use. +Use `receiveWithAuthorization` instead of `transferWithAuthorization` when calling from other smart contracts. It is possible for an attacker watching the transaction pool to extract the transfer authorization and front-run the `transferWithAuthorization` call to execute the transfer without invoking the wrapper function. This could potentially result in unprocessed, locked up deposits. `receiveWithAuthorization` prevents this by performing an additional check that ensures that the caller is the payee. Additionally, if there are multiple contract functions accepting receive authorizations, the app developer could dedicate some leading bytes of the nonce as an identifier to prevent cross-use. When submitting multiple transfers simultaneously, be mindful of the fact that relayers and miners will decide the order in which they are processed. This is generally not a problem if the transactions are not dependent on each other, but for transactions that are highly dependent on each other, it is recommended that the signed authorizations are submitted one at a time. -The zero address must be rejected when using `ecrecover` to prevent unauthorized transfers and approvals of funds from the zero address. The built-in `ecrecover` returns the zero address when a malformed signature is provided. +The zero address must be rejected when `ecrecover` is used to prevent unauthorized transfers and approvals of funds from the zero address. The built-in `ecrecover` returns the zero address when a malformed signature is provided. ## Copyright diff --git a/ERCS/erc-601.md b/ERCS/erc-601.md index 50504640ce3..19c5d811a8d 100644 --- a/ERCS/erc-601.md +++ b/ERCS/erc-601.md @@ -19,7 +19,7 @@ At present, different Ethereum clients and wallets use different derivation path Further, BIP44 was designed with UTXO-based blockchains in mind, and is a poor fit for Ethereum, which uses an accounts abstraction instead. -As an alternative, we propose a deterministic wallet hierarchy better tailored to Ethereum's unique requiremnts. +As an alternative, we propose a deterministic wallet hierarchy better tailored to Ethereum's unique requirements. ## Specification We define the following 4 levels in BIP32 path: diff --git a/ERCS/erc-6123.md b/ERCS/erc-6123.md index 605349fc3fe..5fb68e23396 100644 --- a/ERCS/erc-6123.md +++ b/ERCS/erc-6123.md @@ -107,7 +107,7 @@ function cancelTrade(address withParty, string memory tradeData, int position, i #### Trade Termination: `requestTermination` -Allows an eligible party to request a mutual termination of the trade with the correspondig `tradeId` with a termination amount she is willing to pay and provide further termination terms (e.g. an XML) +Allows an eligible party to request a mutual termination of the trade with the corresponding `tradeId` with a termination amount she is willing to pay and provide further termination terms (e.g. an XML) ```solidity function requestTradeTermination(string memory tradeId, int256 terminationPayment, string memory terminationTerms) external; @@ -182,7 +182,7 @@ function afterSettlement() external; #### Settlement Phase: `afterTransfer` -This method is called back from a settlement token or from an eligible address if the transfer of the settlment +This method is called back from a settlement token or from an eligible address if the transfer of the settlement amount was successful. - completes the settlement transfer. The transactionData is emitted as part of the corresponding event: `SettlementTransferred` or `SettlementFailed` This might result in a termination or start of the next settlement phase, depending on the provided success flag. @@ -270,7 +270,7 @@ Emitted when a settlement is requested (via `initiateSettlement`). May trigger t The argument `lastSettlementData` is the one that was passed upon a previous settlement in `performSettlement` (under the name `settlementData`). It may be used to pass updated settlement -specific information calcualted during the previous settlement, e.g., when margin buffer amounts are a function +specific information calculated during the previous settlement, e.g., when margin buffer amounts are a function of market parameters. In case of an external oracle it can pass the `settlementData` via `performSettlement` and pick it up in the `SettlementRequested` event (allows for stateless external oracles). @@ -408,4 +408,4 @@ Copyright and related rights waived via [CC0](../LICENSE.md). "language": "en", "source": "SSRN" } -``` \ No newline at end of file +``` diff --git a/ERCS/erc-7730.md b/ERCS/erc-7730.md index db214630aec..6fea82d3901 100644 --- a/ERCS/erc-7730.md +++ b/ERCS/erc-7730.md @@ -2,7 +2,7 @@ eip: 7730 title: Structured Data Clear Signing Format description: JSON format describing how to clear-sign smart contract calls and typed messages. -author: Laurent Castillo (@lcastillo-ledger) +author: Laurent Castillo (@lcastillo-ledger), Derek Rein (@arein), Pierre Aoun (@paoun-ledger), Arik Galansky (@arikg) discussions-to: https://ethereum-magicians.org/t/eip-7730-proposal-for-a-clear-signing-standard-format-for-wallets/20403 status: Draft type: Standards Track @@ -13,13 +13,13 @@ requires: 155, 712 ## Abstract -This specification defines a JSON format carrying additional information required to correctly display structured data to a human for review on a wallet screen, before signature by the wallet. +This specification defines a JSON format carrying additional information required to correctly display structured data for human verification on wallet screens or for machine consumption e.g. by transaction simulation engines. -The [ERC-7730](./eip-7730.md) specification enriches type data contained in the ABIs and schemas of structured messages (structures like the calldata of an EVM transaction or an [EIP-712](./eip-712.md) message) with additional formatting information, so that wallets can construct a better UI when displaying the data before signature. For instance, a solidity field containing an amount, encoded as an uint256, can be converted to the right magnitude and appended with the correct ticker. +The [ERC-7730](./eip-7730.md) specification enriches type data contained in the ABIs and schemas of structured messages (structures like the calldata of an EVM transaction or an [EIP-712](./eip-712.md) message) with additional formatting information and dynamic value interpolation, enabling both human-readable display with contextual intent descriptions and machine-interpretable data processing. For instance, a solidity field containing an amount, encoded as an uint256, can be converted to the right magnitude and appended with the correct ticker for display, or parsed programmatically for transaction simulation. -Wallets will use (wallet-curated) ERC-7730 files alongside the raw data to sign in order to construct a display adapted to be reviewed by humans. +Wallets and automated systems will use curated ERC-7730 files alongside the raw data to sign in order to construct appropriate interfaces for their respective use cases. -At the time of writing (version 1 of this specification), the only structured data supported are smart contract calls (aka calldata) in EVM transactions and EIP-712 structured messages. +This enables significantly improved signing user experiences and lower end-user risk from frontend and phishing attacks. ## Motivation @@ -31,7 +31,7 @@ Properly validating a transaction on a hardware wallet's screen (also known as C This specification intends to provide a simple, open standard format to provide wallets with the additional information required to properly format a structured data to sign for review by users. -Providing this additional formatting information requires deep knowledge of the way a smart contract or message is going to be used. It is expected that DApp developers will be the best placed to write such a file. The intent of an open standard is to only write this file once and have it work with most wallets supporting this standard. +Providing this additional formatting information requires deep knowledge of the way a smart contract or message is going to be used. It is expected that app developers will be the best placed to write such a file. The intent of an open standard is to only write this file once and have it work with most wallets supporting this standard. ## Specification @@ -80,6 +80,7 @@ The following is an example of how to clear sign a `transfer` function call on a "formats": { "transfer(address _to,uint256 _value)": { "intent": "Send", + "interpolatedIntent": "Send {_value} to {_to}", "fields": [ { "path": "_to", @@ -202,6 +203,152 @@ References to values in the container (here an EVM Tx container) * `@.value` refers to the enclosing transaction native currency amount * `@.to` refers to the enclosing transaction destination address (usually, a smart contract bound to this ERC-7730 through the `context` section) +#### Value Interpolation + +The `interpolatedIntent` field supports embedding formatted field values directly within intent strings using interpolation syntax. This allows constructing dynamic, context-aware descriptions of transactions and messages. + +The `interpolatedIntent` makes transaction intents significantly shorter and easier to read by presenting all relevant information in a single, natural language sentence rather than as separate labeled fields. This is particularly valuable for: +- Reducing the cognitive load on users reviewing transactions +- Displaying concise summaries on resource-constrained devices +- Enabling clear descriptions of batch transactions (e.g., [EIP-5792](./eip-5792.md)), where multiple operations can be concatenated into a single readable sentence + +**Interpolation Syntax** + +Values are interpolated using curly braces containing a path reference: `{path}`. The path MUST follow the [path reference rules](#path-references) and can reference: +- Structured data fields (e.g., `{_to}`, `{params.amountIn}`) +- Container values (e.g., `{@.value}`, `{@.from}`) +- Metadata constants (e.g., `{$.metadata.constants.nativeAssetAddress}`) + +**Formatting Behavior** + +When a wallet processes an `interpolatedIntent`: +1. The wallet MUST identify all interpolation expressions `{path}` in the string +2. For each expression, the wallet MUST resolve the path and locate the corresponding field format specification in the `fields` array +3. The wallet MUST apply the field's `format` and `params` to format the value +4. The wallet MUST replace the interpolation expression with the formatted value +5. If any interpolation fails (path not found, formatting error, etc.), the wallet MUST fall back to displaying the regular `intent` field + +**Escaping** + +To include literal curly braces in the intent text, escape them by doubling: `{{` for `{` and `}}` for `}`. + +**Examples** + +*Simple token transfer:* +```json +{ + "intent": "Send", + "interpolatedIntent": "Send {_value} to {_to}", + "fields": [ + {"path": "_to", "format": "addressName"}, + {"path": "_value", "format": "tokenAmount", "params": {"tokenPath": "@.to"}} + ] +} +``` +Displays as: **"Send 100 USDT to cyberdrk.eth"** + +*Swap with native currency:* +```json +{ + "intent": "Swap", + "interpolatedIntent": "Swap {amountIn} for at least {amountOutMinimum}", + "fields": [ + {"path": "amountIn", "format": "tokenAmount", "params": {"tokenPath": "tokenIn"}}, + {"path": "amountOutMinimum", "format": "tokenAmount", "params": {"tokenPath": "tokenOut"}} + ] +} +``` +Displays as: **"Swap 1000 USDC for at least 0.25 WETH"** + +*Using container values:* +```json +{ + "intent": "Wrap ETH", + "interpolatedIntent": "Wrap {@.value} ETH for WETH", + "fields": [ + {"path": "@.value", "format": "amount"} + ] +} +``` +Displays as: **"Wrap 0.5 ETH for WETH"** + +*Escaping literal braces:* +```json +{ + "interpolatedIntent": "Execute {{function}} with {amount} tokens" +} +``` +Displays as: **"Execute {function} with 100 tokens"** + +**Batch Transactions (EIP-5792)** + +When displaying batch transactions as defined in [EIP-5792](./eip-5792.md), wallets SHOULD concatenate the `interpolatedIntent` strings of individual operations using " and " as a separator to create a single, human-readable description of the entire batch. + +This approach provides users with a clear, natural language summary of complex multi-step operations without requiring them to mentally piece together separate transaction descriptions. + +*Permit + Swap example:* +```json +[ + { + "function": "permit", + "interpolatedIntent": "Approve {spender} to spend {value} USDC" + }, + { + "function": "swapExactTokensForTokens", + "interpolatedIntent": "Swap {amountIn} for at least {amountOutMin}" + } +] +``` +Combined display: **"Approve Uniswap Router to spend 1000 USDC and Swap 1000 USDC for at least 0.25 WETH"** + +*Approve + Swap example:* +```json +[ + { + "function": "approve", + "interpolatedIntent": "Approve {_spender} to spend {_value}" + }, + { + "function": "exactInputSingle", + "interpolatedIntent": "Swap {amountIn} for at least {amountOutMinimum}" + } +] +``` +Combined display: **"Approve Uniswap V3 Router to spend 5000 DAI and Swap 5000 DAI for at least 1.2 ETH"** + +*Approve + Swap + Mint NFT example:* +```json +[ + { + "function": "approve", + "interpolatedIntent": "Approve {_spender} to spend {_value}" + }, + { + "function": "swapExactTokensForETH", + "interpolatedIntent": "Swap {amountIn} for at least {amountOutMin} ETH" + }, + { + "function": "mint", + "interpolatedIntent": "Mint {quantity} NFT(s) from {collection}" + } +] +``` +Combined display: **"Approve DEX Router to spend 2000 USDC and Swap 2000 USDC for at least 0.5 ETH and Mint 2 NFT(s) from BoredApeYachtClub"** + +**Implementation Guidance for Batch Transactions** + +Wallets implementing batch transaction display SHOULD: +1. Process each transaction in the batch to generate its `interpolatedIntent` +2. Join the resulting intent strings with " and " (note the spaces) +3. Display the combined string as a single transaction summary +4. Provide a way for users to view individual transaction details if needed +5. Fall back to displaying individual `intent` fields if any `interpolatedIntent` processing fails + +Wallets MAY: +- Apply additional formatting (e.g., capitalizing the first letter, adding a period at the end) +- Truncate very long combined intents and provide expansion UI +- Group related operations visually while still showing the combined intent + #### Organizing files Smart contracts and EIP-712 messages are often re-using common interfaces or types that share similar display formatting. This specification supports a basic inclusion mechanism that enables sharing files describing specific interfaces or types. @@ -580,6 +727,7 @@ It also shows how to describe a more dynamic enumeration, like a list of possibl "repay(address asset, uint256 amount, uint256 interestRateMode)": { "$id": "repay", "intent": "Repay loan", + "interpolatedIntent": "Repay {amount} of {interestRateMode} rate loan", "fields": [ { "path": "amount", @@ -678,6 +826,38 @@ Wallets SHOULD use this `intent` value to display a clear intent when reviewing ``` This snippet defines an intent for a withdrawal function on a contract, with an expectation that the intent would be displayed in a structured way on the wallet screen. +**`interpolatedIntent`** + +A string containing an intent description with embedded field values using [interpolation syntax](#value-interpolation). + +The `interpolatedIntent` provides a more dynamic, contextual description than the static `intent` field by embedding actual transaction/message values directly in the intent string. This is particularly useful for: +- Displaying concise, single-line transaction summaries +- Improving UX on devices with limited screen space +- Reducing cognitive load by presenting values in natural language context + +When both `intent` and `interpolatedIntent` are present: +- Wallets SHOULD prefer displaying `interpolatedIntent` when interpolation is successfully processed +- Wallets MUST fall back to `intent` if interpolation fails for any reason +- Wallets MAY display both fields, with `interpolatedIntent` as the primary description + +Interpolated paths MUST reference fields that have corresponding format specifications in the `fields` array. The formatting applied during interpolation MUST match the formatting that would be applied if the field were displayed separately. + +*Example with complex intent:* +```json +{ + "intent": { + "Action": "Approve", + "Type": "Batch" + }, + "interpolatedIntent": "Approve {spender} to spend up to {amount} on your behalf until {deadline}", + "fields": [ + {"path": "spender", "label": "Spender", "format": "addressName"}, + {"path": "amount", "label": "Amount", "format": "tokenAmount", "params": {"tokenPath": "@.to"}}, + {"path": "deadline", "label": "Deadline", "format": "date", "params": {"encoding": "timestamp"}} + ] +} +``` + **`fields`** The `fields` key defines formatting information for individual fields of the structured data (function or message). @@ -851,6 +1031,8 @@ This examples uses an array slice to indicate that only the last element of the "display": { "formats": { "PermitBatch": { + "intent": "Approve token spending", + "interpolatedIntent": "Approve {spender} to spend multiple tokens until {sigDeadline}", "fields": [ { "path": "details.[]", @@ -872,6 +1054,19 @@ This examples uses an array slice to indicate that only the last element of the } } ] + }, + { + "path": "spender", + "label": "Spender", + "format": "addressName" + }, + { + "path": "sigDeadline", + "label": "Signature Deadline", + "format": "date", + "params": { + "encoding": "timestamp" + } } ] } @@ -881,6 +1076,71 @@ This examples uses an array slice to indicate that only the last element of the ``` This example uses a full array selector `details.[]` to apply the list of the underlying two underlying formats to ALL the elements of the `details` array. +#### Embedded Calldata + +Embedded calldata is used when a parameter of a smart contract function contains the calldata for another function call to a smart contract. +This pattern is common in contract interactions where one function call triggers another function call as part of its execution. +For example, the `permitAndCall` function verifies a permit and then executes another function within the same contract using the provided embedded calldata. +Here is an example of how to format embedded calldata:" + +```json +{ + "display": { + "formats": { + "permitAndCall(bytes permit, bytes action)": { + "intent": "Execute with permit", + "fields": [ + { + "path": "action", + "label": "Swap", + "format": "calldata", + "params": { + "calleePath": "@.to", + } + } + ], + "required": ["action"], + "excluded": ["permit"] + } + } + } +} +``` + +In this example, the `permitAndCall` function accepts two parameters: `permit` and `action`. +The `action` parameter contains the calldata for a subsequent function call. +The `format` field is set to `calldata`, instructing the wallet to interpret the action parameter as embedded calldata. +The `calleePath` parameter defines the path to the address of the target contract, while the optional `selector` parameter specifies the function selector if it is not the first 4 bytes of the calldata. +When displaying the transaction, the wallet will attempt to resolve an ERC-7730 descriptor for the embedded calldata using the callee address and the selector. +In some cases, embedded calldata may require a transaction value and/or a spender to be properly clear-signed, as the underlying function might rely on a value passed from the parent transaction (e.g., for swaps or staking). +To handle this, the `amountPath` and/or `spenderPath` parameters can be used to specify these values explicitly. + +```json +{ + "display": { + "formats": { + "permitAndCall(bytes permit, address target, bytes action)": { + "intent": "Execute with permit", + "fields": [ + { + "path": "action", + "label": "Swap", + "format": "calldata", + "params": { + "calleePath": "target", + "amountPath": "@.value", + "spenderPath": "@.to" + } + } + ], + "required": ["action", "target"], + "excluded": ["permit"] + } + } + } +} +``` + ### Reference ### Container structure values @@ -1015,13 +1275,16 @@ Formats usable for bytes | `123456789A` | Field Value = Value ['12','34','56','78','9a'] | --- -| **`calldata`** | | -|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| *Description* | Data contains a call to another smart contract. To look for relevant ERC-7730 files matching this embedded calldata, use `callee` parameter and `selector`. If an ERC-7730 is not found or if embedded calldata are not supported by the wallet, it MAY display a hash of the embedded calldata instead, with target `calleePath` resolved to a trusted name if possible. | -| *Parameters* | --- | -| `selector` | Optional selector, if not present the first 4 bytes of the calldata are interpreted as the selector | -| `calleePath` or `callee` | A path reference or constant value for the contract being called | -| *Examples* | | +| **`calldata`** | | +|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| *Description* | Contains a call to another smart contract or to another function within the same contract. To resolve an ERC-7730 descriptor for this embedded calldata, use the `callee` and `selector` parameters. If no matching ERC-7730 descriptor is found or if tha wallet does not support embedded calldata, it MAY display a hash of the embedded calldata instead, with target `calleePath` resolved to a trusted name if possible. | +| *Parameters* | --- | +| `calleePath` or `callee` | A path reference or a constant value specifying the address of the contract being called. | +| `selectorPath` or `selector`| Optional. If omitted, the first 4 bytes of the calldata are used as the selector. | +| `chainIdPath` or `chainId` | Optional. Specifies the chain ID if it differs from the current contract’s chain. | +| `amountPath` or `amount` | Optional. Specifies the native currency amount associated with the calldata, if applicable. If provided, the ERC-7730 descriptor for this embedded calldata MAY reference this value using the `@.value` container path. | +| `spenderPath` or `spender` | Optional. Specifies the spender address associated with the calldata, if applicable. If provided, the ERC-7730 descriptor for this embedded calldata MAY reference this value using the `@.from` container path. | +| *Examples* | | #### Address @@ -1084,7 +1347,7 @@ Wallets MAY extend the specification with wallet specific layout instructions by It is expected that the main limitation to adoption of ERC-7730 will be the complexity of writing this interface description file compared to interest of writing it. This drove a few choices when introducing this ERC specification: -* The form of an ERC itself will allow usage of these file by any wallets (Hardware or Software, without restrictions), and in turn drive up the benefits for dApps developers to provide their own ERC-7730 description +* The form of an ERC itself will allow usage of these file by any wallets (Hardware or Software, without restrictions), and in turn drive up the benefits for app developers to provide their own ERC-7730 description * The specification is intended to be directly readable by developers, in order to facilitate direct edition by developers. * In addition, a set of edition tools will be created and open sourced to ease visualization of the results for end users @@ -1103,16 +1366,11 @@ This consideration is driving a few choices done for ERC-7730: The full signature of a function call does not contain information about the types of complex parameters that might be used in the function call, only their names, while the ABI does carry this information. This is why the ABI is the reference and the function signature MUST match it. The full form of the function call is allowed in order to simplify writing and reading the ERC-7730 file. -### Deployment model - -Making the ERC-7730 available for wallets is a key factor of adoption. We have a few options: -- In each dApps GitHub repository or website: good for autonomy but can be problematic for discoverability by wallets of new ERC-7730 files -- Foundation operated repository, like ethereum chainID list: good alternative between decentralization and discoverability. -- Ledger repository: as a short term solution, Ledger is providing a central repository (See Ledger GitHub repository) - ### Extensibility to other Structured Data formats -In the future, this specification could be extended to structured data like Meta Transaction in [EIP-2771](./eip-2771.md) or User Operations in [EIP-4337](./eip-4337.md). +In the future, this specification could be extended to structured data like Meta Transaction in [EIP-2771](./eip-2771.md), User Operations in [EIP-4337](./eip-4337.md), and batch transaction payloads in [EIP-5792](./eip-5792.md). + +The `interpolatedIntent` field is particularly well-suited for [EIP-5792](./eip-5792.md) batch transactions, as it enables wallets to concatenate multiple operation descriptions into a single, natural language sentence. By joining individual `interpolatedIntent` strings with " and ", wallets can provide users with clear, readable summaries of complex multi-step operations like "Approve Uniswap Router to spend 1000 USDC and Swap 1000 USDC for at least 0.25 WETH". This significantly improves the user experience when reviewing batch transactions compared to displaying separate, disconnected operation descriptions. See the [Value Interpolation](#value-interpolation) section for detailed implementation guidance and examples. ## Test Cases @@ -1120,29 +1378,70 @@ More examples can be found in the asset folder [here](../assets/eip-7730/example ## Security Considerations -The main security concern introduced by ERC-7730 is to avoid attacks that would use the ERC-7730 formatting mechanism to trick users into signing something wrong. - -Two main attack vectors that needs to be mitigated: -* Avoid using a well-formed, trusted ERC-7730 file on data that should not be formatted using it -* Avoid badly formed, incorrect ERC-7730 files that would hide critical parameters or create misinterpretations through bed formatting +ERC-7730 creates a risk surface where malicious actors could abuse formatting to make unsafe transactions appear benign. In addition to misapplied or malformed files, implementers should anticipate phishing techniques such as (a) parameter injection using legitimate, high-profile contract formats, (b) registry poisoning with well-formed but misleading entries, and (c) front-end/CDN compromise that prompts signatures for unexpected contracts or parameters. ### Binding context -The binding `context` is the way we mitigate the first attack, by specifying in the ERC-7730 file itself, **what kind** of structured data should be formatted by said file. +The binding `context` mitigates misuse by specifying exactly which structured data a given ERC-7730 file may format. app developers MUST set restrictive constraints; wallets MUST verify all constraints and ensure formatting is cryptographically bound to the reviewed data and not tamperable in transit (including on resource-constrained hardware wallets). + +### Registry Poisoning + +Curation and registry of ERC-7730 files are out of scope for this specification, but any external registry or wallet ecosystem MUST assume it will be targeted. A secure registry should (a) require cryptographically verifiable provenance and attestations for each ERC-7730 file and its maintainer, (b) keep a public, tamper-evident history of submissions, approvals, and revocations, (c) implement a mechanism to credibly link contract ownership or authority to the submitted file, and (d) adopt a clear governance model with multi-party sign-off and automated monitoring to detect anomalies or mass poisoning attempts. These measures mitigate attacks on ERC-7730 files in transit and make registry compromise significantly harder without constraining this ERC itself. + +### Interpolated Intent Security + +The `interpolatedIntent` feature introduces additional attack surfaces that wallets MUST mitigate: + +**Injection Attacks** + +Malicious contracts could craft parameter values that, when interpolated, create misleading intent descriptions. For example: +- A token name containing "to vitalik.eth" could make "Send {amount} to {recipient}" appear as "Send 100 USDT to vitalik.eth to 0x123..." +- Addresses with misleading ENS names could obscure the true destination +- Very long formatted values could push critical information off-screen + +*Mitigations:* +- Wallets MUST apply the same formatting and validation to interpolated values as they would for separately displayed fields +- Wallets MUST validate that ENS names and other address labels are verified before interpolation +- Wallets SHOULD display field values separately in addition to the interpolated intent, or provide easy access to detailed field view + +**Format Consistency** + +Wallets MUST ensure that the formatting applied during interpolation exactly matches the formatting that would be applied if the field were displayed separately. This prevents attackers from exploiting differences in formatting to hide malicious values. + +*Implementation requirement:* +- The interpolation engine MUST use the same formatter functions and parameters specified in the corresponding field format specification +- If a path in `interpolatedIntent` does not have a corresponding field format specification, interpolation MUST fail and fall back to `intent` + +**Path Validation** + +Wallets MUST validate that all paths in interpolation expressions: +1. Follow the [path reference rules](#path-references) +2. Reference fields that exist in the structured data being signed +3. Have corresponding field format specifications in the `fields` array +4. Do not create circular references or unbounded recursion + +**Fallback Behavior** -dApps developers must make sure that constraints in the binding context are restrictive enough to apply only to relevant data. +If interpolation fails for any reason (invalid path, formatting error, missing field specification, validation failure), wallets MUST: +1. Fall back to displaying the static `intent` field +2. Display all fields separately according to their field format specifications +3. NOT attempt to partially process the interpolated intent +4. Optionally warn the user that the dynamic description could not be generated -Wallets must ensure that all constraints are met before formatting any data for review by the end user. +**Resource Constraints** -It is also expected that the way the formatting is applied to the data is not vulnerable to MITM or tampering attack from an attacker in control of communication means. Constraints have been design simple, so that a strong cryptographic binding to the data can be created even on resource constrained Hardware Wallets. +Hardware wallets and other resource-constrained devices MAY choose not to implement `interpolatedIntent` support. The `intent` field MUST always be present as a fallback for such devices. -### Curation model +**Testing and Validation** -The second attack is not directly mitigated by the specification (beyond providing recommendations). It is rather expected that wallets will use a two-step curation process, and NOT trust ERC-7730 files coming directly from the public repository. +ERC-7730 file authors SHOULD test `interpolatedIntent` strings with: +- Minimum and maximum expected values for each interpolated field +- Edge cases like zero amounts, maximum allowances, expired dates +- Long addresses, token names, and other string fields to ensure proper truncation -Rather wallets SHOULD do some additional verifications on the ERC-7730 file itself and corresponding dApps before trusting the file to build their user's UI. +Future Work -![Curation Model](../assets/eip-7730/curation-model.svg) +Future improvements could bind frontends to verified contract manifests so that a compromised UI cannot silently substitute a different contract. Clear, auditable registry governance (multi-party signoff, monitoring, and revocation) can further raise the cost of phishing, parameter injection, and front-end compromise attacks. ## Copyright diff --git a/ERCS/erc-7828.md b/ERCS/erc-7828.md index fbdabe39796..04c2fcb975b 100644 --- a/ERCS/erc-7828.md +++ b/ERCS/erc-7828.md @@ -4,7 +4,7 @@ title: Readable Interoperable Addresses using ENS description: An iteration of Interoperable Address' format that allows resolution to shorter, hierarchical strings using naming registries author: Sam Kaufman (@SampkaML), Marco Stronati (@paracetamolo), Yuliya Alexiev (@yuliyaalexiev), Jeff Lau (@jefflau), Sam Wilson (@samwilsn), Vitalik Buterin (@vbuterin), Teddy (@0xteddybear), Joxes (@Joxess), Racu (@0xRacoon), Skeletor Spaceman (@0xskeletor-spaceman), TiTi (@0xtiti), Gori (@0xGorilla), Ardy (@0xArdy), Onizuka (@onizuka-wl), Lumi (@oxlumi), Moebius (@0xmoebius) discussions-to: https://ethereum-magicians.org/t/erc-7828-chain-specific-addresses-using-ens/21930 -status: Draft +status: Review type: Standards Track category: ERC created: 2024-11-27 @@ -13,32 +13,31 @@ requires: 155, 7930 ## Abstract -This proposal extends [ERC-7930](./eip-7930.md) (Interoperable Addresses & Names) by standardizing a human-readable format for chain-specific addresses in the form `
@#`. It introduces: +This proposal extends [ERC-7930] \(Interoperable Addresses & Names\) by standardizing a human-readable format for chain-specific addresses in the form `
@#`. It introduces: - A unified format for accounts that specifies, together with the address, the chain where the address lives. - The use of human-readable chain names, with resolution to chain identifiers via ENS. - The use of human-readable account names, with resolution to addresses via ENS. -- An on-chain registry mapping chain names to identifiers, enabling decentralized resolution of chain metadata. +- An on-chain registry mapping chain names to identifiers, enabling decentralized resolution of chain metadata. - The ENS domain suffix used for chain names SHALL be abstracted from users for readability, ensuring a simpler display format. ## Motivation -The current Ethereum address landscape is leading to an ecosystem that will have hundreds and eventually thousands of L2s that use the same address format as Ethereum mainnet. This means an address by itself is not enough information to know which chain the address is related to. This can be problematic if funds are sent to an unreachable address on the incorrect chain. From the user account it should be possible to obtain the right chain identifier (chainID) to include in a transaction. +The current Ethereum address landscape is leading to an ecosystem that will have hundreds and eventually thousands of L2s that use the same address format as Ethereum mainnet. This means an address by itself is not enough information to know which chain the address is related to. This can be problematic if funds are sent to an unreachable address on the incorrect chain. From the user account it should be possible to obtain the right chain identifier (chainID) to include in a transaction. -The mapping from chain names to identifiers has, since [EIP-155](./eip-155.md), been maintained off chain using a centralized list. This solution has a few shortcomings: +The mapping from chain names to identifiers has, since [EIP-155], been maintained off chain using a centralized list. This solution has a few shortcomings: - It does not scale with the growing number of L2s. - The list maintainer is a trusted centralized entity. -- It does not (currently) support non-EVM chains, even when naming systems (such as ENS, since ENSIP-9) do. +- It does not (currently) support non-EVM chains, even when naming systems (such as ENS, since [ENSIP-9]) do. -Instead of using non-human-readable numeric chain identifiers, this specification **SHALL** require a human-readable chain name resolved on-chain via ENS wildcard resolver. The centralized chain list maintained in `ethereum-lists/chains` **SHALL** be superseded by an on-chain registry. This registry provides a single source of truth for mapping chain names to chain identifiers and enables decentralized, extensible chain metadata resolution. +Instead of using non-human-readable numeric chain identifiers, this specification SHALL require a human-readable chain name resolved on-chain via ENS wildcard resolver. The centralized chain list maintained in `ethereum-lists/chains` SHALL be superseded by an on-chain registry. This registry provides a single source of truth for mapping chain names to chain identifiers and enables decentralized, extensible chain metadata resolution. In the same spirit, the address could be a human-readable name as well, which is already a use case for ENS. By coupling the TLD to the resolving method used, this standard could leverage current and future features of ENS as well as other naming registries. Moreover, the above can be leveraged to allow for a name to represent the same entity corresponding to different addresses on different chains, mitigating the risk of sending funds to an address the intended recipient doesn't actually control. Desired properties: -- Backwards compatibility with [ERC-7930] -- The chain portion can be an [ERC-7785](./eip-7785.md) domain name when that standard is productive. +- Backwards compatibility with [ERC-7930]. - The address portion can be either the appropriate type of address for the chain, or a domain name. - The address portion and the chain portion should be resolved separately. @@ -66,8 +65,8 @@ Where: - ``, `` and `` are defined to maintain backwards compatibility with [ERC-7930], and their semantics remain the same. - ``: A human-readable chain label within the reserved `.eth` domain. This standard uses `.eth` to provide a consistent abstraction for chain identity, mapping these labels to their corresponding canonical chain identifiers. -- ``: An ENS name, which should be resolved following the appropiate ENSIPs (which this standard does not aim to overwrite). It's grammar definition is slightly different than that of ENSIP-1, as this standard does not support names consisting of only a TLD, since they'd be of limited usefulness. -- `