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.

V2 token contract and ledger replaces V1 token contract and ledger.

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.