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

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.

Original ERC · ← ERCs