Cardstack’s Upgradable Smart Contract, Explained
Future-proofing the Cardstack Project
Cardstack’s Ethereum smart contract is more advanced than most ERC20 smart contracts. We built our contract to be upgradable and extensible, in order to future-proof the Cardstack Project.
Cardstack’s Senior Blockchain Developer Hassan Abdel-Rahman has provided a thorough technical writeup of our upgradable contract. We also blogged about our first smart contract upgrade, conducted in June 2018.
This is an explainer in plain English about how our smart contract works.
The Cardstack Smart Contract
The first thing you should know is that the Cardstack Smart Contract is made of multiple contracts. Let’s meet them:
Registry contract
This is the “master” contract that binds all the other contracts together. It is the authority on which contracts are assigned as the ledger contract(s), token contract(s), and storage contract(s).
The registry contract can unbind any of these contracts and bind with new contracts.
To upgrade any of the contracts (e.g. the token contract), we deploy a new version of that contract, which will have a different address. The registry contract unbinds with the old contract and binds with the new contract.
In sum, the new contract replaces the old contract. Then the registry contract reconnects everything.
ENS resolver
In addition to managing underlying contracts, the registry contract is our ENS resolver. As requests come through cardstack.eth, the registry contract exposes the appropriate contract(s) underneath.
For example, if I am a user and I want to find the latest Cardstack Token Smart Contract address, I can visit cardstack.eth and the registry contract will point me to the correct token contract.
Or, if a decentralized application wants to request storage from a Cardstack storage contract, it can send a request to cardstack.eth and the registry contract will point the dApp to a storage contract.
Storage contract
A storage contract acts a bucket, carrying the state from one version of our contract to the next. This includes everything in a contract that isn’t related to a token balance. For example: the name of the token, contribution caps, whitelisted addresses, ERC20 third-party contract allowances, etc.
A storage contract can also store a ledger contract — or structures of multiple ledger contracts.
Ledger contract
Cardstack Token balances are stored on a ledger contract, which is a modified form of a storage contract. A ledger contract contains records of addresses’ token balances up to 18 decimal places, but has no functionality of its own.
A ledger contract can be managed by one or more designated token contract.
Token contract
The Token Smart Contract may interact with the ledger contract, making token transactions and other ERC20 functions possible.
Our current smart contract has gone through three rounds of rigorous security audits. We recently completed the first upgrade of our token contract, changing the decimal system from 0 to 18 (read about the change here).
To maintain consistency, Our ENS address cardstack.eth will always expose the most updated version of the Cardstack Token Smart Contract to an end user.
For security and simplicity, you should always use the ENS address to locate our most current token contract address.
Next upgrade cycle: stable token contract, living token 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 can 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 feature upgrades without affecting third-party integrations.
Both the living contract and the stable contract will reflect token balances consistently since they both point to the same underlying ledger contract. The living contract will include all the functionality of the stable contract.
For end users, cardstack.eth will resolve to the living contract.
Notes on this approach
We have elected not to use a proxy pattern used in some smart contracts, including those from the OpenZeppelin open source project, due to potential security vulnerabilities our development and audit teams identified. (As Solidity matures and the tools and strategies for upgrading contracts evolve, we may revisit this decision.)
Our approach optimizes our ability to expand the scope and feature set of the living smart contract, without introducing too much complexity in the stable contract.
If the token standards in Ethereum evolve significantly, many projects including Cardstack, as well as projects using the proxy pattern, will likely have to upgrade the ABI signature of our token contract. In such a case, we would work with the integration teams of third-party services as if we were deploying a new version of the full node for a non-Ethereum-based blockchain.
For end users
Because our smart contract will undergo periodic upgrades, you should always use the ENS address cardstack.eth to locate our token contract address.
When Cardstack tokens are unlocked, we will always give advance notice about smart contract upgrades. We will also announce the moment we initialize and complete each upgrade.
During an upgrade, token balances may not be fully up-to-date. Transactions may also be rejected. Please be patient while a contract update is underway.
To make sure you receive the latest updates, follow Cardstack on our various platforms: (Telegram, Twitter, Medium, Newsletter, Website)
Read More
- The Future of Cardstack: A Conversation with Chris Tse and Huoxing Caijing
- Growing a Healthy Software Ecosystem by Lead Developer Ed Faulkner
- Developer Blog: Card UI
- 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.
