New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ERC-1643: Document Management Standard #1643

Open
adamdossa opened this Issue Dec 10, 2018 · 3 comments

Comments

Projects
None yet
3 participants
@adamdossa
Copy link

adamdossa commented Dec 10, 2018


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

@adamdossa adamdossa changed the title WIP Document Management Standard Dec 10, 2018

@adamdossa adamdossa changed the title Document Management Standard ERC-1643: Document Management Standard Dec 10, 2018

@bzzl

This comment has been minimized.

Copy link

bzzl commented Dec 27, 2018

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

This comment has been minimized.

Copy link

adamdossa commented Jan 3, 2019

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

@itinance

This comment has been minimized.

Copy link

itinance commented Jan 14, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment