Backend Wallets

Engine performs blockchain actions using backend wallets that you own and manage.

There are multiple options for securing backend wallets.

Smart backend wallets are the recommended way to perform blockchain operations with Engine. Each smart backend wallet consists of an EOA (managed internally by Engine) and a smart account (using thirdweb's default account implementation).

Smart backend wallets inherit smart account benefits and offer several advantages over traditional EOAs:

• Gas Management: Built-in paymaster eliminates the need to maintain gas tokens. This means you never need to hold crypto or top up gas.
• Better Nonce Management: Smart accounts use multi-dimensional nonces, which are more efficient than EOAs.
• Simple Integration: Works with all existing Engine endpoints without any code changes.

The smart account is automatically deployed the first time you send a transaction on a chain. You don't need to think about deploying or managing the smart account - Engine handles everything behind the scenes. All transactions are sent as UserOperations to the EntryPoint contract on chain.

• smart:local - Smart account backed by a local key
• smart:aws-kms - Smart account backed by AWS KMS
• smart:gcp-kms - Smart account backed by Google Cloud KMS

For AWS and Google Cloud KMS options, follow the setup instructions in the respective sections below.

Smart backend wallets have no additional costs to use with your Engine instance. Transactions sent from smart backend wallets follow the same billing model as regular account abstraction transactions with thirdweb. Smart accounts need to be deployed on each chain. This costs gas and is billed to your account like any other transaction.

A local wallet is a wallet created or imported from a private key. Ensure your private key is backed up before transacting with a local wallet in a production environment.

Local wallets private keys are stored encrypted in Engine's database. For security reasons, private keys cannot be exported.

An AWS KMS Wallet is a wallet securely stored in your AWS account. Engine can create and transact with the wallet, but not delete it.

• Create an IAM user with programmatic access.
• Grant the following KMS permissions to this user.
  • kms:CreateKey
  • kms:GetPublicKey
  • kms:Sign
  • kms:CreateAlias
  • kms:Verify
• On the user page, navigate to Security credentials > Access keys.
• Select Create access key to get an Access Key and Secret Key.
• In the dashboard, navigate to Configuration > Backend Wallets.
• Select AWS KMS and provide the following:
  • Access Key (example: AKIA...)
  • Secret Key (example: UW7A...)
  • Region (example: us-west-1)

• Ensure your KMS key is created with the following settings:
  • Key type: Asymmetric
  • Key spec: ECC_SECG_P256K1
  • Key usage: Sign and verify
• In the dashboard, navigate to Overview > Backend Wallets.
• Select Import and provide the following:
  • AWS KMS Key ID (example: 0489da75-9830-4a5a-97e3-e4a6df7775b3)
  • AWS KMS ARN (example: arn:aws:kms:us-west-1:632186309261:key/0489da75-9830-4a5a-97e3-e4a6df7775b3)

• Enable Google KMS API for your GCP account.

• Create a Service Account.

• Navigate to the IAM page. Find the service account and select Edit Principal to add the following roles:

  • Cloud KMS Admin
  • Cloud KMS CryptoKey Signer/Verifier

• Navigate to the Service Accounts page. Select the above service account.

• Navigate to the Keys tab. Select Add Key > Create new key.

• Select JSON to download the JSON file. This file contains the key's private key in plaintext.

• In the dashboard, navigate to Configuration > Backend Wallets.

• Select Google KMS and provide the following:

  gcpApplicationProjectId

  This is the Project ID of the GCP project where the key was created.

  Where to find:

  • Navigate to the Google Cloud Console.
  • Click on the project dropdown at the top of the page.
  • The Project ID is displayed under your project's name.

  gcpKmsLocationId

  This is the location where the keyring was created (e.g., us-central1, europe-west1).

  Where to find:

  • In the Google Cloud Console, go to Security > Cryptographic Keys.
  • Click on the keyring that contains your key.
  • The location is displayed in the Location field.

  gcpKmsKeyRingId

  This is the ID of the keyring where your key is stored.

  Where to find:

  • In the Google Cloud Console, go to Security > Cryptographic Keys.
  • Select the keyring that contains your key.
  • The KeyRing ID is displayed in the list or the URL.

  gcpApplicationCredentialEmail

  This is the email associated with the service account used for accessing the KMS key.

  Where to find:

  • In the Google Cloud Console, go to IAM & Admin > Service Accounts.
  • Find the service account you are using. its email will be in the format: name@project.iam.gserviceaccount.com

  gcpApplicationCredentialPrivateKey

  This is the private key of the service account that is used for authenticating API requests.

  Where to find:

  • Open the JSON file downloaded above.
  • Copy the value of the private_key field.

• Ensure your keyring is created with the following settings:
  • Purpose: Asymmetric sign
  • Algorithm: Elliptic Curve P-256 - SHA256 Digest
• In the dashboard, navigate to Overview > Backend Wallets.
• Select Import and provide the following:
  • GCP KMS Key ID (example: 0489da75-9830-4a5a-97e3-e4a6df7775b3)
  • GCP KMS Version ID (example: 1)

For AWS or Google Cloud KMS wallets, you must provide your credentials.

• In the dashboard, navigate to Overview > Backend Wallets.
• Select Create.
• (Optional) Provide a label to organize your wallets.

For AWS or Google Cloud KMS wallets, you must provide your credentials.

• In the dashboard, navigate to Overview > Backend Wallets.
• Select Import.
• Provide the requested fields.
  • See above for instructions for specific wallet types.

In the dashboard, navigate to Overview > Backend Wallets to view your wallets created by or imported to Engine.

• It is recommend to use AWS or Google Cloud KMS wallets for production use. Private keys are never exposed and the wallet is backed up securely by the cloud provider.
• Use labels and multiple backend wallets to organize and track usage.
  • Example: Use one wallet to pay out creators on your platform and another to airdrop NFTs to users.
• If your wallets require topping up gas or ERC20 tokens regularly, consider a separate "funds storage" backend wallet that transfers funds to other wallets via the dashboard UI or API.