thirdweb Engine

You can deploy and use thirdweb Engine through several methods depending on your needs:

Managed Hosting

Get Engine hosted and managed by thirdweb for a hands-off experience via the thirdweb Dashboard.

Self-Hosting

• Free Self-hosting: Follow the official self-host instructions to run Engine on your own infrastructure.
• Railway: Use the Railway template for a quick deployment on Railway.

Engine tracks nonces using several distinct states to ensure reliable transaction sequencing and to prevent nonce collisions or gaps:

1. On-chain Nonce: The state of the blockchain. It is calculated as the transactionCount from the RPC minus 1 (representing the last successfully mined transaction).
2. Last Used Nonce: The highest nonce that Engine has attempted to use and sent to the RPC.
3. Sent Nonces: A queue of nonces that have been broadcast to the network but have not yet been included in a block (mined).
4. Recycled Nonces: A pool of nonces that were reserved by Engine but failed to be successfully broadcast to the RPC. These are held in a pending state to be either retried (recycled) or cancelled to prevent gaps in the transaction sequence.

When calling deployment methods, you can provide several optional headers to control the transaction behavior:

• xIdempotencyKey: Prevents duplicate transactions. Engine compares the last 100,000 transactions to de-duplicate.
• xTransactionMode: Set to 'sponsored' for sponsored transactions. This is ignored if using a smart wallet.
• xAccountAddress: The smart account address.
• xAccountFactoryAddress: The smart account factory address. If omitted, Engine attempts to resolve it from the contract.
• xAccountSalt: A string or hex salt used to predict the smart account address. Useful when creating multiple accounts with the same admin.

The engine uses abiSchema and abiTypeSchema to validate ABI definitions. An ABI is an array of objects where each object represents an entry (function, event, etc.).

Key fields in abiTypeSchema include:

• type (Optional String)
• name (Optional String)
• internalType (Optional String)
• components (Optional Array of objects with type, name, and internalType)

Key fields in abiFunctionSchema include:

• name (String)
• inputs (Array of abiTypeSchema)
• outputs (Array of abiTypeSchema)
• signature (String)
• stateMutability (String)
• comment (Optional String)

Certain routes are considered public and do not require authentication. These include:

• GET /
• GET /favicon.ico
• GET /system/health
• GET routes matching OpenAPI definitions
• GET /auth/user*
• GET /transaction/status*
• POST /auth/payload, /auth/login, /auth/switch-account, /auth/logout
• /relayer/{uuid} (Relay transaction endpoints)
• Admin queue routes (which enforce their own specific auth)

Additionally, if the ENGINE_MODE environment variable is set to sandbox, the authentication check is skipped entirely for all requests.

The nftSchema defines the complete structure of an NFT as tracked by the engine. It includes:

• metadata: The nftMetadataSchema (id, uri, name, description, etc.).
• owner: The wallet address of the owner.
• type: The contract standard, which must be one of ERC1155, ERC721, or metaplex.
• supply: The total supply as a string.
• quantityOwned: (Optional) The amount owned by the user.

The engine uses a specific CustomError type to handle expected operational errors. When you throw an object matching this shape, the middleware will catch it and return it as a structured JSON response.

Type Definition:

type CustomError = {
  message: string;
  statusCode: number;
  code: string;
  stack?: string;
};

API Response Format: When a CustomError is thrown, the client receives a response with the following JSON body:

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human readable message",
    "statusCode": 400,
    "stack": "..."
  }
}

Keypair authentication allows requests to be authenticated using a JWT signed by an ES256 private key that matches a configured public key.

To use this feature, you must:

1. Set the ENABLE_KEYPAIR_AUTH environment variable to true.
2. Ensure the public key is added to Engine.
3. (Optional) If the JWT contains a bodyHash, the request body must match the SHA256 hash provided in the token to prevent tampering.

Engine supports IP allowlisting to restrict access to specific IP addresses.

• If the ipAllowlist in your configuration is empty, all IPs are allowed.
• If configured, the middleware checks the request IP against the list. If TRUST_PROXY is enabled (or if ENGINE_TIER is set), the middleware will use the cf-connecting-ip header (Cloudflare) to identify the client IP.
• If an IP is not in the allowlist, the request is rejected with a 401 Unauthorized error.