Skip to main content

FAQ

About Engine​

How are Engine and the thirdweb Contract SDK different?​

Engine is a server that manages your backend wallets and how they interact with contracts. This difference unlocks capabilities that thirdweb and other web3 SDKs, including:

  • Management of KMS backend wallets
  • Fine-grained access control with access tokens
  • Transaction parallelization to handle higher throughput per wallet
  • Observability and retries on stuck transactions
  • Webhooks on completed transactions to sync on-chain and off-chain activity

Additionally, Engine is built on top of the thirdweb SDK and has the same capabilities.

Does Engine work with all thirdweb smart contracts?​

Yes. Engine has intuitive interfaces to deploy prebuilt contracts, manage smart wallets, run a marketplace, and more.

Does Engine work with my non-thirdweb smart contract?​

Yes. Engine can read and write to any EVM contract with low-level API calls, including providing raw calldata. ERC-721 and ERC-1155 APIs can also be used for contracts imported to thirdweb.

Using Engine​

How do I wait for a transaction to be mined?​

Write calls to contracts do not block until they are mined. Instead they enqueue an async job and immediately return a reference to the job called queueId.

Here are three ways to determine when the job is mined:

  • Use webhooks to notify your backend when a transaction event occurs.

  • Poll the /transaction/status/<queue_id> endpoint.

  • Use websockets:

    const socket = new WebSocket(
      "wss://<engine_url>/transaction/status/<queue_id>?token=<session_token>",
    );
    socket.onmessage = (event) => {
      const res = JSON.parse(event.data);
      console.log("Received data:", JSON.parse(res.result));
    };

How do I cancel a transaction?​

If a transaction is has not yet been mined or failed, cancel the transaction with POST /transaction/cancel.

Or to cancel a transaction in the Engine dashboard, select the Cancel transaction button next to the status in the Transactions table.

Cancel transaction button

How do I customize RPC URLs?​

Set the CHAIN_OVERRIDES environment variable to the path to a JSON file or internet-accessible URL. The default value is ./chain-overrides.json if found. See the example format.

Troubleshooting​

How do I resolve an "invalid password" error?​

As of v0.0.7, an ENCRYPTION_PASSWORD is used to encrypt sensitive data stored in DB. Prior versions used the THIRDWEB_API_SECRET_KEY by default.

To resolve this error, set ENCRYPTION_PASSWORD to the THIRDWEB_API_SECRET_KEY used during setup.

Afterward you may change THIRDWEB_API_SECRET_KEY if needed. Do not change ENCRYPTION_PASSWORD since all sensitive data is encrypted with this password.

How do I resolve issues connecting to Postgres DB?​

Here are some common troubleshooting tips:

  • Ensure the Postgres DB is running in Docker:
    • In same container, ensure the host in the POSTGRES_CONNECTION_URL is set to localhost.
    • In different container, ensure the host in the POSTGRES_CONNECTION_URL is set to host.docker.internal.
  • Ensure the Postgres DB connection URL and credentials are correct.
  • Ensure the database name exists on the Postgres DB.