Docs

Relayers

Use Engine as a relayer to submit meta-transactions on behalf of your users. Relayers allow your users to send blockchain transactions and have gas fees paid by your backend wallets.

For example, your users can transfer or list NFTs in their wallet without having gas funds.

Learn more about gasless transactions.

Requirements

Create a relayer

  • Navigate to the Explorer section in the Engine dashboard.
  • Select Add relayer.
  • Provide the following details:
    • Chain: The chain where contracts will be called.
    • Backend Wallet: The backend wallet that will submit meta-transactions to the forwarder. Ensure this wallet has sufficient gas funds.
    • Label: A descriptive name for this relayer.
    • Allowed Contracts: (Optional) A list of contract addresses this relayer is allowed to submit transactions to.
    • Allowed Forwarders: (Optional) A list of forwarder addresses this relayer is allowed to submit transactions to.

The relayer will be assigned an ID. The relayer URL to submit transactions to will look like this: https://<your_engine_url>/relayer/<relayer_id>

Submit to a relayer from your app frontend

First, update the CORS policy on Engine to allow your webapp to call Engine.

  • URL: POST /configuration/cors
  • Header
    • Authorization: Bearer <access_token>
    • Content-Type: application/json
  • Body (example)
    {
    "urlsToAdd": [
    "http://localhost:8000",
    "https://dev.my-app.com",
    "https://my-app.com"
    ]
    }

Next, use the thirdweb React SDK to allow users to sign transactions with their wallet and send it to your Engine relayer.

Pass the relayer URL to the SDK provider.

import { ThirdwebProvider } from "@thirdweb-dev/react";
export default function App() {
return (
<ThirdwebProvider
activeChain="polygon"
sdkOptions={{
gasless: {
engine: {
relayerUrl: <engine_relayer_url>,
},
},
}}
>
<ConnectWallet/>
<MintComponent />
</ThirdwebProvider>
);
}

Enable users to connect their wallet with the ConnectWallet component.

import { ConnectWallet } from "@thirdweb-dev/react";
export function Connect() {
return <ConnectWallet />;
}

Create a button that sends a blockchain transaction.

import { useContract } from "@thirdweb-dev/react";
export default function MintComponent() {
const contract = useContract("0x7A0CE8524bea337f0beE853B68fAbDE145dAC0A0");
return (
<Button
onClick={() => {
// This mint transaction will be submitted by your Engine relayer.
await contract.erc20.mint(1);
}}
>
Claim
</Button>
);
}

Submit to a relayer from your app backend

Alternatively, submit transactions to your Engine relayer from your app backend.

  • Prompt the user to sign a transaction, such as transferring an NFT or minting a token.
    • This step does not require gas in the user's wallet.
    • Ensure the signature matches the format that the forwarder expects.
  • Pass the signature from your app frontend to your app backend.
  • Call Engine from your app backend.
    • Method: POST https://<engine_url>/relayer/{relayer_id}
    • Body:
      • type: "forward", "permit", or "execute-meta-transaction"
      • request: The transaction request details
      • signature: The request signed by the user's wallet
      • forwarderAddress: A forwarder address that is trusted by the contract, if type = "forward"
      • See the API reference for details.