> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gelato.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# ERC-2771 Migration Guide

> How to migrate to the new Gelato Relay ERC2771 contract

<Note> This only applies if you are using `@gelatonetwork/relay-sdk` v3 or contracts from the package `@gelatonetwork/relay-context` v2</Note>

Gelato Relay ERC2771 proxy contracts are immutable for security reasons. We have deployed new versions of our ERC2771 proxy contracts with enhanced security: `GelatoRelayERC2771.sol` and `GelatoRelay1BalanceERC2771.sol`, new addresses of which you can find [here](/relay/additional-resources/supported-networks).

To support these new contracts, Relay Context Contracts found in the package `@gelatonetwork/relay-context` have been updated to version v3, along with the Gelato Relay SDK package `@gelatonetwork/relay-sdk`, which has been updated to version v4.

Gelato Relay continues to support ERC2771 contracts that inherit from the legacy `@gelatonetwork/relay-context` v2, so you can upgrade at your own convenience. Nevertheless we recommend you to upgrade as soon as possible to ensure optimal security, features and support.

## Package and Contract Compatibility Matrix

{(() => {
const compatibilityData = [
  {
    contract: "Legacy GelatoRelayERC2771.sol",
    address: "0xBf175FCC7086b4f9bd59d5EAE8eA67b8f940DE0d",
    relaySdk: "v3",
    relayContext: "v2"
  },
  {
    contract: "GelatoRelayERC2771.sol",
    address: "0xb539068872230f20456CF38EC52EF2f91AF4AE49",
    relaySdk: "v4",
    relayContext: "v3"
  },
  {
    contract: "GelatoRelay1BalanceERC2771.sol",
    address: "0xd8253782c45a12053594b9deB72d8e8aB2Fca54c",
    relaySdk: "v4",
    relayContext: "v3"
  }
];

return (
  <div className="w-full max-w-6xl mx-auto">
    <div className="overflow-x-auto rounded-lg border border-gray-200 dark:border-gray-700">
      <div className="flex w-full bg-gray-50 dark:bg-gray-900 min-w-[400px]">
        <div className="flex-1 py-4 px-3 sm:px-6 font-semibold text-gray-800 dark:text-white text-sm sm:text-base">
          Gelato Relay ERC2771 Contract
        </div>
        <div className="flex-1 py-4 px-3 sm:px-6 font-semibold text-gray-800 dark:text-white text-sm sm:text-base text-center">
          relay-sdk
        </div>
        <div className="flex-1 py-4 px-3 sm:px-6 font-semibold text-gray-800 dark:text-white text-sm sm:text-base text-center">
          relay-context
        </div>
      </div>
      
      {compatibilityData.map((item, index) => (
        <div
          key={index}
          className="flex w-full border-b border-gray-100 dark:border-gray-800 transition-colors duration-200 min-w-[400px]"
        >
          <div className="flex-1 py-3 sm:py-4 px-3 sm:px-6 font-medium text-gray-700 dark:text-gray-300 text-sm sm:text-base break-words leading-relaxed">
            <div className="break-words hyphens-auto" style={{ hyphens: 'auto', wordBreak: 'break-all', WebkitHyphens: 'auto', msHyphens: 'auto' }}>
              {item.contract}:
            </div>
            <div className="font-mono text-gray-600 dark:text-gray-400 text-xs sm:text-sm mt-1 break-all" style={{ wordBreak: 'break-all', overflowWrap: 'break-word' }}>
              {item.address}
            </div>
          </div>
          <div className="flex-1 py-3 sm:py-4 px-3 sm:px-6 text-gray-600 dark:text-gray-400 text-sm sm:text-base text-center break-words leading-relaxed">
            <div className="break-words hyphens-auto">
              {item.relaySdk}
            </div>
          </div>
          <div className="flex-1 py-3 sm:py-4 px-3 sm:px-6 text-gray-600 dark:text-gray-400 text-sm sm:text-base text-center break-words leading-relaxed">
            <div className="break-words hyphens-auto">
              {item.relayContext}
            </div>
          </div>
        </div>
      ))}
    </div>
  </div>
);
})()}

<Warning> Please note that contract addresses differ on [zkSync Era](/relay/additional-resources/supported-networks#zksync-era-mainnet-%2F-testnet). </Warning>

<Warning> Using `@gelatonetwork/relay-sdk` v3 with contracts inheriting from `@gelatonetwork/relay-context` v3, or using `@gelatonetwork/relay-sdk` v4 with contracts inheriting from `@gelatonetwork/relay-context` v2 won't work, as they refer to different Gelato Relay ERC2771 contracts. </Warning>

## Migration Steps

1. If you deployed contracts that inherit from `@gelatonetwork/relay-context` - update the package version and either upgrade or redeploy your contracts.

2. If you are using `sponsoredCallERC2771` in combination with `ERC2771Context.sol` - make sure to use the new `GelatoRelay1BalanceERC2771.sol` contract address as the trustedForwarder which you can find [here](/relay/additional-resources/supported-networks).

3. If you are using `@gelatonetwork/relay-sdk` - update the package version in your project.

4. Make sure you use your newly upgraded/deployed contract addresses with the updated Gelato Relay SDK package.

If you cannot upgrade or redeploy your ERC2771-compatible contracts, please [contact us](https://gelato.cloud/contact) to find a future-proof solution together.