Solidity
This page will cover setting up a local environment for working with Solidity. This is not required to deploy an ERC20 token, but in my experiencce it has been a good learning experience to set up these environments yourself, instead of using a provided service like Remix. That said, Remix is a really neat tool, and I would recommend maybe getting into some basic solidity there first and deploying a test contract to ropsten. For that process, I found a lot of information available online, so I won't cover it here, but here's my ERC20 token GitHub repository, feel free to use whatever code there might help you along the way. The code there may be more up-to-date then the code on this page, so there will probably be discrepancies from the screenshots and snippets seen here.
Once you deploy on Remix, if you still want to get a development environment and repository of your own setup, this page might be useful to you.
OpenZeppelin Documentation This is a great resource
OpenZeppelin ERC20 Decoumentation specific to the IERC20 interface I inherit in my token contract.
OpenZeppelin Contracts GitHub Useful for looking at how things are implemented
Remix ETH Web IDE You can use this Web IDE as an alternative to setting up a local development environment.
MetaMask
You will need the MetaMask browser extension and wallet. Google and install it onto your web browser. Be sure to save your mnemonic phrase. This goes for all wallets, but we will specifically need this phrase to deploy our contract.
Switch to the Ropsten test net within metamask, and visit the link below and enter your wallet address to give yourself free test ethereum. This is only for testing on the Ropsten network.
Ropsten ETH Faucet for testnet use only
You will need this test ETH to pay the transaction fees for deploying your contract when creating your ERC20 token. Don't skip this step, visit the link to the ropsten faucet above.
Custom Coins
You will only need to do this once you have your contract deployed
To get your custom token balances to show in metmask, you need to add a custom coin. Be sure you are on ropsten, or your test net of choice, and see the images below.
In your MetaMask wallet, click Add Token, and go to the Custom Token tab. Enter your contract address you recieved when deploying.
Click Add Tokens on the confimation screen, and they will appear in your wallet!
Project Setup
Solidity is the language used to create an ERC20 Token. This section will cover compilation of a contract on a local machine. If it compiles locally, it will deploy successfully. The section after this will cover deploying Solidity projects to a remote networks with Truffle. After that deploy is done, your token will be available on the Ropsten test net.
How to setup a Solidity project
First, we need to make a project directory and install everything we need. If you don't have git or npm, you'll need to install them first. We will also install the Truffle compiler -
mkdir /some/project/dir
cd /some/project/dir
git init // Git is useful. Use it as needed, or don't. I won't cover any git commands here.
npm init -y // Modify the generated package.json file, if needed
if you want to use OpenZeppelin, you will need to run the following command to install it, making it available to import in your contracts
npm install --save-dev @openzeppelin/contracts
Now, within a new contracts/contract-ERC20.sol file we can import the ETH ERC20 interface provided by OpenZeppelin -
import "@openzeppelin/contracts/token/ERC20/IERC20.sol"
Compiling Solidity With Truffle
We need to install the Truffle compiler -
npm install --save-dev truffle
The next steps will overwrite your contracts/ and test/ directories. If you have files there you want to keep, move or copy them somewhere else. After running the following initialization command, move them back, but keep any other additional files that Truffle has generated.
Run the following command to initialize a new Truffle project
npx truffle init
Check the truffle-config.js generated by npx truffle init, and modify your compiler version as needed. For me, all active settings in this config are seen below. This will work for compiling locally, but not on any remote public network. The next section will cover deploying to a remote network.
// truffle-config.js
module.exports = {
// Set default mocha options here, use special reporters etc.
mocha: {
},
// Configure your compilers
compilers: {
solc: {
version: "0.8.0", // <------- Modify your version if needed!
}
},
db: {
enabled: false
}
};
Be sure to move any contracts you have into the contracts/ directory, and any tests you have into the test/ directory. For my project, I have a simple network test and a single contract. For an example ERC20, check shaunrd0/karma The screenshot below of my compilation output should provide some insight into how my project is structured.
Now, when we run the following command truffle will compile all contracts in the contracts/ directory.
npx truffle compile
Now that our contract compiles, we need to configure truffle to connect to a testnet. The next section will cover doing this.
Deploy Truffle to Public Networks
Deploying Truffle to Remote Networks
Install hdwallet-provider for Truffle. We will use this to configure our wallet address when deploying the contract.
npm install --save-dev @truffle/hdwallet-provider
Grab your alchemy API key first, because you will need it! Once registered, the Alchemy dashboard will let you create a new project. Name it whatever you want, put it on whatever network you want just make sure this matches the network you put in your config below. Oncce you create the app, click View Key in the screenshot below. This can be found on the dashboard for the application itself. Copy the HTTPS key provided.
Now you're ready to look at your config. Add your mnemonic attached to your MetaMask wallet as the phrase, and add your Alchemy API key as the providerOrUrl -
// truffle-config.js
const HDWalletProvider = require('@truffle/hdwallet-provider');
module.exports = {
networks: {
ropsten: {
provider: () => new HDWalletProvider({
mnemonic: {
phrase: 'word word word word word word word word word word word word word word'
},
providerOrUrl: "https://eth-ropsten.alchemyapi.io/v2/xxxxxxx_YOUR_ALCHEMY_API_KEY_xxxxxxxx",
chainId: 3 // <--- Don't forget this! For me, excluding this line caused errors. cainId 3 is for ropsten
}),
network_id: 3, // Ropsten's id
gas: 5500000, // Ropsten has a lower block limit than mainnet
confirmations: 2, // # of confs to wait between deployments. (default: 0)
timeoutBlocks: 200, // # of blocks before a deployment times out (minimum/default: 50)
skipDryRun: true // Skip dry run before migrations? (default: false for public nets )
},
},
// Set default mocha options here, use special reporters etc.
mocha: {
},
// Configure your compilers
compilers: {
solc: {
version: "0.8.0", // <------- Modify your version if needed!
}
},
db: {
enabled: false
}
};
Now we are ready to test that we can connect to the ropsten network, and verify our wallet connection at the same time.
npx truffle console --network rinkeby
This should open a console prompt, type await web3.eth.getBalance(accounts[0]), followed by accounts. If you get a response, things are configured correctly! You should notice your wallet address is listed after entering the second accounts command.
One final step before we can deploy our contract to ropsten. Create the file migrations/2_deploy.js, and add the contents below. Be sure to pay attention to comments and change the values as needed.
// migrations/2_deploy.js
// Set variable name Karma to your whatever you named your token
const Karma = artifacts.require("Karma"); // <-- Set string in call to articfacts.require to your token name
module.exports = function (deployer) {
deployer.deploy(Karma); // <----- Use const variable declared above in call to deployer.deploy
};
Now, we are finally ready to deploy our contract. run this final command to deploy to ropsten testnet.
npx truffle migrate --network ropsten
This may take a while, but when it completes you should see the output below
We have deployed Karma to the ETH ropsten testnet! You can take the contract address and view it on EtherScan. Here's the link for the contract we deployed in this section. All of my source code for this token's contract can be found there. It is useful, once you have a contract deployed or some transactions to look at, to explore etherscan a bit to see how things are organized. Notice on my contract page, you can see that 1 Billion Karmas were minted and sent to my wallet address, since I am the contract owner, and our contrract constructor looks like this -
/**
* Constrctor function
*
* Initializes contract with initial supply tokens to the creator of the contract
*/
constructor()
{
name = "Karma"; // Name of the token
symbol = "KRMA"; // Abbreviation of the token
decimals = 18; // Number of decimals that can be used to split token
// FORMAT: <SUPPLY><DECIMALS>
// Where SUPPLY is the number of coins in base 10 decimal notation
// And DECIMALS is a trailing number of 0's; Count must match `decimals` value set above
// 1000 000 000 000000000000000000 == 1 billion total supply;
// + trailing 0's represent the 18 decimal locations that can be used to send fractions
_totalSupply = 1000000000000000000000000000;
// Set the remaining balance of the contract owner to the total supply
balances[msg.sender] = _totalSupply; // msg.sender is the calling address for this constructor
// Transfer the total supply to the contract owner on initialization
emit Transfer(address(0), msg.sender, _totalSupply); // address(0) is used to represent a new TX
}
This constructor only happens wheen the contract is deployed. Future updates will not remint these tokens and provide me with 1B more or reset the supply.
Upgradeable ERC20 Contracts
Once I deployed a test contract and become familiar with etherscan, I quickly realized the only way to update the contract was to effectively deploy a new contract and direct all clients to the new address on ropsten..
But this just didn't seem like it would scale well, and since I was preparing to deploy Karma to ETH mainnet I decided to look into using the proxy pattern to deploy a ProxyAdmin which would own a TransparentUpgradeableProxy - this TransparentUpgradeableProxy points to a contract address on the ethereum network that implements the functionality of Karma. Laying out the project this way, things make sense and I provide myself with the tools I need to upgrade the contracts without any client needing to redirect their calls to Karma.
To do this, I followed guides provided by OpenZeppelin. I will list some useful resources I found below
Upgradeable Contracts For Truffle
First, we need to install @openzeppelin/contracts-upgradeable to your project by running the following command -
npm i --save-dev @openzeppelin/contracts-upgradeable
If this is your first time deploying using @openzeppelin/truffle-upgrades, you may notice an additional deploy of a ProxyAdmin that automatically happens. This ProxyAdmin is owned by your wallet address, and you can use it to manage the proxied contracts you deploy in the future. Here is my ProxyAdmin - you'll notice you have the following functions available in the write contract section on etherscan
If we click Connect to Web3, metamask will prompt us to choose an account to connect to. In order for this to work, your metamask account must be on the same network as the contract you are viewing.
If you try to connect to my ProxyAdmin, you'll notice you lack permissions to run any of the functions in Write Contract. It would be the same for me if I tried to connect to your ProxyAdmin. This protects our contracts and allows only the owner of the ProxyAdmin to manage subsequent contracts.
For now, it is enough to know this contract exists, when it is created, and what it is for. Later on, we will use this contract to upgrade our proxy implementation.
For deploying upgradeable contracts, we can use the same truffle.config.js as we did in the sections above.
TODO: MAKE NEW BRANCH FOR MASTER (simple example), MERGE upgradeable with master A complete example of an upgradeable token can be found at shaunrd0/karma
Contracts
Let's say we have the following contract
// Copyright [2021] - [2021], [Shaun Reed] and [Karma] contributors
// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;
// ----------------------------------------------------------------------------
// Import ERC Token Standard #20 Interface
// ETH EIP repo: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
// ----------------------------------------------------------------------------
import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
// ----------------------------------------------------------------------------
// Karma Contract
// ----------------------------------------------------------------------------
contract Karma is Initializable, ERC20Upgradeable
{
function initialize(string memory name, string memory symbol, uint256 initialSupply) public virtual initializer {
__ERC20_init(name, symbol);
_mint(_msgSender(), initialSupply);
}
}
And we want to add an additional function, isToken, just to test that our upgrades are working. This function simply returns true, since Karma is a token. Notice the contract above does not define or declare this function.
To upgrade Karma, we add the function below, and rename the contract to KarmaV2
// Copyright [2021] - [2021], [Shaun Reed] and [Karma] contributors
// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;
// ----------------------------------------------------------------------------
// Import ERC Token Standard #20 Interface
// ETH EIP repo: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
// ----------------------------------------------------------------------------
import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
// ----------------------------------------------------------------------------
// Karma Contract
// ----------------------------------------------------------------------------
contract KarmaV2 is Initializable, ERC20Upgradeable
{
function initialize(string memory name, string memory symbol, uint256 initialSupply) public virtual initializer {
__ERC20_init(name, symbol);
_mint(_msgSender(), initialSupply);
}
function isToken() public returns (bool)
{
return true;
}
}
Now we have defined all the contracts we need for an upgradeable ERC20 token. In the next section, we will define the needed Migrations to deploy the entire stack to ETH ropsten test network.
Migrations
We will need to create the following migrations, the ./migrations/ folder inside your project directory. Each file has a comment with the required name. It is important to prefix these migrations with 1_, 2_, 3_, etc - as Truffle uses this order to track migration status and pick up where it left off should a subsequent migration be interrupted or fail.
// migrations/1_initial_migration.js
const Migrations = artifacts.require("Migrations");
module.exports = function (deployer) {
deployer.deploy(Migrations);
};
// migrations/2_deploy_karma.js
const Karma = artifacts.require('Karma');
module.exports = async function (deployer) {
await deployer.deploy(Karma);
};
// migrations/3_deploy_proxy.js
const Karma = artifacts.require('Karma');
const { deployProxy } = require('@openzeppelin/truffle-upgrades');
module.exports = async function (deployer) {
await deployProxy(
Karma,
['Karma', 'KRMA', '1000000000000000000000000000'],
{ deployer, initializer: 'initialize' }
);
};
// migrations/4_upgrade_karma.js
const { upgradeProxy } = require('@openzeppelin/truffle-upgrades');
const Karma = artifacts.require('Karma');
const KarmaV2 = artifacts.require('KarmaV2');
module.exports = async function (deployer) {
const existing = await Karma.deployed();
await upgradeProxy(existing.address, KarmaV2, { deployer });
};
Deploying and Verifying
Now, having defined the above contracts and migrations, we are ready to deploy to a public test network. Run npx truffle migrate --network ropsten to deploy to ETH's ropsten testnet, or replace ropsten with the testnet of your choice. The output from my deploy can be seen below. Note that there is no deploy for my ProxyAdmin since it already exists, and each account can use one ProxyAdmin to own several proxies.
[kapper@kubuntu-vbox karma-new]$npx truffle migrate --network ropsten
Compiling your contracts...
===========================
> Compiling ./contracts/Migrations.sol
> Compiling ./contracts/karma-1-ERC20.sol
> Compiling ./contracts/karma-2-ERC20.sol
> Compiling ./contracts/karma-3-ERC20.sol
> Compiling @openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/extensions/IERC20MetadataUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol
> Compilation warnings encountered:
Warning: Function state mutability can be restricted to pure
--> /home/kapper/Code/karma-new/contracts/karma-2-ERC20.sol:24:5:
|
24 | function isToken() public returns (bool)
| ^ (Relevant source part starts here and spans across multiple lines).
> Artifacts written to /home/kapper/Code/karma-new/build/contracts
> Compiled successfully using:
- solc: 0.8.0+commit.c7dfd78e.Emscripten.clang
Starting migrations...
======================
> Network name: 'ropsten'
> Network id: 3
> Block gas limit: 8000000 (0x7a1200)
1_initial_migration.js
======================
Deploying 'Migrations'
----------------------
> transaction hash: 0x13d88d460d187ef446f48ae52984a8387b06e20ecc3887dbf52a2a958fa7ea29
> Blocks: 1 Seconds: 12
> contract address: 0xeB3c4405174931CDDd59E5edfAB03fc46100Ec6D
> block number: 10179266
> block timestamp: 1620248502
> account: 0x9F688c4D72356E230E9db8fA58f6cf981C16E63f
> balance: 1.74300232575
> gas used: 245600 (0x3bf60)
> gas price: 20 gwei
> value sent: 0 ETH
> total cost: 0.004912 ETH
Pausing for 2 confirmations...
------------------------------
> confirmation number: 1 (block: 10179267)
> confirmation number: 2 (block: 10179268)
> Saving migration to chain.
> Saving artifacts
-------------------------------------
> Total cost: 0.004912 ETH
2_deploy_karma.js
=================
Deploying 'Karma'
-----------------
> transaction hash: 0xa21e6335e217cf4056541f842957e8370009c19889f8c1455dc0de4b11407ea3
> Blocks: 0 Seconds: 24
> contract address: 0xB2425Ea8087233A8cD4140E1480F60EB57C133aE
> block number: 10179270
> block timestamp: 1620248640
> account: 0x9F688c4D72356E230E9db8fA58f6cf981C16E63f
> balance: 1.71041050575
> gas used: 1583678 (0x182a3e)
> gas price: 20 gwei
> value sent: 0 ETH
> total cost: 0.03167356 ETH
Pausing for 2 confirmations...
------------------------------
> confirmation number: 1 (block: 10179271)
> confirmation number: 2 (block: 10179272)
> Saving migration to chain.
> Saving artifacts
-------------------------------------
> Total cost: 0.03167356 ETH
3_deploy_proxy.js
=================
Deploying 'TransparentUpgradeableProxy'
---------------------------------------
> transaction hash: 0x774ddb93ed3b219202195821e43939f031320d441cf78e8bbf497724b06f2b05
> Blocks: 1 Seconds: 52
> contract address: 0xdCDA9d33Eb6eEf5C748743Bb1e2B7FBFBc500904
> block number: 10179275
> block timestamp: 1620248756
> account: 0x9F688c4D72356E230E9db8fA58f6cf981C16E63f
> balance: 1.69552372575
> gas used: 715526 (0xaeb06)
> gas price: 20 gwei
> value sent: 0 ETH
> total cost: 0.01431052 ETH
Pausing for 2 confirmations...
------------------------------
> confirmation number: 1 (block: 10179277)
> confirmation number: 2 (block: 10179278)
> Saving migration to chain.
> Saving artifacts
-------------------------------------
> Total cost: 0.01431052 ETH
4_upgrade_karma.js
==================
> Saving migration to chain.
-------------------------------------
> Total cost: 0 ETH
5_upgrade_karma.js
==================
Deploying 'KarmaV3'
-------------------
> transaction hash: 0x9badc27d60018e0aa2892260da8a2b614295627f153cc7d04018b726c19c59ff
> Blocks: 1 Seconds: 49
> contract address: 0x36DB5d3224995Ea7fd9EC61Ab6D7eeFe47ab1717
> block number: 10179289
> block timestamp: 1620248870
> account: 0x9F688c4D72356E230E9db8fA58f6cf981C16E63f
> balance: 1.66117366575
> gas used: 1621063 (0x18bc47)
> gas price: 20 gwei
> value sent: 0 ETH
> total cost: 0.03242126 ETH
Pausing for 2 confirmations...
------------------------------
> confirmation number: 1 (block: 10179295)
5_upgrade_karma.js
==================
Deploying 'KarmaV3'
-------------------
> transaction hash: 0x3c446b4ac1e647d3145b5e187e03d181f5de101fe568271e6ded27c90fe1ca0e
> Blocks: 0 Seconds: 12
> contract address: 0x9e3Be3194de7A033f82e7aC121b1036Dd817f4c7
> block number: 10179297
> block timestamp: 1620248992
> account: 0x9F688c4D72356E230E9db8fA58f6cf981C16E63f
> balance: 1.62875240575
> gas used: 1621063 (0x18bc47)
> gas price: 20 gwei
> value sent: 0 ETH
> total cost: 0.03242126 ETH
Pausing for 2 confirmations...
------------------------------
> confirmation number: 1 (block: 10179298)
> confirmation number: 2 (block: 10179299)
> Saving migration to chain.
> Saving artifacts
-------------------------------------
> Total cost: 0.03242126 ETH
Summary
=======
> Total deployments: 1
> Final cost: 0.08331734 ETH
For quick access, here's links to each contract deployed above on EtherScan:
(My) ProxyAdmin TransparentUpgradeableProxy Karma (V1) KarmaV2 KarmaV3
And, the resulting token on etherscan is found here - Karma Token
Here's the hard part
:(
Verification of contracts on etherscan is not so straight-forward the first time around, or at least it wasn't for me. Head over to etherscan, make sure you are viewing the correct network, and enter the deployed contract address for Karma (Or, in your case, enter the contract address that replaced Karma)
Here is the contract page for Karma that we deployed on ropsten in the output above. Notice the verification status of Karma is Verified. Compare this page to the same page on your contract. The Karma contract should allow you to call functions within the read contract and write contract pages, while an unverified contract will not provide access to these functions. So, we need to verify our contracts on etherscan. When we try to view an unverified contract, we will be presented with a link to verify that looks similar to the page below.
Click Verify and Publish, and you will see a page that asks for several options you configured when setting up your project and writing your contracts. Select the options that match your token. My options for Karma are seen in the screenshot below. Please disregard the contract address in this image, as it does not reflect any address we have linked to on this page. The compiler type, version, and license are all still relevant to Karma.
Now, we will be presented with a screen that asks up to input the source code for the contract. Including other contracts is not allowed here, and to verify simply the easiest way is to 'flatten' your .sol contract manually (and carefully).
At each import statement, recursively, simply copy-paste the code from the import in-place of the import statement itself. Remove any SPDX-License-Identifier beyond the initial SPDX at the top of your contract. Be sure not to leave any imports in the flattened contract, or verification will fail. If your contracts use arguments in the constructor, you will have to research ABI format for inputting your constructor arguments. Karma does not use any arguments in the constructor, so there is no need for me to do this in my example.
Here is a pastebin example of my input that verified KarmaV1 Here is a pastebin example of my input that verified KarmaV2 Here is a pastebin example of my input that verified KarmaV3
Once the verification of these implementation contracts is complete, we are ready for the final step - verifying the TransparentUpgradeableProxy. To do this, navigate to the relative contract address on etherscan for your deploy. For my example, the contract for the TransparentUpgradeableProxy can be found at this link
This part is very easy to miss on etherscan, and wraps up all the work we've done so far
In the image below, click More Options and then click Is this a proxy? in the context menu that pops up.
This will lead you to the following verification page, which automatically fills out the contract address of the TransparentUpgradeableProxy and allows you to submit it for verification as a proxy contract. Click Verify, and if all has been done correctly, the TransparentUpgradeableProxy will verify with the message below!
That's it! We have deployed an upgradeable ERC20 token on the Ethereum ropsten testnet. After verifying your TransparentUpgradeableProxy, you should notice the addition of the Read as Proxy and Write as Proxy options when viewing the TransparentUpgradeableProxy on etherscan, as seen in the image below.
We should notice that the implementation contract referred to in bold is the address or the most recent Karma, which is KarmaV3. We can be sure of this by both the contract address and the addition of the isToken and getAddress functions seen under Read as Proxy. Pretty cool!
We now have a single contract that can refer to the most recent implementation we have defined on the ropsten testnet. Hopefully, some of this information has helped you to deploy your own token.