Skip to content

An extension to the ERC-20 standard token that allows tokens to be put on hold.

License

Notifications You must be signed in to change notification settings

IoBuilders/holdable-token

Repository files navigation

Holdable Token

Build Status Coverage Status npm

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.

Holdable Token: Hold executed

Open iterative hold executed

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

Holdable Token: Open iterative hold executed

Hold released by notary

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

Holdable Token: Hold released by notary

Hold released by payee

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

Holdable Token: Hold released by notary

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

Holdable Token: Hold released on expiration

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

Holdable Token: Hold released on expiration

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.

Holdable Token: Hold executed on total open held amount reached

State diagram

Holdable Token: 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

About

An extension to the ERC-20 standard token that allows tokens to be put on hold.

Resources

License

Stars

Watchers

Forks

Packages

No packages published