eip1996 v3.0.1

Holdable Token

This is the reference implementation of EIP Holdable Token. This implementation will change over time with the token standard and is not stable at the moment.

Feedback is appreciated and can given at the discussion of the EIP.

Summary

An extension to the ERC-20 standard token that allows tokens to be put on hold. This guarantees a future transfer and makes the held tokens unavailable for transfer in the mean time. Holds are similar to escrows in that are firm and lead to final settlement.

Abstract

A hold specifies a payer, a payee, a maximum amount, a notary and an expiration time. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either executed or released. The hold can only be executed by the notary, which triggers the transfer of the tokens from the payer to the payee. If a hold is released, either by the notary at any time, or by anyone after the expiration, no transfer is carried out and the amount is available again for the payer.

A hold can be partially executed, if the execution specifies an amount less than the maximum amount. In this case the specified amount is transferred to the payee and the remaining amount is available again to the payer.

Holds can be specified to be perpetual. In this case, the hold cannot be released upon expiration, and thus can only be executed by the notary or released by the notary or payee.

Sequence diagrams

Hold executed

The following diagram shows the sequence of the hold creation and execution.

Open iterative hold executed

The following diagram shows the sequence of the hold creation and execution.

Hold released by notary

The following diagram shows the sequence of a hold creation and release by the notary.

Hold released by payee

The following diagram shows the sequence of a hold creation and release by the payee.

Hold released on expiration

The following diagram shows the sequence of a hold creation and release after it has expired. After a hold has expired it can be released by anobody. Here in the sequence by a not involved third-party user UserC

Hold released on expiration

The following diagram shows the sequence of a hold creation and release after it has expired. After a hold has expired it can be released by anobody. Here in the sequence by a not involved third-party user UserC

Hold executed on total amount reached

The following diagram shows the sequence of a hold creation and release after an open hold has fulfilled all held money.

State diagram

Install

npm install eip1996

Usage

To write your custom contracts, import it and extend it through inheritance.

pragma solidity ^0.5.0;

import 'eip1996/contracts/Holdable.sol';

contract MyHoldable is Holdable {
    // your custom code
}

You need an ethereum development framework for the above import statements to work! Check out these guides for Truffle, Embark or Buidler.

Tests

To run the unit tests execute npm test.

Code coverage

To run the code coverage simply execute npm run coverage

Deployment

To deploy a new version to NPM the version in package.json has to be increased and a tag has to be created on the master branch. This can be done in one step with one of the following commands

# new patch version
npm version patch

# new minor version
npm version minor

# new major version
npm version major

Afterwards the changes and the tags have to be pushed to the GitHub repository with:

git push
git push origin --tags