I like this. An API that has been sorely needed. Thanks for putting this out there.

Nomenclature hasn't always been clear to me: variations of mint/withdraw/create/destroy, etc haven't been obvious, but increaseSupply & decreaseSupply seems to the most generic. +1.

There is however one change I would do with this: making it even more generic.

I would rephrase this as: "Token Standard Extension for Increasing & Decreasing Supply".

Then, secondly, I would take out the importance of the contract creator and make it more generic. There might be scenarios where one might want to update supply based on a specific condition that can be called by anyone. eg, submit a proof of a burned Bitcoin from BTCRelay and it increases supply of E-BTC. So the ownership/creator logic should be optional imho. Additionally, the increase & decrease should also allow for doing this for any address. So, I would change this to:

function increaseSupply(uint256 value, address for) returns (bool)

"Increases total supply of the token by value and credits it to address for."

function decreaseSupply(uint256 value, address from) returns (bool)

"Decreases total supply by value and withdraws it from address from if it has a sufficient balance."

Ownership/creator/change logic is optional for the token contract. So if you want an owner/creator/third party to be able to increase supply, you add it yourself that logic internally.

What do you think?

I'm uncertain about variable naming and parameter order here. What do you also think about abstracting it to being more generic like the above APIs?

Additionally, the increase & decrease should also allow for doing this for any address.

+1 to this. No need to restrict supply changes to a single, static address.

Ownership/creator/change logic is optional for the token contract. So if you want an owner/creator/third party to be able to increase supply, you add it yourself that logic internally.

I think there definitely needs to be an owner if the contract allows arbitrary inflation in perpetuity. This parameter can be called something other than creator, though that's the best name I can think of. I think only this address should be able to change supply after the initial deployment.

I'm uncertain about variable naming and parameter order here. What do you also think about abstracting it to being more generic like the above APIs?

Not sure what you mean by this. Can you elaborate?

I think there definitely needs to be an owner if the contract allows arbitrary inflation in perpetuity.

I think increasing & decreasing supply can be made more generic for other conditions.

It's likely that most of the use cases will have an owner/creator that is the authority allowed to increase/decrease, but you can do some other things that will allow this API extension to be more generic. For example, a once-off seal can be implemented. If sha3 of a string == a hardcoded hash, then you can increase supply. It only works once. There is thus no owner/creator here.

So, I would advocate that requiring a creator limits the functionality of this API extension even though it's likely that it will be the most used pattern.

Not sure what you mean by this. Can you elaborate?

re variable naming & parameter order. Just wondering if the current spec has the least ambiguous naming. Need to think more if there are better words to use for the parameters. :)

Fair enough point about abstraction. I suppose the standard itself could abstract that "creator only" restriction to an isOwner modifier.

I'm worried about bad implementations, but I guess the more abstract the standard, the better.

I think it's a great idea to start thinking about what more flexibly managed tokens should do and what they should look like. But, annoyingly, I have nitpicks.

Generally when entities offer claims that can be issued at will, they do not do so to themselves, because they already have an effectively infinite inventory. "Treasury stock" — a firm's notional holdings of its own shares — is a rare and not very useful accounting formality, and would be even rarer and less useful if there were not regulatory inconveniences surrounding new share issue. There is effectively an infinite quantitative supply of US dollars at the Fed. What matters is not the number, but the institutions behavior in terms of how much it will put into circulation, and in exchange for what assets. I think it's not a great idea to standardize a notion of self-issue. That's kind of a no-op and leads to a great deal of confusion. This is timely with GNO, for example. Rather than imagine that outsiders bought 5-ish% of the float and the company made out like bandits and has some bizarre market cap, it's more useful to say that the firm only issued what it sold, has disclosed plans to issue substantially more tokens over a period of several years to its developers, and has committed to a permanent total cap on issuance. Treating that permanent total cap number as meaningfully extant now yields a lot more heat than light, in my view. Tokens are neither shares of stock nor fiat currency, but like firms and central banks, organizations that issue tokens will be interested in managing the usefulness and value of their issues and using new tokens to incentivize useful behavior or acquire valuable assets.

So, broadly, if we want to standardize contracts that will inform practices around issuable tokens, I'd prefer functions that let the issuer issue them to any address. This would accommodate self-supply if desired, but would capture the more generally useful case. (I'd also prefer that the function be called "issue".)

Similarly, on the other side, organizations often accept claims they themselves have issued in exchange for some form of value. The usual word for this is "redemption". If I run a bakery, I might issue a token whose value is given a floor by virtue of it's being redeemable for a muffin. We might imagine that the buyer simply pays in MuffinCoin, which my bakery then receives in its account. But again, there is more heat than light in that. If my bakery can issue MuffinCoin, at will and without friction, does its own internal MuffinCoin balance matter in any meaningful way? I'd say no. It'd be much better for such a token to have a straight-up "redeem" method, that simultaneously surrenders and retires the token from the total float.

Thinking in terms of issuance and redemption, rather than increasing and decreasing internal supply, complicates the work here, potentially a lot. In general, issuance should be tied to the performance of some favor or the surrender of some value, while redemption should be associated with the provision of some value by the token issuer. A very simple token whose value is capped at 1 ETH might issue on demand in exchange for a payment of 1 ETH. A token that wished to put a floor on its value might be redeemable automatically for that value. From token users perspective, much more important than a quantitative notional supply (that includes a lot of internally owned tokens) is some sense of the terms or purposes for which tokens are issued or redeemed. It'd be easy, and perhaps useful, to standardize contracts with floors and caps expressible in terms of ETH or other tokens. When tokens will be issued at the discretion of insiders to incentivize development, or via some DAO-like proposal and voting scheme, things get more complicated. Would it be useful to standardize the notion of contracts logging something about value received that provoked token issue, or the value surrendered in exchange for redemption? Maybe, or maybe trying to standardize that in strings or something would foreclose more useful, token-specific solutions.

I think this is very important work. Tokens will only really become useful for more than wild (if momentarily lucrative) speculation as they become issuable and redeemable. This is very long-winded, but the tl; dr is that tokens should become useful for more than blue-sky speculation, terms of issuance and redemption are important means by which they can be given broader use, so I'd encourage thinking about terms of issuance and redemption rather than quantitive supply as primary drivers of token value, and discourage fetishizing especially internal "supply".

Cool, looks a lot like DSToken. Suggest aliases mint and burn.

Very much disagree with imposing any sort of control convention, we have had great success with the more general auth pattern and it would be a big pain to retrofit existing tokens. Also the base token standard doesn't define semantics (only ABI) and I kind of like it that way.

Also don't like this doubling down on return-value-oriented error management, but it might be too late to change that.

@swaldman The simple answer is that the control address can be a different contract which could encode all the different examples you made, in other words all the things you said are exactly the motivator for this issue from my POV

We are using a similar pattern for Gnosis outcome tokens. Instead of assigning them to a creator, they are direclty assigned to a specific address: https://github.com/ConsenSys/gnosis-contracts/blob/master/contracts/solidity/EventFactory/OutcomeToken.sol#L38

This allows some more flexibility and saves an additional transaction. Of course, the creator can just issue tokens for himself.

One suggestion: It became a convention to use a transfer event, sending tokens from address 0 or the token address itself to issue tokens. This was done by many crowdsales in the past to distribute the initial tokens. This could be reused in this case:

Transfer(0, <receiver>, <amount>);

The example implementation does not appear to do anything:

function increaseSupply(uint value) public returns (bool) {
  if (msg.sender == creator) {
    if (!safeAdd(totalSupply, value)) { throw; };
    if (!safeAdd(balances[creator], value)) { throw; };
    return true;
  }
  return false;
}

safeAdd does not modify any values, it just returns the sum or throws if there is an overflow. You dont need to check the return value you need to set whatever is being updated to it. For example:

function increaseSupply(uint value) public returns (bool) {
    if (msg.sender != creator) throw;
    totalSupply = safeAdd(totalSupply, value); // throws if overflow
    balances[creator] = safeAdd(balances[creator], value);  // throws if overflow
    return true;
}

Also you consider using the owned class from the ethereum.org tutorials:

contract owned {
    address public owner;

    function owned() {
        owner = msg.sender;
    }

    modifier onlyOwner {
        if (msg.sender != owner) throw;
        _;
    }

    function transferOwnership(address newOwner) onlyOwner {
        owner = newOwner;
    }
}

Which is already a somewhat standard way to specify that a contract has an owner. It gives you the modifier onlyOwner which makes it clearer that the function has access control applied to it:

function increaseSupply(uint value) onlyOwner returns (bool)  {
    totalSupply = safeAdd(totalSupply, value);
    balances[owner] = safeAdd(balances[owner], value);
    return true;
} 

Adding on to @nmushegian's comment, I don't see any reason to specify access control here. That should be strictly an implementation detail IMO - isOwner / auth / whatever. The nice thing about ERC20 is that it's just a standard interface for token manipulations and nothing more.

@swaldman: I like your last point to avoid elevating 'supply' as a meaningful notion (any more than it already is). These additional functions should just mean:

• give me more tokens
• take these tokens from me

How these things happen is up to the implementation: maybe tokens are newly created, maybe there is a pool of available tokens, maybe tokens are taken proportionally from everyone else... There's a huge range of crazy semantics, so don't try and constrain them.

I prefer mint / burn for naming, but I'm biased.

I'll add to @rainbreak and @nmushegian in saying we've been using mint and burn for a while now.

+1 not forcing a creator for the supply change.

@JonnyLatte can you give your thoughts on explicitly not including any sort of access control pattern in this standard definition?

In some ways I think control architecture is a kind of prerequisite for trying to discover good standards, essentially the motive for trying to add creator/owner/auth/whatever is that you can't really make use of the admin backdoor definitions without also knowing about how to change control contracts

Proposal has been updated in light of comments above. Please see original commit for reference.

Thanks everyone, keep the comments coming.

@alex-miller-0 👍 for taking this up. Such an extension of ERC20 is dearly needed.

I'm with @simondlr when it comes to keep the creator/generator as generic as possible. It should not be restricted to a central address / or addresses of a central controlling entity. While there might be cases of central issuance, I can see very many where this part will be a decentralized function.
Thus, in extending the standard, we should keep it as generic as possible.

@swaldman : While I can see your reasoning, I'm with @nmushegian on this issue. As a matter of fact, these are specific situations that must be addressed in a separate contract. It will be detrimental to try and regulate such aspects in the standard.

Finally, when it comes to the naming convention, mint and burn sounds just right ;-)

@alex-miller-0 : Just had a look at the updated proposal.

May I suggest to re-formulate "cases of digitized, centrally controlled assets" into "cases where a control of the total supply of assets is desired". Of course, the summary should reflect this as well.

As argued in my previous comment, I am a strong advocate of keeping the standard as open as possible. Central control may or may not be desired, independent of the fact that the supply the asset can vary.

EDIT: For consistency reasons, I would also remove the allusion to Central operators in the Rationale. Just call them operators.

@nmushegian I like how the payable modifier was introduced with the default being that functions cannot receive ETH which forces developers to explicitly state that they are supposed to receive funds. Applying this more generally to access control seems like a rather daunting task though because its the developers of the application are the ones deciding who can access what under what conditions.

Maybe if you could specify for a contract or entire build that access control modifiers are required on all public functions and have the contract not compile in your environment if they are left off. That change would be portable to compilation environments that are not enforcing access control so the code would still be portable.

To be honest though I'm not experienced enough with large projects requiring access control to be confident that any suggestions I make would be a help or hindrance.

I am not a fan of this functionality being added to the token standard unless part of the standard recommends that the function be "off-by-default." The community should adhere, I think, to a very strong "decentralize everything" philosophy, especially when specifying standards, especially with the token standard.

Having said that, it's obvious that people would want this. I would like to see a simple query become part of this proposal such as "bool supplyMayChange."

In this way, it would be easy for users and tools to distinguish between "supply changeable" tokens and those whose supply cannot change. Not sure how one would enforce that, though.

off-by-default

@tjayrush I think the intent with this, is exactly that. It's an extension to ERC20. So it won't be folded into ERC20, but rather you will have ERC20 + ERC621 tokens.

Regarding mint & burn.

I'm personally in favour of keeping with generic naming (increase/decrease supply). "mint" seems skeuomorphic, not really apt anymore in this context.

Additionally, I wonder if there's potentially issues with mistaking the nomenclature and implying certain things that could be disregarded as illegal. ie, "burning" money is illegal in most nation states.

Not sure if it's a big deal or not, but something to consider. :)

I question the need to specify this as an official API. The purpose of an official API is that the contract can be called from any other contract, without having to know what token it is. But changing the supply is never going to be done from any other random contract. It is only going to be done from specially trusted contracts.

Can you give an example where one of the current tokens would benefit from using this API?

It may be good as a recommended praxis, but that is a developer guideline, not an API requirement.

Edit: Spelling.

I question to need to specify this as an official API

I agree with you. I honestly wasn't sure where to bring this up and I'm not sure how to distribute this as a suggested standard.

It would be cool to have some sort of official repo for standards that are voted on and improved by the community.

I kind of agree RE standardisation, although I think that there are useful things to standardise here; specifically, how to log events for token creation and deletion. Presently some tokens emit a custom event for this, while others log it as a transfer from 0, and still others log it as a transfer from the token contract's address.

It'd also be interesting to see a (probably separate) standard for fundraising contracts that accept bids or buy orders.

@tjayrush:

I am not a fan of this functionality being added to the token standard unless part of the standard recommends that the function be "off-by-default." The community should adhere, I think, to a very strong "decentralize everything" philosophy, especially when specifying standards, especially with the token standard.

Again the point of having access control defined by contract is that everything is "off by default" because you must explicitly program the conditions under which it can be called, which is outside the scope of this EIP afaik

@larspensjo:

But changing the supply is never going to be done from any other random contract. It is only going to be done from specially trusted contracts.

Yep exactly, which makes me double down on this:

In some ways I think control architecture is a kind of prerequisite for trying to discover good standards, essentially the motive for trying to add creator/owner/auth/whatever is that you can't really make use of the admin backdoor definitions without also knowing about how to change control contracts

I question the need to specify this as an official API

Agree and furthermore I think contract standards should be squarely outside the scope of EIPs and there should not be any more "official" APIs. But let's still make threads to coordinate design patterns, and then people can make their own decisions! =O

But changing the supply is never going to be done from any other random contract. It is only going to be done from specially trusted contracts.

Yep exactly,

As @simondlr pointed out these methods might actually be used by contracts that impose trustless logic instead of relying on a trusted third party. As suchI don't think this should simply be dismissed as being a contract standard and thus not suited for an EIP.

My beliefs are in sync with what was stated before, already: the need for ever more complex token models would be benefit greatly from having an official API like this.

Can you give an example where token A is requested by contract B to change the supply, given that A is unknown to B?

Especially if A is one of the currently existing tokens.

Can you give an example where token A is requested by contract B to change the supply, given that A is unknown to B?

Can you clarify a bit? For B to call A.mint(...) it obviously needs to have a reference to A, at least at the moment, and nobody here disagrees with that.

Can you give an example where token A is requested by contract B to change the supply, given that A is unknown to B?

Can you clarify a bit? For B to call A.mint(...) it obviously needs to have a reference to A, at least at the moment, and nobody here disagrees with that.

Yes, it need a reference. But the reference can be to any token that fulfills the API. I am asking for an example where B have a pointer to any token, not just A specifically, and that B doesn't know about the actual instance A. Will there be such examples?

I'm in agreement with a couple commenters above, there is no need for this to be an EIP. If you want to design a mechanism for increasing/decreasing supply and use that feel free to do so and create a blog post, open source project, gist, etc. to get the word out for people to follow along. The purpose of an API EIP is to make it so contracts can talk to each other or to generic tooling without having any knowledge of each other. Token supply changes necessarily are trusted operations which means you can't apply them arbitrarily to any token contract. You must have a trusted relationship with the specific token you want to interact with, in which case you will know the API for increasing/decreasing supply. Also, I really can't think of a use-case for some sort of generic tooling around supply increases/decreases (which is what would benefit from an EIP like this).

EIPs are not the place for best-practices. They are the place for standardization of things that need (or greatly benefit from) standardization. EIPs should be reserved for problems that can't be or would be very difficult to solve without consistent standard across the ecosystem. Tokens, due to their proliferation and shared tooling, fall into this category but really only the bare basics for token interactions should be included.

I think there really needs to be some stronger arguments put forth as to why this should be an EIP.

How would these extensions be added to the smart contract at https://www.ethereum.org/token?

I've begun implementing an EIP621 token here: https://github.com/skmgoldin/EIP621Token

I need to add tests and documentation.

For whatever it's worth, I think unique Mint/Burn events would be better than hacking the Transfer event. For example, in the decreaseSupply function we're supposed to fire a Transfer event Transfer(from, 0, value). It is not uncommon for the 0 address to be used as a burn address or for sends to 0 to happen for any reason, and UIs/off-chain services should not necessarily interpret these to mean that supply has decreased.

Mint(to, value)
Burn(from, value)

@MicahZoltu

Token supply changes necessarily are trusted operations which means you can't apply them arbitrarily to any token contract.

what about this EIP implies these are public-facing functions? Of course "mint" is likely protected. All of these EIPs can't do more than define ABIs anyway, these are not even close to definitions of semantics

@MicahZoltu Which is absolutely terrible, I agree.

@nmushegian I was merely arguing that there is no need for an EIP for this. If you come up with a good pattern for minting/burning tokens in your contract then that is great, share it with others as a blog post, tutorial, re-usable contract, etc. There isn't value in standardizing the idea though, since it doesn't provide interoperability benefits (which is the point of standards).

As for Mint and Destroy events, I do think there is value in standardizing on this and I have said as much over in #223 and encourage others to support that.

I agree with that except it's that just such an obvious next step to try to define the analogous semantics and ABI for the actual operations

I may suggest using the Zeppelin Library that is ERC20 Compliant, they include the mint and burn within their contracts, and is easy to use when you run waffle.

This restricts a total supply to a single, immutable value, usually transferred to the contract creator.

I don't think this is true. At least the text of https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20-token-standard.md does not seem to me to require that totalSupply() not change over time.

I haven't read all of the comments yet, so I apologize if this is repetition.

So, I would advocate that requiring a creator limits the functionality of this API extension even though it's likely that it will be the most used pattern.

Why not just have the creator as an optional parameter? I think that should settle arguments for and against to include or not include a creator control parameter.

https://www.youtube.com/watch?v=OawrlVoQqSs

I'm personally in favour of keeping with generic naming (increase/decrease supply). "mint" seems skeuomorphic, not really apt anymore in this context.

@simondlr while mint and burn are skeuomorphic, they are less of a mouthful than increaseSupply and decreaseSupply, but that's not a big deal. As long as people understand that this is virtual money being created and destroyed (which they should given the context), not actual coins being minted or paper being burnt, I prefer the simplicity of mint and burn. When you mint you increase supply and when you burn you decrease supply, so the intent is the same. Create and destroy are also OK, but then it is unclear without context what it is that is being created or being destroyed.

@yudilevi

IMO these functions should throw upon failure as opposed to returning a flag.

Have you checked out the revert opcode that is now in effect as of Byzantium?

Hi guys,

I created my token using token factory but I sent them by accident to MEW address and not meta mask address - I didn't send eth to my contract address via meta mask so all my tokens got lost. I really like my token name and I would like to increase total supply but I don't know how. Could you please provide me with a short step by step instructions how to do that? You'd save my day :) Thank you, thank you very much in advance.

I'd like to bump this discussion. I'm working on a continuously mintable bonded curve token for use in a curation market and think it would benefit from a standardized API. Similar to Prediction Markets, much trading should be automated in these scenarios. Having a standard API that would provide handles for buying and selling into these markets would be essential.

Furthermore I think there is a distinction that needs to be made between increaseSupply/decreaseSupply and minting/burning. With a bonded curve token the price of the token is a function of the number of tokens in circulation. Selling tokens for the base denomination will destroy the token and decrease the supply. However there is also the scenario in which a user might want to (or be required to) send tokens to an unretrievable address like 0x0. This would raise the bottom price of the token by making those tokens unsellable and provide a degree of stability to the market. This seems closer to the scenario mentioned by @skmgoldin of "burning" tokens by sending them to an unretrievable address. In that case maybe increaseSupply and decreaseSupply should be used to do just that, whereas "burn" should continue being used as the act of removing from circulation. Alternatively one could be even more explicit with something like removeFromCirculation()

This is a courtesy notice to let you know that the format for EIPs has been modified slightly. If you want your draft merged, you will need to make some small changes to how your EIP is formatted:

• Frontmatter is now contained between lines with only a triple dash ('---')
• Headers in the frontmatter are now lowercase.

If your PR is editing an existing EIP rather than creating a new one, this has already been done for you, and you need only rebase your PR.

In addition, a continuous build has been setup, which will check your PR against the rules for EIP formatting automatically once you update your PR. This build ensures all required headers are present, as well as performing a number of other checks.

Please rebase your PR against the latest master, and edit your PR to use the above format for frontmatter. For convenience, here's a sample header you can copy and adapt:

---
eip: <num>
title: <title>
author: <author>
type: [Standards Track|Informational|Meta]
category: [Core|Networking|Interface|ERC] (for type: Standards Track only)
status: Draft
created: <date>
---

@alex-miller-0 are you still pursuing this or is it superseded with some other ERC?

@alex-miller-0 are you still pursuing this?

There has been no activity on this pull request for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

This pull request was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.