eip1996
v3.0.1
Published
An extension to the ERC-20 standard token, which 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 settle
Downloads
6
Maintainers
Readme
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