The First Cardstack Smart Contract Upgrade
What you should know
Cardstack’s Ethereum smart contract has been designed from the bottom up to be extensible and future-proof. Cardstack isn’t just using an off-the-shelf, run-of-the-mill ERC20 contract. Our smart contract is unlike any others in that it can evolve through upgrades.
We have now executed our first smart contract upgrade.
In this upgrade, we replaced our original “Version 1” token contract and ledger with a “Version 2” token contract and ledger. The V2 ledger replicates all token balances from the V1 ledger.
Summary
- The V1 token contract and ledger used “decimal 0.” The V2 token contract and ledger use “decimal 18.”
- Using decimal 18, we sent transactions from the V2 token contract to the V2 ledger to replicate all token balances from the V1 ledger.
- The balances from the V1 token contract and V1 ledger are still visible, but no longer usable.
- cardstack.eth will resolve to the V2 token contract address.
Keep on reading for full details.
Decimal 18
Our V1 token contract (0x1ed2…) and ledger used “decimal 0,” meaning the smallest possible unit was 1 CARD.
Since the TGE, we decided to change the token contract and ledger to “decimal 18,” which makes the smallest possible unit 1*10^18 CARD, and gives Cardstack Tokens the same level of divisibility as Ether (1 wei = 1*10^18 ETH).
This allows users to transact in fractional CARD tokens, ensuring the long-term utility of Cardstack Tokens.
The upgrade
In brief, Cardstack’s smart contract system works by using a “registry contract” to manage underlying ledger contract(s), token contract(s), and storage contract(s). (For more detail, read this writeup.)
The registry contract is also an ENS resolver, directing requests from cardstack.eth to the appropriate contract.
To upgrade any of the contracts (e.g. the token contract), we deploy a new version of that contract. The registry contract unbinds with the old version and binds with the new version.
For this upgrade, we deployed a new V2 token contract (0xb07e…) and ledger to replace the V1 token contract and ledger. Then the registry contract connected everything back together.
Replicating token balances
Because we changed the decimal system from 0 to 18 in this upgrade, we had to recreate our entire ledger using decimal 18.
To accomplish this, we sent transactions from the V2 smart contract to the V2 ledger, replicating all the token balances from the V1 ledger.
On the smart contract level, tokens on the V2 ledger go out to 18 more decimal places. This value does not represent a change in the amount of CARD — think of it as Cardstack tokens becoming 10¹⁸ times more high-resolution.
In this sense, the V2 token contract is like a “lens” that allows you to read the V2 ledger in normal units of CARD.
The balances from the V1 token contract and V1 ledger are still visible, but no longer usable.
Wallets that are connected to our V2 token contract will detect the decimal 18 system, and display balances and transactions in normal units of CARD.
However, if you are a developer and want to interact with our smart contract via JSON ABI or introspect our smart contract code directly, you will have to take into account the 18 decimals, as the raw balances in our V2 ledger now contain 18 additional decimal places.
cardstack.eth
Our upgradable smart contract system means that the our token will be located at a new Ethereum address after each upgrade.
Old token contracts (and ledgers, if applicable) will still be visible, but no longer usable.
For security and simplicity, we have registered cardstack.eth with Ethereum Name Service (ENS) to point directly to our registry smart contract, which will always resolve to our newest Cardstack Token Smart Contract address.
ENS allows contracts to be addressed using a human-readable phrase instead of the string of hexadecimal characters that comprise a raw token address.
Now you won’t have to worry about knowing our 42-character token address, or worrying if you have the most up to date one — it will always be located at cardstack.eth.
Next upgrade cycle: stable contract, living contract
For some third-party ERC20 functions, it is important to keep a stable token contract address, as some Ethereum-based services do not have underlying ENS resolver functionality.
That’s why our smart contract architecture allows for multiple token contracts working side by side, each with full access to the ledger contract.
We plan to keep our fully audited V2 token contract as our “stable” ERC20 token contract, forming a dependable bridge to third-party services that require standard integrations.
However, we plan to deploy an additional “living” ERC20 token contract that will work side-by-side with the stable contract, so that the Cardstack Framework can continue to gain upgrades without affecting third-party integrations.
Both the living contract and the stable contract will reflect token balances consistently. The living contract will include all the functionality of the stable contract.
For end users, cardstack.eth will resolve to the living contract.
Dashboard
We are updating our dashboard app to be display token balances correctly using the V2 token contract and V2 ledger.
We will be making lots of additional improvements to our dashboard as we continue to upgrade our smart contract. For example, in the near future we plan to add additional server side computation in order to display richer details about a user’s history and relationship to their tokens.
We will provide more details about dashboard updates soon.
Security Audit
Our V1 contract passed two security audits prior to the Token Generation Event. We have just completed a third security audit to ensure the security of our V2 token contract. There were no major changes or recommendations.
Batch A & B Tokens
Early Contributor (Batch A) and Pre-Allocation (Batch B) tokens have not yet been distributed. These tokens will be distributed prior to the token unlock, and will be distributed using our V2 token contract.
Read More
- Cardstack’s Upgradable Smart Contract, Explained
- Growing a Healthy Software Ecosystem by Lead Developer Ed Faulkner
- Running an Ethereum Cardstack Hub Application by Senior Blockchain Developer Hassan Abdel-Rahman
- The Cardstack White Paper
Get Involved
Join the discussion about Cardstack on our official Telegram channel: https://t.me/cardstack.
Important Reminders
- We will never, under any circumstances, solicit funds from you via email, private message, or social media.
- If you are in doubt or notice any suspicious activity, please message the admins in our official Telegram group: https://t.me/cardstack.
