# ERC-1643 — Change Summary (Original → Current)
This document describes ever…y meaningful difference between the original ERC-1643 proposal text (`erc-1643-original.md`) and the current version (`ERCS/erc-1643.md`).
See [1643](https://github.com/ethereum/EIPs/issues/1643)
---
## 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](https://github.com/ethereum/EIPs/issues/1411)
> - [EIP Draft](https://github.com/SecurityTokenStandard/EIP-Spec)"
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-721.md), [ERC-1155](./erc-1155.md), 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:
```solidity
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](./erc-6093.md) 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`](../assets/erc-1643/src/erc-1643/IERC1643.sol)
- [`ERC1643.sol`](../assets/erc-1643/src/erc-1643/ERC1643.sol)
- [`ERC20DocumentToken.sol`](../assets/erc-1643/src/ERC20DocumentToken.sol)
- [`ERC721DocumentToken.sol`](../assets/erc-1643/src/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](../LICENSE.md)."
---
## 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) |