smart backend wallet creation + initial flow

Author: d4mr

src/db/wallets/createWalletDetails.ts

@@ -1,3 +1,4 @@
+import type { Address } from "thirdweb";
 import type { PrismaTransaction } from "../../schema/prisma";
 import { encrypt } from "../../utils/crypto";
 import { getPrismaWithPostgresTx } from "../client";
@@ -8,13 +9,17 @@ type CreateWalletDetailsParams = {
   address: string;
   label?: string;
 } & (
+  | {
+      type: "local";
+      encryptedJson: string; // ENCRYPTION IS NOT HANDLED HERE, process privatekey with legacyLocalCrytpo before passing to this function
+    }
   | {
       type: "aws-kms";
       awsKmsKeyId?: string; // depcrecated and unused, todo: remove with next breaking change
       awsKmsArn: string;
 
-      awsKmsSecretAccessKey?: string; // will be encrypted and stored, pass plaintext to this function
-      awsKmsAccessKeyId?: string;
+      awsKmsSecretAccessKey: string; // will be encrypted and stored, pass plaintext to this function
+      awsKmsAccessKeyId: string;
     }
   | {
       type: "gcp-kms";
@@ -24,11 +29,39 @@ type CreateWalletDetailsParams = {
       gcpKmsKeyVersionId?: string; // depcrecated and unused, todo: remove with next breaking change
       gcpKmsLocationId?: string; // depcrecated and unused, todo: remove with next breaking change
 
-      gcpApplicationCredentialPrivateKey?: string; // encrypted
-      gcpApplicationCredentialEmail?: string;
+      gcpApplicationCredentialPrivateKey: string; // will be encrypted and stored, pass plaintext to this function
+      gcpApplicationCredentialEmail: string;
+    }
+  | {
+      type: "smart:aws-kms";
+      awsKmsArn: string;
+      awsKmsSecretAccessKey: string; // will be encrypted and stored, pass plaintext to this function
+      awsKmsAccessKeyId: string;
+      accountSignerAddress: Address;
+
+      accountFactoryAddress?: Address;
+    }
+  | {
+      type: "smart:gcp-kms";
+      gcpKmsResourcePath: string;
+      gcpApplicationCredentialPrivateKey: string; // will be encrypted and stored, pass plaintext to this function
+      gcpApplicationCredentialEmail: string;
+      accountSignerAddress: Address;
+
+      accountFactoryAddress?: Address;
+    }
+  | {
+      type: "smart:local";
+      encryptedJson: string; // ENCRYPTION IS NOT HANDLED HERE, process privatekey with legacyLocalCrytpo before passing to this function
+      accountSignerAddress: Address;
+
+      accountFactoryAddress?: Address;
     }
 );
 
+/**
+ * Create a new WalletDetails row in DB
+ */
 export const createWalletDetails = async ({
   pgtx,
   ...walletDetails
@@ -47,15 +80,23 @@ export const createWalletDetails = async ({
     );
   }
 
+  if (walletDetails.type === "local") {
+    return prisma.walletDetails.create({
+      data: {
+        ...walletDetails,
+        address: walletDetails.address.toLowerCase(),
+        encryptedJson: walletDetails.encryptedJson,
+      },
+    });
+  }
+
   if (walletDetails.type === "aws-kms") {
     return prisma.walletDetails.create({
       data: {
         ...walletDetails,
         address: walletDetails.address.toLowerCase(),
 
-        awsKmsSecretAccessKey: walletDetails.awsKmsSecretAccessKey
-          ? encrypt(walletDetails.awsKmsSecretAccessKey)
-          : undefined,
+        awsKmsSecretAccessKey: encrypt(walletDetails.awsKmsSecretAccessKey),
       },
     });
   }
@@ -66,11 +107,60 @@ export const createWalletDetails = async ({
         ...walletDetails,
         address: walletDetails.address.toLowerCase(),
 
-        gcpApplicationCredentialPrivateKey:
-          walletDetails.gcpApplicationCredentialPrivateKey
-            ? encrypt(walletDetails.gcpApplicationCredentialPrivateKey)
-            : undefined,
+        gcpApplicationCredentialPrivateKey: encrypt(
+          walletDetails.gcpApplicationCredentialPrivateKey,
+        ),
+      },
+    });
+  }
+
+  if (walletDetails.type === "smart:aws-kms") {
+    return prisma.walletDetails.create({
+      data: {
+        ...walletDetails,
+
+        address: walletDetails.address.toLowerCase(),
+        awsKmsSecretAccessKey: encrypt(walletDetails.awsKmsSecretAccessKey),
+        accountSignerAddress: walletDetails.accountSignerAddress.toLowerCase(),
+
+        accountFactoryAddress:
+          walletDetails.accountFactoryAddress?.toLowerCase(),
+      },
+    });
+  }
+
+  if (walletDetails.type === "smart:gcp-kms") {
+    return prisma.walletDetails.create({
+      data: {
+        ...walletDetails,
+
+        address: walletDetails.address.toLowerCase(),
+        accountSignerAddress: walletDetails.accountSignerAddress.toLowerCase(),
+
+        gcpApplicationCredentialPrivateKey: encrypt(
+          walletDetails.gcpApplicationCredentialPrivateKey,
+        ),
+
+        accountFactoryAddress:
+          walletDetails.accountFactoryAddress?.toLowerCase(),
       },
     });
   }
+
+  if (walletDetails.type === "smart:local") {
+    return prisma.walletDetails.create({
+      data: {
+        ...walletDetails,
+        address: walletDetails.address.toLowerCase(),
+        accountSignerAddress: walletDetails.accountSignerAddress.toLowerCase(),
+
+        accountFactoryAddress:
+          walletDetails.accountFactoryAddress?.toLowerCase(),
+      },
+    });
+  }
+
+  // we will never reach here
+  // this helps typescript understand that this function will always return
+  throw new Error("Unsupported wallet type");
 };

src/prisma/migrations/20241007003342_add_smart_backend_wallet_columns/migration.sql

@@ -0,0 +1,3 @@
+-- AlterTable
+ALTER TABLE "wallet_details" ADD COLUMN     "accountFactoryAddress" TEXT,
+ADD COLUMN     "accountSignerAddress" TEXT;

src/prisma/schema.prisma

@@ -94,6 +94,9 @@ model WalletDetails {
   gcpKmsResourcePath                 String? @map("gcpKmsResourcePath") @db.Text
   gcpApplicationCredentialEmail      String? @map("gcpApplicationCredentialEmail") /// if not available, default to: Configuration.gcpApplicationCredentialEmail
   gcpApplicationCredentialPrivateKey String? @map("gcpApplicationCredentialPrivateKey") /// if not available, default to: Configuration.gcpApplicationCredentialPrivateKey
+  // Smart Backend Wallet
+  accountSignerAddress               String? @map("accountSignerAddress") /// this, and either local, aws or gcp encryptedJson, are required for smart wallet
+  accountFactoryAddress              String? @map("accountFactoryAddress") /// optional even for smart wallet, if not available default factory will be used
 
   @@map("wallet_details")
 }

src/schema/wallet.ts

@@ -2,4 +2,9 @@ export enum WalletType {
   local = "local",
   awsKms = "aws-kms",
   gcpKms = "gcp-kms",
+
+  // Smart wallets
+  smartAwsKms = "smart:aws-kms",
+  smartGcpKms = "smart:gcp-kms",
+  smartLocal = "smart:local",
 }

src/server/routes/backend-wallet/create.ts

@@ -8,20 +8,25 @@ import { AddressSchema } from "../../schemas/address";
 import { standardResponseSchema } from "../../schemas/sharedApiSchemas";
 import {
   CreateAwsKmsWalletError,
-  createAwsKmsWallet,
+  createAndStoreAwsKmsWallet,
 } from "../../utils/wallets/createAwsKmsWallet";
 import {
   CreateGcpKmsWalletError,
-  createGcpKmsWallet,
+  createAndStoreGcpKmsWallet,
 } from "../../utils/wallets/createGcpKmsWallet";
-import { createLocalWallet } from "../../utils/wallets/createLocalWallet";
+import { createAndStoreLocalWallet } from "../../utils/wallets/createLocalWallet";
+import {
+  createAndStoreSmartAwsWallet,
+  createAndStoreSmartGcpWallet,
+  createAndStoreSmartLocalWallet,
+} from "../../utils/wallets/createSmartWallet";
 
 const requestBodySchema = Type.Object({
   label: Type.Optional(Type.String()),
   type: Type.Optional(
     Type.Enum(WalletType, {
       description:
-        "Optional wallet type. If not provided, the default wallet type will be used.",
+        "Type of new wallet to create. It is recommended to always provide this value. If not provided, the default wallet type will be used.",
     }),
   ),
 });
@@ -30,13 +35,15 @@ const responseSchema = Type.Object({
   result: Type.Object({
     walletAddress: AddressSchema,
     status: Type.String(),
+    type: Type.Enum(WalletType),
   }),
 });
 
 responseSchema.example = {
   result: {
     walletAddress: "0x....",
     status: "success",
+    type: WalletType.local,
   },
 };
 
@@ -70,11 +77,11 @@ export const createBackendWallet = async (fastify: FastifyInstance) => {
 
       switch (walletType) {
         case WalletType.local:
-          walletAddress = await createLocalWallet({ label });
+          walletAddress = await createAndStoreLocalWallet({ label });
           break;
         case WalletType.awsKms:
           try {
-            walletAddress = await createAwsKmsWallet({ label });
+            walletAddress = await createAndStoreAwsKmsWallet({ label });
           } catch (e) {
             if (e instanceof CreateAwsKmsWalletError) {
               throw createCustomError(
@@ -88,7 +95,7 @@ export const createBackendWallet = async (fastify: FastifyInstance) => {
           break;
         case WalletType.gcpKms:
           try {
-            walletAddress = await createGcpKmsWallet({ label });
+            walletAddress = await createAndStoreGcpKmsWallet({ label });
           } catch (e) {
             if (e instanceof CreateGcpKmsWalletError) {
               throw createCustomError(
@@ -100,11 +107,54 @@ export const createBackendWallet = async (fastify: FastifyInstance) => {
             throw e;
           }
           break;
+        case WalletType.smartAwsKms:
+          try {
+            const smartAwsWallet = await createAndStoreSmartAwsWallet({
+              label,
+            });
+
+            walletAddress = smartAwsWallet.address;
+          } catch (e) {
+            if (e instanceof CreateAwsKmsWalletError) {
+              throw createCustomError(
+                e.message,
+                StatusCodes.BAD_REQUEST,
+                "CREATE_AWS_KMS_WALLET_ERROR",
+              );
+            }
+            throw e;
+          }
+          break;
+        case WalletType.smartGcpKms:
+          try {
+            const smartGcpWallet = await createAndStoreSmartGcpWallet({
+              label,
+            });
+            walletAddress = smartGcpWallet.address;
+          } catch (e) {
+            if (e instanceof CreateGcpKmsWalletError) {
+              throw createCustomError(
+                e.message,
+                StatusCodes.BAD_REQUEST,
+                "CREATE_GCP_KMS_WALLET_ERROR",
+              );
+            }
+            throw e;
+          }
+          break;
+        case WalletType.smartLocal:
+          walletAddress = (
+            await createAndStoreSmartLocalWallet({
+              label,
+            })
+          ).address;
+          break;
       }
 
       reply.status(StatusCodes.OK).send({
         result: {
           walletAddress,
+          type: walletType,
           status: "success",
         },
       });

src/server/utils/storage/localStorage.ts

@@ -1,13 +1,21 @@
-import { AsyncStorage } from "@thirdweb-dev/wallets";
-import fs from "fs";
+import type { AsyncStorage } from "@thirdweb-dev/wallets";
+import fs from "node:fs";
 import { prisma } from "../../../db/client";
 import { WalletType } from "../../../schema/wallet";
 import { logger } from "../../../utils/logger";
 
+/**
+ * @deprecated
+ * Deprecated local file storage implementation for use with v4 sdk
+ * Use `legacyLocalCrypto` for encryption and decryption instead
+ */
 export class LocalFileStorage implements AsyncStorage {
   label?: string;
 
-  constructor(private readonly walletAddress: string, label?: string) {
+  constructor(
+    private readonly walletAddress: string,
+    label?: string,
+  ) {
     this.walletAddress = walletAddress.toLowerCase();
     this.label = label;
   }

src/server/utils/wallets/createAwsKmsWallet.ts

@@ -6,7 +6,7 @@ import {
 } from "./fetchAwsKmsWalletParams";
 import { importAwsKmsWallet } from "./importAwsKmsWallet";
 
-type CreateAwsKmsWalletParams = {
+export type CreateAwsKmsWalletParams = {
   label?: string;
 } & Partial<AwsKmsWalletParams>;
 
@@ -16,15 +16,35 @@ export class CreateAwsKmsWalletError extends Error {}
  * Create an AWS KMS wallet, and store it into the database
  * All optional parameters are overrides for the configuration in the database
  * If any required parameter cannot be resolved from either the configuration or the overrides, an error is thrown.
- * If credentials (awsAccessKeyId and awsSecretAccessKey) are explicitly provided, they will be stored separately from the global configuration
+ * Credentials (awsAccessKeyId and awsSecretAccessKey) are explicitly stored separately from the global configuration
  */
-export const createAwsKmsWallet = async ({
+export const createAndStoreAwsKmsWallet = async ({
   label,
   ...overrides
 }: CreateAwsKmsWalletParams): Promise<string> => {
+  const { awsKmsArn, params } = await createAwsKmsWallet(overrides);
+
+  return importAwsKmsWallet({
+    awsKmsArn,
+    label,
+    crendentials: {
+      accessKeyId: params.awsAccessKeyId,
+      secretAccessKey: params.awsSecretAccessKey,
+    },
+  });
+};
+
+/**
+ * Creates an AWS KMS wallet and returns the AWS KMS ARN
+ * All optional parameters are overrides for the configuration in the database
+ * If any required parameter cannot be resolved from either the configuration or the overrides, an error is thrown.
+ */
+export const createAwsKmsWallet = async (
+  params: Partial<AwsKmsWalletParams>,
+) => {
   let kmsWalletParams: AwsKmsWalletParams;
   try {
-    kmsWalletParams = await fetchAwsKmsWalletParams(overrides);
+    kmsWalletParams = await fetchAwsKmsWalletParams(params);
   } catch (e) {
     if (e instanceof FetchAwsKmsWalletParamsError) {
       throw new CreateAwsKmsWalletError(e.message);
@@ -54,12 +74,9 @@ export const createAwsKmsWallet = async ({
   }
 
   const awsKmsArn = res.KeyMetadata.Arn;
-  return importAwsKmsWallet({
+
+  return {
     awsKmsArn,
-    label,
-    crendentials: {
-      accessKeyId: kmsWalletParams.awsAccessKeyId,
-      secretAccessKey: kmsWalletParams.awsSecretAccessKey,
-    },
-  });
+    params: kmsWalletParams,
+  };
 };