Quando aprendemos os fundamentos da blockchain, que você confere neste artigo aqui, uma das primeiras coisas que aprendemos é que ela é imutável. Isso não impede de novas informações serem adicionadas, mas sim de que informações anteriores não podem ser alteradas, o histórico se mantém eterno. Da mesma forma, quando estamos programando para uma blockchain, os nossos algoritmos/programas que chamamos de Smart Contracts (que você aprende o básico aqui) também não podem ser alterados, apenas podemos publicar novos smart contracts, com novos endereços.
Isso quer dizer que você pode adicionar novos smart contracts na blockchain, incluindo novas versões do mesmo, mas que jamais poderá excluir ou modificar um já existente. E essa frase coloca muito medo nos programadores Solidity pois caso você suba uma versão do contrato com um bug ou vulnerabilidade, isso quer dizer que ela ficará na blockchain para sempre. E sim, isso é verdade.
Apesar disso, claro, existem medidas de contorno que você pode fazer. Uma delas seria avisar todo mundo que usa este smart contract bugado a desconsiderá-lo e passar a usarem somente o novo que você publicou com o bug corrigido. Mas nem sempre isso é viável ou desejável. O ideal é que você, já na concepção do smart contract, crie algum mecanismo que permita a atualização do seu smart contract posteriormente.
#1 – Opções de Atualização
A opção número um é a que citei antes: desconsidere o endereço antigo do contrato e passe a usar somente o novo. Ponto. Simples e direto mas que geralmente causa muitos problemas se seu smart contract é de uso público como uma DEX ou é uma criptomoeda ERC-20 com vários holders. Se for o segundo caso, ainda dá para contornar: você pode publicar um contrato de migração para fornecer tokens da nova moeda na mesma quantidade que os holders já possuíam na moeda antiga.
A opção número dois é você ter variáveis de estado e funções administrativas para permitir ajustes sem a necessidade de um novo deploy. Isso é fácil de fazer e perfeitamente possível em contratos simples. Mas simples mesmo, onde os bugs sejam de valores errados, inconsistências nos dados, etc. Nada que algumas funções sets definidas para o administrador usar não resolvam.
Mas para qualquer outra situação mais complexa o caminho é usar algum padrão de contratos atualizáveis (upgradeable contracts). Existem duas soluções muito famosas no mercado: os proxies e os adapters.
Os adapters são a solução mais simples, embora não sejam as melhores em diversos cenários. Eu explorei bastante um modelo de Adapter neste outro tutorial e resumidamente, você deve criar um contrato de adapter e um de implementação. No contrato de adapter você tem o endereço de onde está a implementação atual e funções administrativas para mudar isso. Além disso, o adapter expõe as funções que podem ser chamadas da implementação, delegando essas chamadas ao contrato de implementação correto conforme configurado previamente.
Tudo funciona bem do ponto de vista lógico, mas do ponto de vista de dados, eles ficam armazenados na implementação. Assim, caso você venha a mudar, eles serão perdidos e você terá de fazer algum plano de migração ou preparação. Assim, o pattern Adapter atende bem soluções de contratos que não tenham dados sensíveis e/ou que não possam ser migrados.
A solução perfeita para os demais cenários é usar o padrão proxy, que iremos explorar neste tutorial de hoje.
#2 – Proposta de Solução
A proposta que considero mais interessante para os cenários descritos é do pattern Proxy. À primeira vista um proxy e um adapter são idênticos e para o usuário eles são mesmo. A diferença é que um proxy possui um contrato Proxy que serve como conta, como storage e que delega todas as chamadas de funções a outro contrato, chamado de lógico. Assim, ao longo do tempo você pode atualizar seu contrato lógico sem perder fundos ou dados, apenas configurando o proxy para apontá-lo corretamente. Isso tudo sem o cliente nem sonhar que estão rolando atualizações.
Existem diversas implementações de proxies no mercado, sendo a imagem acima apenas uma simplificação comum para entendimento.
Por exemplo, existem os proxies transparentes que seguem a ERC-1967. Esta é uma abordagem mais pesada e complexa, mas que permite maior flexibilidade e poucas adaptações nos contratos. Já os UUPS (Universal Upgradeable Proxies Standard ou Padrão de Proxies Atualizáveis Universais) são documentados na ERC-1822 e são mais leves e simples, mas exigem mais customizações no contrato original que você deseja tornar upgradeable. Independente da abordagem escolhida, existem dois conceitos fundamentais da linguagem Solidity que são explorados e compartilhados por todos proxies:
- Quando uma chamada de função é feita a um contrato e ele não possui a mesma, uma função de fallback é chamada no lugar. Você pode escrever um fallback personalizado para lidar com estes cenários, como por exemplo para redirecionar estas chamadas a contratos de implementação.
- Toda vez que um contrato A delega uma chamada a outro contrato B, ele executa o código do contrato B, mas no contexto do contrato A. Isto significa que msg.value e msg.sender serão mantidos e que toda alteração no storage impactará o contrato A apenas.
Estes dois conceitos são a chave para você entender como proxies funcionam, independente do pattern escolhido. Para ajudar a ilustrar isso, considere o proxy abaixo. Ele não segue praticamente nenhum padrão, é apenas um exemplo simples e didático para entender minimamente como funciona. Mais à frente faremos um funcional.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 |
// SPDX-License-Identifier: MIT pragma solidity ^0.8.24; contract Proxy { bytes32 private constant _ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103; bytes32 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; constructor() { bytes32 slot = _ADMIN_SLOT; address _admin = msg.sender; assembly { sstore(slot, _admin) } } function admin() public view returns (address adm) { bytes32 slot = _ADMIN_SLOT; assembly { adm := sload(slot) } } function implementation() public view returns (address impl) { bytes32 slot = _IMPLEMENTATION_SLOT; assembly { impl := sload(slot) } } function upgrade(address newImplementation) external { require(msg.sender == admin(), "admin only"); bytes32 slot = _IMPLEMENTATION_SLOT; assembly { sstore(slot, newImplementation) } } function _delegate() private { assembly { let _target := sload(_IMPLEMENTATION_SLOT) calldatacopy(0x0, 0x0, calldatasize()) let result := delegatecall( gas(), _target, 0x0, calldatasize(), 0x0, 0 ) returndatacopy(0x0, 0x0, returndatasize()) switch result case 0 { revert(0, 0) } default { return(0, returndatasize()) } } } fallback() external payable { _delegate(); } receive() external payable { _delegate(); } } |
A primeira coisa que você vê neste proxy são duas constantes, uma é a posição no storage do contrato onde armazenaremos o endereço do contrato de implementação e em outro é o endereço do owner/admin do contrato (falei sobre isso nesse artigo). Essas constantes são endereços fixos definidos na ERC-1967 e isso é necessário porque o contrato de proxy, além de rotear as requisições para a implementação serve como storage para os dados do contrato e a fim de evitar colisões, usa sempre as mesmas áreas de storage para estas informações essenciais que devem ser as únicas no seu estado.
Depois temos o constructor onde descobrimos o owner do contrato e armazenamos ele no endereço definido anteriormente. Repare que fazemos isso com código assembly, pois somente desta forma conseguimos a precisão no armazenamento dos dados que precisamos. Depois as duas funções seguintes, praticamente idênticas, usam de assembly para ler os mesmos endereços a fim de retornar os valores do admin e da implementação.
A função seguinte, upgrade, serve para atualizar o endereço da implementação, usado quando o contrato for atualizado e o proxy precisar redirecionar as mensagens para outro endereço. Novamente usamos assembly aqui para o armazenamento da informação, mas é na função _delegate que a maior complexidade do pattern é encontrada pois usando assembly nós redirecionamos todos os dados recebidos em uma requisição para outro contrato à nossa escolha na blockchain, com um comando chamado delegatecall. Essa função _delegate é chamada sempre que uma requisição ao proxy não encontre uma função de mesmo nome, caindo por padrão nas funções de fallback ou de receive, ao final do proxy.
Assim, com um proxy parecido com esse, é possível trocar o contrato de implementação ao longo do tempo de forma transparente para os usuários pois todos os dados e saldo ficam no proxy. No entanto, cuidados devem ser tomados com esta abordagem, como por exemplo com as alterações que você realizar: jamais remova variáveis de estado, não as renomeie ou mude a ordem das mesmas no contrato de implementação, pois isto pode fazer com que o storage do proxy seja sobrescrito. O ideal é apenas adicionar novas variáveis e quando precisar mudar valores das mesmas, o faça sempre dentro de funções, nunca no corpo do contrato.
#3 – Projeto com HardHat
Você deve ter reparado que a solução é de um nível bem baixo, usando bastante Assembly, o que torna um risco elevado de aplicar esse pattern. Pensando nisso, a solução que recomendo para implementar tal solução é usar os contratos da OpenZeppelin para isso. Eles fazem um trabalho incrível fornecendo contratos que podem ser usados como base, incluindo do pattern Proxy.
Sendo assim, para exercitarmos o pattern Proxy vamos criar um projeto de exemplo no HardHat e usar a OpenZeppelin e seus contratos atualizáveis. Porque HardHat e não no Remix? Porque o Remix não tem suporte a proxies transparentes.
Este não deve ser seu primeiro projeto com HardHat, pois não introduzirei o toolkit. Caso seja o seu caso, conheça-o neste tutorial. Crie um projeto normalmente e depois instale as dependências que vamos usar.
|
1 2 3 |
npm i dotenv @openzeppelin/contracts-upgradeable @openzeppelin/hardhat-upgrades |
A saber:
- DotEnv: para gerir configurações de ambiente;
- @openzeppelin/contracts-upgradeable: para os contratos-base atualizáveis;
- @openzeppelin/hardhat-upgrades: plugin para fazer deploy do proxy e atualizações da implementação de maneira facilitada;
Agora crie o .env para configurarmos as variáveis de ambiente que vamos usar.
|
1 2 3 4 5 6 |
SECRET=<suas 12 palavras da frase mnemônica aqui> API_KEY=<sua API Key da EtherScan> RPC_URL=https://polygon-mumbai.infura.io/v3/4458cf4d1689497b9a38b1d6bbf05e78 CHAIN_ID=80001 |
No exemplo acima eu deixei configurado para a Testnet da Polygon (chamada Mumbai). Se esse RPC não funcionar, você pode providenciar um gratuito para você em provedores como Infura. Não esqueça de criar uma API Key no site polygonscan.com para podermos verificar os contratos.
Agora vamos ao hardhat.config.ts para configurá-lo com estas variáveis e o plugin de upgrades.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
import { HardhatUserConfig } from "hardhat/config"; import "@nomicfoundation/hardhat-toolbox"; import "@openzeppelin/hardhat-upgrades"; import dotenv from 'dotenv'; dotenv.config(); const config: HardhatUserConfig = { solidity: "0.8.24", networks: { mumbai: { url: process.env.RPC_URL, chainId: parseInt(`${process.env.CHAIN_ID}`), accounts: { mnemonic: process.env.SECRET } } }, etherscan: { apiKey: process.env.API_KEY } }; export default config; |
Agora vamos criar o nosso Contrato.sol, inicialmente configurado no site OpenZeppelin Contracts como Ownable e Upgradeability Transparent.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
// SPDX-License-Identifier: MIT pragma solidity ^0.8.24; import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; contract MyContract is Initializable, OwnableUpgradeable { /// @custom:oz-upgrades-unsafe-allow constructor constructor() { _disableInitializers(); } function initialize() initializer public { __Ownable_init(msg.sender); } } |
E depois ajustando para adicionar algumas funcionalidades próprias e mudança no nome.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
// SPDX-License-Identifier: MIT pragma solidity ^0.8.24; // Uncomment this line to use console.log // import "hardhat/console.sol"; import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; contract Contrato is Initializable, OwnableUpgradeable { string private message; /// @custom:oz-upgrades-unsafe-allow constructor constructor() { _disableInitializers(); } function initialize() initializer public { __Ownable_init(msg.sender); message = "Hello world"; } function getMessage() public view returns (string memory) { return message; } function setMessage(string memory newMessage) public { message = newMessage; } } |
Ponto importante: jamais inicialize variáveis no corpo do contrato, sempre o faça dentro de funções. Além disso, não coloque nada importante dentro do constructor, ao invés disso use a função initialize. Tudo isso por causa dos detalhes de baixo nível em Assembly que nós não iremos estudar a fundo.
Agora que temos o contrato codificado, é hora de escrever nossos testes unitários no Contrato.test.ts.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
import { loadFixture } from "@nomicfoundation/hardhat-network-helpers"; import { expect } from "chai"; import { ethers, upgrades } from "hardhat"; describe("Contrato Proxy", function () { async function deployFixture() { const [owner, otherAccount] = await ethers.getSigners(); const Contrato = await ethers.getContractFactory("Contrato"); const contract = await upgrades.deployProxy(Contrato); const contractAddress = await contract.getAddress(); return { contract, contractAddress, owner, otherAccount }; } it("Should set message", async function () { const { contract } = await loadFixture(deployFixture); await contract.setMessage("Hello LuizTools") expect(await contract.getMessage()).to.equal("Hello LuizTools"); }); it("Should upgrade and set message", async function () { const { contract, contractAddress } = await loadFixture(deployFixture); await contract.setMessage("Hello New LuizTools"); const Contrato = await ethers.getContractFactory("Contrato"); const newContract = await upgrades.upgradeProxy(contractAddress, Contrato); expect(await newContract.getMessage()).to.equal("Hello New LuizTools"); }); }); |
Aqui vale uma explicação com relação à função deployFixture. Embora ela não seja novidade aos desenvolvedores que usam HardHat, ela usa do plugin upgrades da OpenZeppelin, mais especificamente a função deployProxy, que se encarrega de fazer deploy do contrato de proxy e do contrato de implementação, inclusive linkando os dois ao final do processo, de forma transparente pra gente. Ao usarmos o objeto contract retornado por esta função, estaremos armazenando os dados no proxy e chamando as funções da implementação, o que fazemos no único cenário de teste que coloquei mais abaixo.
Eu exploro melhor essa funcionalidade no segundo teste, onde altero o estado do contrato, publico uma atualização dele e o estado se mantém, sem perder nenhum dado.
Para ir além nos testes, podemos fazer deploy na Mumbai Testnet. Atualmente o HardHat está mudando seu módulo de deploy para um novo, chamado HardHat Ignition, que não é compatível com OpenZeppelin Upgradeable Contracts (ainda), então ignore o método de deploy atual e vamos usar o antigo. Para isso, crie uma pasta scripts na raiz do seu projeto e depois um arquivo deploy.ts dentro dela, como abaixo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
import { ethers, upgrades } from "hardhat"; async function main() { const Contrato = await ethers.getContractFactory("Contrato"); const contract = await upgrades.deployProxy(Contrato); await contract.waitForDeployment(); const address = await contract.getAddress(); console.log(`Contract deployed at ${address}`); } // We recommend this pattern to be able to use async/await everywhere // and properly handle errors. main().catch((error) => { console.error(error); process.exitCode = 1; }); |
Repare como ele é parecido com o script de deploy dos testes, então dispensa explicações adicionais. Ao fazer seu primeiro deploy, não esqueça de anotar o endereço do contrato de proxy, vamos precisar dele para atualizações futuras. Caso a Testnet não reconheça seu proxy automaticamente como um proxy (isso é necessário para conseguir testar pela interface do explorado de blocos), procure pela opção manual de verificação, como na imagem abaixo (canto inferior direito da imagem).
Caso ele reclame que o contrato de implementação não foi verificado, basta fazê-lo seja pelo terminal, seja manualmente, como com o comando abaixo.
|
1 2 3 |
npx hardhat verify --network <network name> <contract implementation address> |
Quando tudo estiver certo, você conseguirá testar seu proxy como se fosse o contrato de implementação, como abaixo.
Depois disso, é importante ter um script de update.ts também (na mesma pasta scripts), já que quando você quiser mexer na implementação do contrato e subir só ela, não vai querer fazer todo o deploy de novo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
import { ethers, upgrades } from "hardhat"; async function main() { const Contrato = await ethers.getContractFactory("Contrato"); const contract = await upgrades.upgradeProxy("0xC7A15C3116881c207B00646639aB6f9Cc34239e4", Contrato); await contract.waitForDeployment(); const address = await contract.getAddress(); console.log(`Contract updated at ${address}`); } // We recommend this pattern to be able to use async/await everywhere // and properly handle errors. main().catch((error) => { console.error(error); process.exitCode = 1; }); |
Esse script usa a função uphgrades.upgradeProxy, que exige o endereço do proxy e o factory da implementação. Internamente ele verifica se houve mudança, faz o deploy da nova implementação e atualiza o proxy para apontar para ela. Obviamente você deve trocar o endereço que coloquei ali em cima para o seu, que você terá acesso após ter feito deploy pela primeira vez. Após fazer o update, terá de verificar o seu novo contrato de implementação para que a interface do proxy se atualize.
Para facilitar a execução dos scripts, recomendo ajustar seu package.json.
|
1 2 3 4 5 6 7 8 |
"scripts": { "test": "npx hardhat coverage", "compile": "npx hardhat compile", "deploy": "npx hardhat run scripts/deploy.ts --network mumbai", "update": "npx hardhat run scripts/update.ts --network mumbai" }, |
Faça os testes com os scripts e no próprio site explorador de blocos e verá que você pode mudar a implementação que não perderá seus dados armazenados, desde que use sempre a partir do endereço do proxy.
Espero que tenha ajudado!
Querendo aprender a reduzir o consumo de gás nos seus smart contracts? Se liga nesse artigo.
Olá, tudo bem?
O que você achou deste conteúdo? Conte nos comentários.