ERC-1643: Document Management Standard

[adamdossa]

---

eip: ERC-1643
title: Document Management Standard (part of the ERC-1400 Security Token Standards)
author: Adam Dossa (@adamdossa), Pablo Ruiz (@pabloruiz55), Fabian Vogelsteller (@frozeman), Stephane Gosselin (@thegostep)
discussions-to: #1411
status: Draft
type: Standards Track
category: ERC
created: 2018-09-09
require: None

---

Simple Summary

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).

Abstract

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.

Motivation

Accelerate the issuance and management of securities on the Ethereum blockchain by specifying a set of standard interfaces through which security tokens can be operated on and interrogated by all relevant parties.

Since security tokens and their ownership usually entails rights and obligations either from the investor or the issuer, the ability to associate legal documents with the relevant contracts is important. Doing this in a standardised way allows wallets, exchanges and other ecosystem members to provide a standard view of these documents, and allows investors to subscribe to updates in a standardised manner.

Requirements

See ERC-1400 (#1411) for a full set of requirements across the library of standards.

The following requirements have been compiled following discussions with parties across the Security Token ecosystem.

• MUST support querying and subscribing to updates on any relevant documentation for the security.

Rationale

Being able to attach documents to a security token allows the issuer, or other authorised entities, to communicate documentation associated with the security to token holders. An attached document can optionally include a hash of its contents in order to provide an immutability guarantee.

Specification

These functions are used to manage a library of documents associated with the token. These documents can be legal documents, or other reference materials.

A document is associated with a short name (represented as a bytes32), a modified timestamp, and can optionally have a hash of the document contents associated with it on-chain.

It is referenced via a generic URI that could point to a website or other document portal.

getDocument

Used to return the details of a document with a known name (bytes32). Returns the URI associated with the document (string), the hash (of the contents) of the document (bytes32), and the timestamp at which the document was last modified via setDocument (uint256).

function getDocument(bytes32 _name) external view returns (string, bytes32, uint256);

setDocument

Used to attach a new document to the contract, or update the URI or hash of an existing attached document.

setDocument MUST throw if the document is not successfully stored.

setDocument MUST emit a DocumentUpdated event with details of the document being attached or modified.

function setDocument(bytes32 _name, string _uri, bytes32 _documentHash) external;

removeDocument

Used to remove an existing document from the contract.

removeDocument MUST throw if the document is not successfully removed.

removeDocument MUST emit a DocumentRemoved event with details of the document being attached or modified.

function removeDocument(bytes32 _name) external;

getAllDocuments

Used to retrieve a full list of documents attached to the smart contract.

Any document added via setDocument and not subsequently removed via the removeDocument function MUST be returned.

function getAllDocuments() view returns (bytes32[]);

Interface

/// @title IERC1643 Document Management (part of the ERC1400 Security Token Standards)
/// @dev See https://github.com/SecurityTokenStandard/EIP-Spec

interface IERC1643 {

    // Document Management
    function getDocument(bytes32 _name) external view returns (string, bytes32, uint256);
    function setDocument(bytes32 _name, string _uri, bytes32 _documentHash) external;
    function removeDocument(bytes32 _name) external;
    function getAllDocuments() external view returns (bytes32[]);

    // Document Events
    event DocumentRemoved(bytes32 indexed _name, string _uri, bytes32 _documentHash);
    event DocumentUpdated(bytes32 indexed _name, string _uri, bytes32 _documentHash);

}

References

• EIP 1400: Security Token Standard With Partitions
• EIP Draft

[bzzl]

my confusion: why the removeDocuments have the same functionality with setDocuments ?

Used to attach a new document to the contract, or update the URI or hash of an existing attached document.

[adamdossa]

@bzzl - thanks - that was a typo - I've updated the description now.

[itinance]

I would suggest to not shrink the name to 32 bytes. Especially in terms of legal entities there might by much longer document titles that could crash with other titles when only 32 characters are left.
Therefore i would suggest to use string.

Furthermore, if we would work with a document registry, while each document gets its own UUID (which could be represented by bytes16), any reference to this document could be handled with this ID only instead of storing full document records in the contract or a token mapping although many contracts or token would share the same entity.

[joequant]

bytes32 is much too small. the referenceid should be string.

[joequant]

One thing about document management is that it's necessary to somehow attach arbitrary metadata, and I think the basic conceptual question is what about the document gets stored on the blockchain and what gets stored offchain.

Both the uri and hash code should be optional fields.

[chapati23]

A problem I see is the handling of non-public documents. There will be documents or reports that issuers will (or can) only make available to shareholders (= token owners). So either the issuer runs into the problem that they'll need to upload a document publicly that should be restricted OR the investor runs into the problem that they need additional information from the issuer (e.g. a decryption password for the document) to access the document.

Any thoughts here? We at Brickblock are currently just storing an IPFS hash on-chain that links to the off-chain document, but haven't yet found an elegant way to allow only token holders to access it.

[jameshiester]

I would like to propose the addition of a bytes32 type field to the setDocument arguments. This would support grouping documents added to the contract. For example, if there are multiple revisions of the Form D, a user could query all the documents with type Form D. There might be standardized/reserved document types in much the same way that there are standard codes written into the spec. This would also support extending the contract to include a getDocumentsByType function.

[conor10]

Did this ERC go any further? This is the closest thing I've found to a standard for representing externally stored documents in Ethereum contracts.

This linking of external documents comes up a lot, but I've not come across a standard which strikes me as strange given how many organisations want to use blockchain for this use case.

[github-actions]

There has been no activity on this issue for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

[github-actions]

This issue was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.