Add ERC: Document Management for Security Tokens

[rya-sge]

Adds ERC-1643, a standard interface for attaching, updating, removing, and enumerating documents on token contracts.
ERC-1643 is an old ERC (2018) which was initially part of ERC-1400, but only exists under the form of a GitHub issue.

Changes from the original draft:

• Brought into EIP-1 / eipw compliance (frontmatter, section order, RFC 2119 boilerplate, relative links)
• Modernised Solidity interface: named return values, explicit data locations, NatSpec, and two custom errors (ERC1643InvalidName, ERC1643MissingDocument) following the ERC-6093 convention
• Expanded scope beyond security tokens to cover ERC-721, ERC-1155, vaults, and any product requiring document management
• Added ERC-165 interface detection guidance
• Added Backwards Compatibility, Test Cases, Reference Implementation, and Security Considerations sections
• Reference implementation provided in assets/erc-1643/ (abstract module + ERC-20 and ERC-721 examples, Foundry test suite)

See 1643

Ethereum Magician: link

ERC-1643 — Change Summary (Original → Current)

This issue describes every meaningful difference between the original ERC-1643 proposal text (erc-1643-original.md) and the current version (ERCS/erc-1643.md).

---

1. Frontmatter

Changed fields

Field	Original	Current
eip	ERC-1643 (string with prefix)	1643 (integer only, per EIP-1 format)
title	Document Management Standard (part of the ERC-1400 Security Token Standards)	Document Management for Security Tokens
discussions-to	#1411 (GitHub issue reference)	https://ethereum-magicians.org/t/erc-1643-document-management-standard-erc-1400/27437

Added fields

• description: Interface to attach, update, remove, and enumerate legal or operational documents for token contracts.
• Co-author added to author: Ryan Sauge (@rya-sge)

Removed fields

• require: None — replaced by the absence of the field (no hard dependencies).

---

2. Removed sections

## Simple Summary

The original opened with a Simple Summary section, which is not part of the current EIP-1 template.

Original text:
"This standard sits under the ERC-1400 (#1411) umbrella set of standards related to security tokens. Provides a standard to support attaching documentation to smart contracts, specifically security token contracts in the context of ERC-1400 (#1411)."

Removed entirely. Its substance was folded into Abstract and Motivation.

---

## Requirements

The original contained a dedicated Requirements section.

Original text:
"See ERC-1400 (#1411) for a full set of requirements across the library of standards. [...] MUST support querying and subscribing to updates on any relevant documentation for the security."

Removed. The single MUST requirement was moved into the Specification section. The ERC-1400 reference was removed because ERC-1400 only exists as an external GitHub issue and cannot be linked per eipw rules.

---

## References

Original text:
"- EIP 1400: Security Token Standard With Partitions

• EIP Draft"

Removed. External absolute URLs are not allowed in the ERC body per the markdown-rel-links eipw rule.

---

## Interface (standalone section)

The original exposed the Solidity interface in its own top-level section outside of Specification. This is a non-standard section not permitted by the repo's section-order lint.

Moved into ## Specification as the ### Interface subsection.

---

3. Abstract

Original (2 short sentences):

"Allows documents to be associated with a smart contract and a standard interface for querying / modifying these contracts, as well as receiving updates (via events) to changes on these documents. Examples of documentation could include offering documents and legends associated with security tokens."

Current: Rewritten to be more precise about what the ERC defines (a standard interface, not just a capability), what documents can represent, and the notification mechanism.

---

4. Motivation

Original (1 paragraph): Focused narrowly on security token issuance and the need for standardised document access for wallets and exchanges.

Current (5 paragraphs): Expanded with:

• Explicit statement that the ERC does not define an on-chain attestation mechanism for investor acknowledgement.
• A new paragraph broadening the intended scope: the interface is not restricted to security tokens built on ERC-20 — it can also be used with ERC-721, ERC-1155, decentralized applications, vaults, and any product requiring document management.
• A historical note that the proposal was originally authored as part of a broader security token standards suite (without naming ERC-1400 in ERC-N format, which eipw cannot link).

---

5. Specification

This section was the most substantially rewritten.

RFC 2119 boilerplate — added

Original: No boilerplate. Normative language appeared inline without a preamble.

Current: Standard sentence added at the top:

"The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119 and RFC 8174."

---

Document entry structure — added

Original: Document fields were described only in prose within each function description.

Current: The data model is defined upfront before the interface:

"A document entry is identified by a name (bytes32) and stores: A URI (string) [...] A content hash (bytes32) [...] A last-modified timestamp (uint256) [...]"

---

Interface — Solidity style updated

Aspect	Original	Current
Parameter names	Underscore-prefixed (_name, _uri, _documentHash)	No underscore (name, uri, documentHash)
Return types	Unnamed (returns (string, bytes32, uint256))	Named with qualifiers (returns (string memory uri, bytes32 documentHash, uint256 lastModified))
Data location	Absent (string, bytes32[])	Explicit (string memory, bytes32[] memory, string calldata)
NatSpec	None	@title, @notice, @dev, @return on all items
Custom errors	None	ERC1643InvalidName() and ERC1643MissingDocument() added

---

Custom errors — added

Original: No errors defined; revert behaviour was described only as "MUST throw".

Current: Two errors defined in the interface:

error ERC1643InvalidName();      // setDocument with name == bytes32(0)
error ERC1643MissingDocument();  // removeDocument on a missing entry

Naming rationale for ERC1643InvalidName

The name follows the ERC<N>Invalid<Concept> convention established by ERC-6093 and adopted throughout OpenZeppelin v5 (ERC20InvalidSender, ERC721InvalidOwner, etc.). This makes the error immediately recognisable to developers already familiar with the ecosystem's error vocabulary.

Two alternative names were considered and rejected:

• ERC1643InvalidNameZero — too implementation-specific. "Zero" describes the Solidity representation (bytes32(0)) rather than the semantic meaning. A caller should not need to know the internal representation to understand why a transaction reverted.
• ERC1643EmptyName — semantically clearer about the condition, but deviates from the Invalid<Concept> convention without sufficient gain. Since this is the only name-related error in the interface (format validation was deliberately excluded), there is no ambiguity for ERC1643InvalidName to resolve.

ERC1643InvalidName is concise, follows established convention, and leaves room for implementations to override with more descriptive errors if their policy requires it (the spec permits MAY use different error names/signatures).

---

ERC-165 subsection — added

Original: No mention of interface detection.

Current: New ### Interface Detection (ERC-165) subsection:

"Implementations SHOULD support ERC-165 interface detection. When implemented, supportsInterface SHOULD return true for type(IERC1643).interfaceId and for the ERC-165 interface id."

---

Function Requirements subsection — added

Original: Requirements were expressed as flat prose per function with minimal normative detail.

Current: A ### Function Requirements subsection enumerates precise MUST / SHOULD / MAY rules per function, covering:

• getDocument: empty-return behaviour, no-revert guarantee.
• setDocument: create-vs-overwrite distinction, timestamp update, event emission, bytes32(0) rejection, empty URI/hash policy, error usage.
• removeDocument: removal, event with removed metadata, missing-document error usage.
• getAllDocuments: inclusion and exclusion invariants.

---

6. Rationale

Original (1 paragraph): Only explained why a document hash is useful.

Current (3 paragraphs):

• Added rationale for bytes32 names (compact, deterministic, O(1) comparison vs. string).
• Added rationale for URI-based off-chain storage (gas cost, existing systems).
• Retained and expanded the hash-integrity rationale.
• Added rationale for events (indexing, real-time monitoring).

---

7. New sections (not present in original)

## Backwards Compatibility — added

States that the ERC is additive and does not alter token transfer semantics.

## Test Cases — added

Lists five minimum test scenarios covering the full document lifecycle, event emission, and enumeration consistency.

## Reference Implementation — added

Links to the assets provided in assets/erc-1643/:

• IERC1643.sol
• ERC1643.sol
• ERC20DocumentToken.sol
• ERC721DocumentToken.sol

Describes the internal data structure (mapping, array, index for O(1) removal).

## Security Considerations — added

Four paragraphs covering:

1. Mutable off-chain URI content and the importance of hash verification.
2. Access control on setDocument / removeDocument.
3. Event streams as advisory only; reconcile against on-chain state for correctness.
4. bytes32 name truncation risk and the safer hash-based naming alternative.
5. Backward compatibility note: custom errors and ERC-165 support were absent in the original and older deployments may not expose them.

## Copyright — added

"Copyright and related rights waived via CC0."

---

8. Summary table

Area	Original	Current
Frontmatter format	Non-compliant (eip: ERC-1643, require:, missing description)	EIP-1 / eipw compliant
Section set	Simple Summary, Abstract, Motivation, Requirements, Rationale, Specification, Interface, References	Abstract, Motivation, Specification, Rationale, Backwards Compatibility, Test Cases, Reference Implementation, Security Considerations, Copyright
RFC 2119 boilerplate	Absent	Present
Solidity interface	Old style, no NatSpec, no errors	Modern style, full NatSpec, custom errors
Normative detail	Minimal prose	Granular MUST/SHOULD/MAY per function
ERC-165	Not mentioned	SHOULD support, with interface ID guidance
Scope	ERC-1400 security tokens only	Any token standard or on-chain product
Reference implementation	None	Linked Foundry project with ERC-20 and ERC-721 examples
ERC-1400 reference	Prominently named and linked to GitHub issue	Described generically (eipw cannot link external-only proposals)

[eip-review-bot]

File ERCS/erc-1643.md

Requires 1 more reviewers from @g11tech, @jochem-brouwer, @samwilsn, @xinbenlv

[github-actions]

The commit 723eae2 (as a parent of b6e970b) contains errors.
Please inspect the Run Summary for details.