ERC-1996 Holdable token
Stagnant · Vaults & DeFi · created 2019-04-10
A standard that adds a hold function to ERC-20 tokens, locking up a specified amount for a payment counterparty in advance until a notary executes or releases it.
Why it is needed
ERC-20, Ethereum's basic token standard, lets an account approve another account to spend its tokens via the approve function, but this approval only sets a maximum spendable amount and does not actually lock up that amount as a guarantee. Even with an approved amount, if the owner spends it elsewhere first, a transfer that was meant to execute later can fail. However, in situations like the clearing process for a regulated token, where a transfer cannot be finalized until all verification is complete, or a hotel check-in, where payment must be guaranteed in advance without knowing the exact amount, a simple approval is not enough. Without a hold function, there is no way for the token contract itself to handle this kind of pre-guaranteed payment or conditional settlement.
What to implement
function hold(string calldata operationId, address to, address notary, uint256 value, uint256 timeToExpiration) external returns (bool);: Creates a new hold under msg.sender's account, specifying the payee, notary, maximum amount, and expiration time.function holdFrom(string calldata operationId, address from, address to, address notary, uint256 value, uint256 timeToExpiration) external returns (bool);: A pre-approved operator creates a hold on behalf of the from account.function releaseHold(string calldata operationId) external returns (bool);: Releases a hold without a transfer, returning the locked amount to the payer.function executeHold(string calldata operationId, uint256 value) external returns (bool);: Executes an actual transfer from the payer to the payee for the amount specified by the notary.function renewHold(string calldata operationId, uint256 timeToExpiration) external returns (bool);: Sets a new expiration time for a hold that has not yet expired.function retrieveHoldData(string calldata operationId) external view returns (address from, address to, address notary, uint256 value, uint256 expiration, HoldStatusCode status);: Queries the payer, payee, notary, amount, expiration time, and status of a specific hold.function balanceOnHold(address account) external view returns (uint256);: Queries the total amount of holds placed on an account.function netBalanceOf(address account) external view returns (uint256);: Queries the net balance, the sum of balanceOf and balanceOnHold.function totalSupplyOnHold() external view returns (uint256);: Queries the total amount currently on hold out of the entire token supply.function authorizeHoldOperator(address operator) external returns (bool);: Approves an operator who can create holds on behalf of msg.sender.function revokeHoldOperator(address operator) external returns (bool);: Revokes an operator's authority to create holds.function isHoldOperatorFor(address operator, address from) external view returns (bool);: Queries whether a specific address is approved as an operator for the from account.event HoldCreated(address indexed holdIssuer, string operationId, address from, address to, address indexed notary, uint256 value, uint256 expiration);: An event emitted when a new hold is created.event HoldExecuted(address indexed holdIssuer, string operationId, address indexed notary, uint256 heldValue, uint256 transferredValue);: An event emitted when a hold is executed and an actual transfer takes place.event HoldReleased(address indexed holdIssuer, string operationId, HoldStatusCode status);: An event recorded together with who released the hold and for what reason when the hold was released.event HoldRenewed(address indexed holdIssuer, string operationId, uint256 oldExpiration, uint256 newExpiration);: An event emitted when a hold's expiration time is renewed.event AuthorizedHoldOperator(address indexed operator, address indexed account);: An event emitted when an operator is authorized to create holds.event RevokedHoldOperator(address indexed operator, address indexed account);: An event emitted when an operator's hold-creation authorization is revoked.
In depth
hold / holdFrom: Creating a Hold
hold creates a hold on the msg.sender's own tokens, while holdFrom creates a hold on the from account's tokens by an operator previously authorized via authorizeHoldOperator. You specify an operationId (string), payee to, notary notary, maximum transfer amount value, and time remaining until expiration timeToExpiration. value must not exceed the payer's balance, and an already-used operationId cannot be reused. If timeToExpiration is 0, the hold becomes perpetual and is not released by expiration. A HoldCreated event is emitted upon creation.
executeHold: Partially Executable Final Transfer
Only the notary can call this, and it actually transfers the specified value in tokens from the payer to the payee. If value is less than the maximum amount held, the remainder is released back to the payer and becomes usable again. After execution, the HoldExecuted event records both the held amount (heldValue) and the actually transferred amount (transferredValue).
releaseHold: Releasing a Hold Without a Transfer
Before expiration, only the notary or payee can call releaseHold; after expiration, anyone can call it. When released, no transfer occurs and the held amount is released back to the payer. The status value in the HoldReleased event records one of ReleasedByNotary, ReleasedByPayee, or ReleasedOnExpiration, distinguishing who released it and why.
renewHold: Renewing the Expiration Time
Only the payer or operator can call this, and it applies only to holds that have not yet expired. The new expiration time is reset to the block timestamp at the time of the call plus the new timeToExpiration; if timeToExpiration is 0, a previously time-bound hold becomes a perpetual hold. Upon renewal, the previous expiration time and the new expiration time are recorded in the HoldRenewed event.
Query Functions: Hold Status and Balance Aggregation
retrieveHoldData returns the payer, payee, notary, amount, expiration time, and status (HoldStatusCode) for a given operationId. balanceOnHold returns the total amount held on an account, netBalanceOf returns the net balance combining balanceOf and balanceOnHold, and totalSupplyOnHold returns the total amount currently held across the entire token supply.
Operator Authorization System
authorizeHoldOperator authorizes another address to call holdFrom on one's own account, and revokeHoldOperator withdraws that authorization. isHoldOperatorFor queries whether a given address is an operator for a given account. The source states that the names of these three functions are not mandatory but follow ERC-777's naming convention.
Modifying balanceOf / transfer / transferFrom and operationId Design
Implementing this standard requires changing the existing ERC-20 balanceOf to return a value excluding the held amount, and transfer and transferFrom must be modified to prevent transferring amounts that are on hold. operationId was chosen as a string to prioritize traceability and readability over gas efficiency; whether to store the full string on-chain or only its hash is left to the implementer's choice. Issuers are recommended, though not required, to use unique, non-overlapping prefixes.
Standard status
This proposal is in Stagnant status, meaning it is no longer actively discussed or advanced. Its content may change or it may never be adopted.