ERC-1404: Simple Restricted Token Standard

[masonicGIT]

eip	title	authors	status	discussions-to	type	category	created
1404	Simple Restricted Token Standard	Ron Gierlach <@rongierlach>, James Poole <@pooleja>, Mason Borda <@masonicGIT>, Lawson Baker <@lwsnbaker>	Draft	https://github.com/simple-restricted-token/simple-restricted-token/issues	Standards	ERC	2018-07-27

Simple Restricted Token Standard

Simple Summary

A simple and interoperable standard for issuing tokens with transfer restrictions. The following draws on input from top issuers, law firms, relevant US regulatory bodies, and exchanges.

Abstract

Current ERC token standards have provided the community with a platform on which to develop a decentralized economy that is focused on building Ethereum applications for the real world. As these applications mature and face consumer adoption, they begin to interface with corporate governance requirements as well as regulations. They must not only be able to meet corporate and regulatory requirements but must also be able to integrate with technology platforms underpinning their associated businesses. What follows is a simple and extendable standard that seeks to ease the burden of integration for wallets, exchanges, and issuers.

Motivation

Token issuers need a way to restrict transfers of ERC-20 tokens to be compliant with securities laws and other contractual obligations. Current implementations do not address these requirements.

A few emergent examples:

• Enforcing Token Lock-Up Periods
• Enforcing Passed AML/KYC Checks
• Private Real-Estate Investment Trusts
• Delaware General Corporations Law Shares

Furthermore, standards adoption amongst token issuers has the potential to evolve into a dynamic and interoperable landscape of automated compliance.

The following design gives greater freedom / upgradability to token issuers and simultaneously decreases the burden of integration for developers and exchanges.

Additionally, we see fit to provide a pattern by which human-readable messages may be returned when token transfers are reverted. Transparency as to why a token's transfer was reverted is of equal importance to the successful enforcement of the transfer restriction itself.

A widely adopted standard for detecting restrictions and messaging errors within token transfers will highly convenience the exchanges, wallets, and issuers of the future.

Specification

The ERC-20 token provides the following basic features:

contract ERC20 {
  function totalSupply() public view returns (uint256);
  function balanceOf(address who) public view returns (uint256);
  function transfer(address to, uint256 value) public returns (bool);
  function allowance(address owner, address spender) public view returns (uint256);
  function transferFrom(address from, address to, uint256 value) public returns (bool);
  function approve(address spender, uint256 value) public returns (bool);
  event Approval(address indexed owner, address indexed spender, uint256 value);
  event Transfer(address indexed from, address indexed to, uint256 value);
}

The ERC-1404 standard builds on ERC-20's interface, adding two functions:

contract ERC1404 is ERC20 {
  function detectTransferRestriction (address from, address to, uint256 value) public view returns (uint8);
  function messageForTransferRestriction (uint8 restrictionCode) public view returns (string);
}

The logic of detectTransferRestriction and messageForTransferRestriction are left up to the issuer.

The only requirement is that detectTransferRestriction must be evaluated inside a token's transfer and transferFrom methods.

If, inside these transfer methods, detectTransferRestriction returns a value other than 0, the transaction should be reverted.

Rationale

The standard proposes two functions on top of the ERC-20 standard. Let's discuss the rationale for each.

1. detectTransferRestriction - This function is where an issuer enforces the restriction logic of their token transfers. Some examples of this might include, checking if the token recipient is whitelisted, checking if a sender's tokens are frozen in a lock-up period, etc. Because implementation is up to the issuer, this function serves solely to standardize where execution of such logic should be initiated. Additionally, 3rd parties may publicly call this function to check the expected outcome of a transfer. Because this function returns a uint8 code rather than a boolean or just reverting, it allows the function caller to know the reason why a transfer might fail and report this to relevant counterparties.
2. messageForTransferRestriction - This function is effectively an accessor for the "message", a human-readable explanation as to why a transaction is restricted. By standardizing message look-ups, we empower user interface builders to effectively report errors to users.

Backwards Compatibility

By design ERC-1404 is fully backwards compatible with ERC-20.
Some examples of how it may be integrated with common types of restricted tokens may be found here.

Test Cases & Implementation

See the reference implementation and tests here.
See some examples of common usage patterns for ERC-1404 here.

Copyright

Copyright and related rights waived via CC0.

[bmann]

This seems very similar to #902?

902 uses a check function (it's broader than just security tokens, but effectively this is the same as detectTransferRestriction).

No worries either way, but happy to discuss updates into 902 if you found something missing in it.

Thanks for taking the time to write up and submit this as an EIP!

[youfoundron]

@bmann Thanks for chiming in!

Looks like #902's TokenValidator contract shares more similarities to Harbor R-Token's RegulatorService approach. We include an R-Token integration example here! 😄

In ERC1404, detectTransferRestriction is meant to live on the token contract itself, in there you could easily kick off the call to validate (what looks to be one of #902's "validation helpers") and achieve a similar result.

[veikkoeeva]

Some questions (might be dumb):

1. If the securities are non-fungible, it would be checked in detectTransferRestriction? Just to make sure as there's a bit of cognitive disonance about ERC-20.
2. Should there be a possibility to have batch transfers?
3. I'm wondering if/how this would work with surety bonds (e.g. three parties, more complex terms, still in detectTransferRestriction?). I might off with this one on the purpose of this (though in that case pointers and clarifications welcome).

[Graeme-Code]

Hi, I'm very interested in using this standard for a governance project with regards to access control. Anybody looked into how this would work with Giveth's mini-me contract?

[youfoundron]

@Graeme-Code, I have not personally used the MiniMe pattern but at a cursory glance of Giveth's repo, it seems you would need to use a version of the MiniMeToken.sol contract modified to implement ERC1404 -- the place to look is function doTransfer() on this contract.

If there is considerable interest in this use-case I would be happy to add an implementation to our examples repo.

[Graeme-Code]

Thank you for the quick response. Running some tests internally and getting consensus on the idea. Will let you know if it is implemented. Cheers

…

On Thu, Sep 20, 2018 at 6:07 PM Ron Gierlach ***@***.***> wrote: @Graeme-Code <https://github.com/Graeme-Code>, I have not personally used the MiniMe pattern but at a cursory glance of Giveth's repo, it seems you would need to use a version of the MiniMeToken.sol contract modified to implement ERC1404 -- the place to look is function doTransfer() on this contract <https://github.com/Giveth/minime/blob/master/contracts/MiniMeToken.sol>. If there is considerable interest in this use-case I would be happy to add an implementation to our examples repo <https://github.com/simple-restricted-token/simple-restricted-token>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1404 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHjHZa18GBJ_sA_N7uD-3jEeQuL4U_jdks5uc8tPgaJpZM4Wktae> .

-- I respond faster on Status, use my contact code below to add me: 0x043d3e8477d431c44cdb12f69375726ed3fa83b4409a2848fa8f625c9394f6214ad473cb5314c5c50cb8cc3e4f4ba870afb6364c730a5664f4ad2c523e66ccc431

[youfoundron]

@veikkoeeva No dumb questions! Will try and address each of these to the best of my ability.

1. If the securities are non-fungible, it would be checked in detectTransferRestriction? Just to make sure as there's a bit of cognitive disonance about ERC-20.
   
   By non-fungible do you mean "partially fungible" a la ERC 1410: Partially Fungible Token Standard #1410, or full on NFT as in ERC: Non-fungible Token Standard #721? In the case of the former, there are no special implementation requirements. To make an ERC1404 + ERC721 compatible token you could easily modify this implementation to handle the _isApprovedOrOwner and zero address logic inside of detectTransferRestriction. If there is considerable interest in this use-case I would be happy to add an implementation to our examples repo.
2. Should there be a possibility to have batch transfers?
   
   This is functionality outside of the scope of ERC20 and by extension outside of the proposed scope of this standard. It would be useful to a lot of people however, and I'd encourage you to pursue this idea further!
3. I'm wondering if/how this would work with surety bonds (e.g. three parties, more complex terms, still in detectTransferRestriction?). I might off with this one on the purpose of this (though in that case pointers and clarifications welcome).
   
   I'm not certain, but this scenario doesn't sound like a straight up transfer of tokens. Correct me if I'm wrong, but I believe you're describing an arrangement where tokens would go into escrow, a third party would give some sort of approval, and (if all goes well) tokens would depart escrow en route to a predetermined recipient. The transfers to / from escrow could be regulated by transfer restrictions of your designing, but unless this process can be executed in a single transaction it is beyond the scope of this standard.

[veikkoeeva]

@rongierlach (or @masonicGIT). Hey, I appreciate you took the time to get back. I'll keep the numbering in the following, but instead of quoting just paraphrase.

1. By non-fungible securities I mean that some securities are non-fungible, as explained at
   https://www.repetico.de/card-34407474. In the EU there has been some bonds that are non-fungible due to some extra national serial codes (see here [pdf]), but the desire is to move towards fully fungible ones. I understand it's very desirably to have fungible securities (and even to be trade them globally), but I'm especially looking into green bonds and the problems faced there. Some noted, e.g., at https://www.eco-business.com/news/will-a-lack-of-transparency-hurt-green-bonds/. The Finnish Financial Regulatory Authority, I believe, recently warned about due diligence risks in green bonds. I don't have deep enough knowledge on securities to know if some sort of non-fungibility could solve problems but still keep trading liquid.

2. This idea has been thought of already, as noted. There's a new standard in the makings that allows batch transfers of fungible and non-fungible tokens, more information at ERC: Multi Token Standard #1155. There's also a new 721x (mentioned at the end of 1155) that builds on 721 directly.

3. That's true as far as I understand. As I see it, the other way/term looking into sureties is bank guarantees. I don't think these are tradeable assets usually, but can be used to make so, as noted at https://www.bankguaranteefacts.com/trading-bank-guarantees/. Then there are tradeable bank guarantees, though, as noted at https://www.linkedin.com/pulse/fraud-trading-discounted-bank-guarantees-lady-mj-santos.

The reason why I noted these might be dumb, or confused questions, are that I don't have deep knowledge on securities and trading and English isn't my native language (the terminology feels a bit problematic). I see there are plenty of inefficiencies in trading globally and fungibility is very much desired. I'm wondering also if there were a use case, now in the age of blockchain, for non-fungible securities as in with green bonds. I could imagine -- maybe wrongly -- greend bonds issued to construction could be tied to particular buildings are in the power plant building noted in the earlier green bond link. In that sense the bonds might not be fully fungible. Or they might be fully tradeable, but still maintain an unique link to off-chain data (like in ERC-721/ERC-721x/ERC-1155).

While writing this, I noticed Dharma protocol which seems to aim tokenizing debt into securities using ERC-721 (link to Ethereum contracts at https://blog.dharma.io/dharma-bug-bounty-erc721-collateralization-137b2baeca24). In my mind securities and debt securities are around the same issue, but I might be misguided here.

If there is something I could find more information on, I'm happy to do put some effort. I'm equally happy to be noted this is out-of-scope and/or I need to check some sources to increase my understanding otherwise.

Once again, I appreciate the effort to get back with explanations. I for one would appreciate an added sample to the sample repo on non-fungible asset.

[zxlzy]

I am an eth fan and solidity beginner from China. I think this this standard is very useful. I do some simple implement for this standard. I do not implement the ban function. But it's easy.
Every tx can teturn just one restrictionCode .But may have more than one reson for be restricted. Should we solve it?
Insert this at transfer and transferFrom function.

uint8 restrictionCode = detectTransferRestriction(_from,  _to, _value);
if( restrictionCode != 0 ) {
 revert(restrictionCode);
}

There is the ERC1404 contract.

contract ERC1404 is StandardToken , Pausable  {
  mapping(uint8 => string) restrictionMap;
  mapping(address => bool) blackList;
  constructor () public {
    restrictionMap[1] = "Token is pausing!";
    restrictionMap[2] = "sender has been banned!";
    restrictionMap[3] = "receiver has been banned!";
  }

  function detectTransferRestriction (address from, address to, uint256 value) public view returns (uint8){
    if (paused == true ) {
      return 1;
    }
    if (blackList[from] == true ) {
      return 2;
    }
    if ( blackList[to] == true ) {
      return 3;
    }
  return 0;
  }
  function messageForTransferRestriction (uint8 restrictionCode) public view returns (string){
    if (bytes(restrictionMap[restrictionCode]).length == 0 ){
      return "Restriction code incorrect!";
    }
    return restrictionMap[restrictionCode];
  }

}

[youfoundron]

@zxlzy At a cursory glance this implementation seems correct. Nice work! 👍
A transaction failing because of more than one reason is a likely possibility. However, modifying the standard to return multiple restriction codes from say a function called detectTransferRestrictions would be tricky because Solidity does not support returning dynamic arrays. There are workarounds for this, but I feel they would sacrifice the simplicity of the standard.

[AC0DEM0NK3Y]

Hi I noticed #1155 was linked here regarding the batch transfer possibility. I should note that I don't see a problem with someone implementing "AContract is 1155,1404" and in the transferring of tokens simply calling the detectTransferRestriction each time...

However if you did want to do 100 transfers in one batch tx perhaps, the requirement to revert on one non-zero return would mean that for eg. instead of 99 transfers passing and 1 failing, all 100 transfers would fail.

Maybe that is something to consider when developing this standard?

Of course however if the detectTransferRestriction is called for each transaction off chain first, then you could do the above batching without having to enforce the check on chain but I'm not aware of the use cases of this standard enough to say that the detection has to always happen on chain during the transfer to make things transparent and secure.

Perhaps, you would just have to do both off and on checks to "guarantee" a batch would make it through in the majority of cases and still enforce security and transparency.

So offline at least (without regard for usable/nice code):

bool doTheBatchTx = true;
int numberOfTransfers=sizeof(fromArray); // better check your arrays all match and numberOfTransfers > 0
while(numberOfTransfers--) {
	if (contract.detectTransferRestriction(fromArray[numberOfTransfers]),toArray[numberOfTransfers],valueArray[numberOfTransfers])) {
		doTheBatchTx = false;
		break;
	}
}

if (doTheBatchTx)
	contract.multicastTransferFrom(fromArray,toArray,idArray,valueArray);
else
	errorMsg("One of the batch transfers failed the detectTransferRestriction check");

any that might fail the above you could drop from the arrays and at least salvage things (unless you needed to guarantee a set and so dropping the entire set might be desirable).

[jllaw]

Really nice and clean. As someone who was involved with the genesis of #1400 (#1410 & #1411), I can really appreciate the simplicity of this. Will monitor and contribute if I can (hard to follow all the conversation as I'm not technically trained).

[jllaw]

"The logic of detectTransferRestriction and messageForTransferRestriction are left up to the issuer."

Just to be clear, the detectTransferRestriction doesn't give a third party any knowledge of the full set of transfer restrictions and rules which might apply to a token right? All this standard would do is 1) check if something can be transferred against something offchain and 2) report some sort of error (but not necessarily in any standardized format).