---
title: "Contrato proxy"
description: "Um contrato proxy encaminha chamadas ao código de implementação enquanto mantém o endereço e o estado do proxy. Entenda como os padrões funcionam e onde surgem riscos de upgrade, armazenamento e administração."
image: "https://wiki.fcontext.com/og.png"
---
> Documentation Index
> Fetch the complete documentation index at: https://wiki.fcontext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Contrato proxy
> Apenas para fins educacionais; não constitui aconselhamento de investimento. Investimentos podem resultar em perdas.
## Resposta direta
Um contrato proxy é um contrato intermediário que encaminha chamadas a outro contrato, geralmente chamado de contrato de implementação ou de lógica. Em um projeto comum da EVM, o proxy usa `delegatecall`; assim, o código da implementação é executado no contexto do proxy, enquanto o estado e os saldos permanecem no endereço do proxy.
Essa camada indireta permite que um sistema mantenha um endereço estável para o usuário enquanto altera sua implementação. Ela também pode reduzir o custo de implantação quando muitos proxies compartilham código. Um proxy não é automaticamente atualizável: alguns proxies mínimos apontam permanentemente para uma implementação, enquanto proxies atualizáveis acrescentam uma forma controlada de trocar a implementação ou o beacon.
Portanto, os usuários precisam avaliar tanto a implementação ativa quanto a autoridade capaz de alterá-la. O bytecode verificado do proxy, por si só, não determina qual código será executado amanhã.
## Como funciona
Quando uma chamada chega ao proxy, seu caminho de fallback copia ou encaminha os dados da chamada a uma implementação. Com `delegatecall`, `address(this)` é o proxy, as leituras e gravações de armazenamento afetam o proxy e os valores originais de `msg.sender` e `msg.value` são preservados. Em seguida, o proxy retorna os dados da implementação ou reverte junto com ela.
Como os metadados do proxy compartilham o espaço de armazenamento do proxy com o estado da aplicação, slots padronizados ajudam a evitar colisões acidentais. A ERC-1967 define slots para o endereço da implementação, o endereço de um beacon e um administrador opcional, e recomenda eventos quando esses valores mudam. O padrão facilita a inspeção de proxies, mas não torna um upgrade seguro por si só.
Projetos comuns colocam a autoridade de upgrade em locais diferentes:
- **Proxy transparente:** o proxy distingue chamadas administrativas de chamadas normais de usuários, geralmente por meio de um contrato administrador separado.
- **Proxy UUPS:** a lógica de upgrade fica na implementação, que deve autorizar mudanças e permanecer compatível com a interface de upgrade esperada.
- **Proxy beacon:** o proxy consulta um beacon para descobrir sua implementação; alterar um beacon pode afetar todos os proxies que o seguem.
- **Clone mínimo:** muitos proxies pequenos delegam para código compartilhado, frequentemente sem qualquer caminho de upgrade.
## Exemplo
Suponha que um proxy de cofre mantenha os saldos dos usuários e delegue à implementação A. Os usuários depositam pelo endereço do proxy, e o código da implementação A atualiza os registros de saldo no armazenamento do proxy.
Mais tarde, a governança altera o slot de implementação ERC-1967 para a implementação B. O endereço do proxy e os saldos registrados não mudam de lugar, mas as chamadas futuras executam o código de B. Se B preservar o layout de armazenamento e aplicar as regras pretendidas, os usuários verão um novo comportamento no mesmo endereço.
Se B reordenar variáveis de armazenamento, omitir uma verificação de autorização ou adicionar uma rota de saque controlada pelo responsável pelo upgrade, a mesma atualização poderá corromper a contabilidade ou expor ativos. Assim, a questão operacional não é apenas se o contrato é um proxy, mas quem pode mudar seu caminho de execução, com qual atraso e sob qual verificação.
## Riscos
- **Comprometimento da chave de upgrade:** um administrador, uma multisig ou um processo de governança pode instalar código malicioso ou defeituoso.
- **Incompatibilidade do layout de armazenamento:** alterar a ordem, os tipos ou a herança das variáveis pode fazer o código novo interpretar incorretamente ou sobrescrever o estado existente.
- **Falha de inicialização:** construtores não inicializam o armazenamento do proxy; proteções ausentes ou reutilizáveis podem permitir que outra conta assuma funções privilegiadas.
- **Surpresas no roteamento de chamadas:** colisões de seletores, rotas exclusivas do administrador ou um beacon inesperado podem fazer a execução diferir da interface visível.
- **Amplo impacto de upgrade compartilhado:** uma decisão sobre um beacon ou implementação pode alterar várias instâncias de contratos ao mesmo tempo.
Antes de depositar ativos ou conceder aprovações, identifique em cadeia a implementação ou o beacon atual, a autoridade de upgrade e qualquer timelock, revise o código-fonte verificado e a compatibilidade do armazenamento e, quando aplicável, inspecione eventos recentes `Upgraded`, `BeaconUpgraded` e `AdminChanged`. O monitoramento continua necessário após a primeira análise porque o caminho de execução pode mudar.
## Erros comuns
- **“O proxy não armazena estado relevante.”** Com `delegatecall`, o estado da aplicação e, muitas vezes, os ativos pertencem ao proxy, embora a lógica venha de outro endereço.
- **“Uma implementação verificada torna o sistema sem necessidade de confiança.”** Chaves de upgrade, governança, beacons, inicialização e implementações futuras continuam fazendo parte do modelo de confiança.
- **“Todo proxy pode ser atualizado.”** Clones e outros proxies fixos podem delegar permanentemente; a possibilidade de upgrade depende do projeto específico e do código de autorização.
## Tópicos relacionados
- [Risco de armazenamento com Delegatecall](/pt-br/crypto/delegatecall-storage-risk/)
- [Colisão de armazenamento do proxy](/pt-br/crypto/proxy-storage-collision/)
- [Monitoramento de upgrade do proxy](/pt-br/crypto/proxy-upgrade-monitoring/)
- [Contrato inteligente](/pt-br/crypto/smart-contract/)
- [Contrato atualizável](/pt-br/crypto/upgradeable-contract/)
## Fontes
- [Introdução aos contratos inteligentes](https://docs.soliditylang.org/en/latest/introduction-to-smart-contracts.html) - Solidity Documentation (acessado em: 2026-08-21)
- [ERC-1967: slots de armazenamento de proxy](https://eips.ethereum.org/EIPS/eip-1967) - Ethereum Improvement Proposals (acessado em: 2026-08-21)
- [ERC-1822: padrão universal de proxy atualizável (UUPS)](https://eips.ethereum.org/EIPS/eip-1822) - Ethereum Improvement Proposals (acessado em: 2026-08-21)
- [Proxy](https://docs.openzeppelin.com/contracts/5.x/api/proxy) - OpenZeppelin Documentation (acessado em: 2026-08-21)
Source: https://wiki.fcontext.com/pt-br/crypto/proxy-contract/index.mdx