Project Wallet (Default Server Wallet)

0xFirekeeper · 0xFirekeeper · commit b48949c32f50 · 2025-10-07T22:10:38.000+07:00
Introduces logic to automatically create a default server wallet when a project is created, using a consistent label. Adds a new utility for generating wallet labels, updates project creation flows to provision the wallet, and enhances the ProjectFTUX component to display wallet details. Refactors server wallet creation logic into a reusable function and updates the server wallet creation UI to use this abstraction.

Closes BLD-372
diff --git a/apps/dashboard/src/@/components/project/create-project-modal/index.tsx b/apps/dashboard/src/@/components/project/create-project-modal/index.tsx
@@ -36,9 +36,13 @@ import { Spinner } from "@/components/ui/Spinner";
 import { Textarea } from "@/components/ui/textarea";
 import { createProjectClient } from "@/hooks/useApi";
 import { useDashboardRouter } from "@/lib/DashboardRouter";
+import { getProjectWalletLabel } from "@/lib/project-wallet";
 import { projectDomainsSchema, projectNameSchema } from "@/schema/validations";
 import { toArrFromList } from "@/utils/string";
-import { createVaultAccountAndAccessToken } from "../../../../app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client";
+import {
+  createProjectServerWallet,
+  createVaultAccountAndAccessToken,
+} from "../../../../app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client";
 
 const ALL_PROJECT_SERVICES = SERVICES.filter(
   (srv) => srv.name !== "relayer" && srv.name !== "chainsaw",
@@ -64,7 +68,7 @@ const CreateProjectDialog = (props: CreateProjectDialogProps) => {
     <CreateProjectDialogUI
       createProject={async (params) => {
         const res = await createProjectClient(props.teamId, params);
-        await createVaultAccountAndAccessToken({
+        const vaultTokens = await createVaultAccountAndAccessToken({
           project: res.project,
           projectSecretKey: res.secret,
         }).catch((error) => {
@@ -74,6 +78,22 @@ const CreateProjectDialog = (props: CreateProjectDialogProps) => {
           );
           throw error;
         });
+
+        const managementAccessToken = vaultTokens.managementToken?.accessToken;
+
+        if (!managementAccessToken) {
+          throw new Error("Missing management access token for project wallet");
+        }
+
+        await createProjectServerWallet({
+          label: getProjectWalletLabel(res.project.name),
+          managementAccessToken,
+          project: res.project,
+        }).catch((error) => {
+          console.error("Failed to create default project wallet", error);
+          throw error;
+        });
+
         return {
           project: res.project,
           secret: res.secret,
diff --git a/apps/dashboard/src/@/lib/project-wallet.ts b/apps/dashboard/src/@/lib/project-wallet.ts
@@ -0,0 +1,21 @@
+const PROJECT_WALLET_LABEL_SUFFIX = " Wallet";
+const PROJECT_WALLET_LABEL_MAX_LENGTH = 32;
+
+/**
+ * Builds the default label for a project's primary server wallet.
+ * Ensures a stable naming convention so the wallet can be identified across flows.
+ */
+export function getProjectWalletLabel(projectName: string | undefined) {
+  const baseName = projectName?.trim() || "Project";
+  const maxBaseLength = Math.max(
+    1,
+    PROJECT_WALLET_LABEL_MAX_LENGTH - PROJECT_WALLET_LABEL_SUFFIX.length,
+  );
+
+  const normalizedBase =
+    baseName.length > maxBaseLength
+      ? baseName.slice(0, maxBaseLength).trimEnd()
+      : baseName;
+
+  return `${normalizedBase}${PROJECT_WALLET_LABEL_SUFFIX}`;
+}
diff --git a/apps/dashboard/src/app/(app)/get-started/team/[team_slug]/create-project/_components/create-project-form.tsx b/apps/dashboard/src/app/(app)/get-started/team/[team_slug]/create-project/_components/create-project-form.tsx
@@ -31,9 +31,13 @@ import { Spinner } from "@/components/ui/Spinner";
 import { Textarea } from "@/components/ui/textarea";
 import { createProjectClient } from "@/hooks/useApi";
 import { useDashboardRouter } from "@/lib/DashboardRouter";
+import { getProjectWalletLabel } from "@/lib/project-wallet";
 import { projectDomainsSchema, projectNameSchema } from "@/schema/validations";
 import { toArrFromList } from "@/utils/string";
-import { createVaultAccountAndAccessToken } from "../../../../../team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client";
+import {
+  createProjectServerWallet,
+  createVaultAccountAndAccessToken,
+} from "../../../../../team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client";
 
 const ALL_PROJECT_SERVICES = SERVICES.filter(
   (srv) => srv.name !== "relayer" && srv.name !== "chainsaw",
@@ -55,7 +59,7 @@ export function CreateProjectFormOnboarding(props: {
           <CreateProjectForm
             createProject={async (params) => {
               const res = await createProjectClient(props.teamId, params);
-              await createVaultAccountAndAccessToken({
+              const vaultTokens = await createVaultAccountAndAccessToken({
                 project: res.project,
                 projectSecretKey: res.secret,
               }).catch((error) => {
@@ -65,6 +69,24 @@ export function CreateProjectFormOnboarding(props: {
                 );
                 throw error;
               });
+
+              const managementAccessToken =
+                vaultTokens.managementToken?.accessToken;
+
+              if (!managementAccessToken) {
+                throw new Error(
+                  "Missing management access token for project wallet",
+                );
+              }
+
+              await createProjectServerWallet({
+                label: getProjectWalletLabel(res.project.name),
+                managementAccessToken,
+                project: res.project,
+              }).catch((error) => {
+                console.error("Failed to create default project wallet", error);
+                throw error;
+              });
               return {
                 project: res.project,
                 secret: res.secret,
diff --git a/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/components/ProjectFTUX/ProjectFTUX.tsx b/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/components/ProjectFTUX/ProjectFTUX.tsx
@@ -1,3 +1,4 @@
+import { createVaultClient, listEoas } from "@thirdweb-dev/vault-sdk";
 import {
   ArrowLeftRightIcon,
   ChevronRightIcon,
@@ -7,8 +8,10 @@ import {
 import Link from "next/link";
 import type { Project } from "@/api/project/projects";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { CopyTextButton } from "@/components/ui/CopyTextButton";
 import { CodeServer } from "@/components/ui/code/code.server";
 import { UnderlineLink } from "@/components/ui/UnderlineLink";
+import { NEXT_PUBLIC_THIRDWEB_VAULT_URL } from "@/constants/public-envs";
 import { DotNetIcon } from "@/icons/brand-icons/DotNetIcon";
 import { GithubIcon } from "@/icons/brand-icons/GithubIcon";
 import { ReactIcon } from "@/icons/brand-icons/ReactIcon";
@@ -18,13 +21,31 @@ import { UnrealIcon } from "@/icons/brand-icons/UnrealIcon";
 import { ContractIcon } from "@/icons/ContractIcon";
 import { InsightIcon } from "@/icons/InsightIcon";
 import { PayIcon } from "@/icons/PayIcon";
+import { WalletProductIcon } from "@/icons/WalletProductIcon";
+import { getProjectWalletLabel } from "@/lib/project-wallet";
 import { ClientIDSection } from "./ClientIDSection";
 import { IntegrateAPIKeyCodeTabs } from "./IntegrateAPIKeyCodeTabs";
 import { SecretKeySection } from "./SecretKeySection";
 
-export function ProjectFTUX(props: { project: Project; teamSlug: string }) {
+type ProjectWalletSummary = {
+  id: string;
+  address: string;
+  label?: string;
+};
+
+export async function ProjectFTUX(props: {
+  project: Project;
+  teamSlug: string;
+}) {
+  const projectWallet = await fetchProjectWallet(props.project);
+
   return (
     <div className="flex flex-col gap-10">
+      <ProjectWalletSection
+        project={props.project}
+        teamSlug={props.teamSlug}
+        wallet={projectWallet}
+      />
       <IntegrateAPIKeySection
         project={props.project}
         teamSlug={props.teamSlug}
@@ -39,6 +60,165 @@ export function ProjectFTUX(props: { project: Project; teamSlug: string }) {
   );
 }
 
+function ProjectWalletSection(props: {
+  project: Project;
+  teamSlug: string;
+  wallet: ProjectWalletSummary | undefined;
+}) {
+  const defaultLabel = getProjectWalletLabel(props.project.name);
+  const walletAddress = props.wallet?.address;
+  const label = props.wallet?.label ?? defaultLabel;
+  const shortenedAddress = walletAddress
+    ? `${walletAddress.slice(0, 6)}...${walletAddress.slice(-4)}`
+    : undefined;
+
+  return (
+    <section>
+      <h2 className="mb-3 font-semibold text-xl tracking-tight">
+        Project Wallet
+      </h2>
+
+      <div className="rounded-lg border border-border bg-card p-4">
+        <div className="flex flex-col gap-4">
+          <div className="flex items-center gap-3">
+            <div className="rounded-full border border-border bg-background p-2">
+              <WalletProductIcon className="size-5 text-muted-foreground" />
+            </div>
+            <div>
+              <p className="font-semibold text-lg tracking-tight">{label}</p>
+              <p className="text-muted-foreground text-sm">
+                Default managed server wallet for this project. Use it for
+                deployments, payments, and other automated flows.
+              </p>
+            </div>
+          </div>
+
+          {walletAddress ? (
+            <div className="flex flex-col gap-3 rounded-lg border border-dashed border-border/60 bg-background p-3 md:flex-row md:items-center md:justify-between">
+              <div>
+                <p className="text-muted-foreground text-xs uppercase">
+                  Wallet address
+                </p>
+                <p className="font-mono text-sm break-all">{walletAddress}</p>
+              </div>
+              <CopyTextButton
+                className="w-full md:w-auto"
+                copyIconPosition="right"
+                textToCopy={walletAddress}
+                textToShow={shortenedAddress ?? walletAddress}
+                tooltip="Copy wallet address"
+              />
+            </div>
+          ) : (
+            <Alert variant="info">
+              <CircleAlertIcon className="size-5" />
+              <AlertTitle>Project wallet unavailable</AlertTitle>
+              <AlertDescription>
+                We could not load the default wallet for this project. Visit the
+                Transactions page to create or refresh your server wallets.
+              </AlertDescription>
+            </Alert>
+          )}
+
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+            <p className="text-muted-foreground text-sm">
+              Manage balances, gas sponsorship, and smart account settings in
+              Transactions.
+            </p>
+            <Link
+              className="inline-flex items-center gap-1 text-sm font-medium text-primary hover:underline"
+              href={`/team/${props.teamSlug}/${props.project.slug}/transactions`}
+            >
+              Open Transactions
+              <ChevronRightIcon className="size-4" />
+            </Link>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+type VaultWalletListItem = {
+  id: string;
+  address: string;
+  metadata?: {
+    label?: string;
+    projectId?: string;
+    teamId?: string;
+    type?: string;
+  };
+};
+
+async function fetchProjectWallet(
+  project: Project,
+): Promise<ProjectWalletSummary | undefined> {
+  const engineCloudService = project.services.find(
+    (service) => service.name === "engineCloud",
+  );
+
+  const managementAccessToken =
+    engineCloudService?.managementAccessToken || undefined;
+
+  if (!managementAccessToken || !NEXT_PUBLIC_THIRDWEB_VAULT_URL) {
+    return undefined;
+  }
+
+  try {
+    const vaultClient = await createVaultClient({
+      baseUrl: NEXT_PUBLIC_THIRDWEB_VAULT_URL,
+    });
+
+    const response = await listEoas({
+      client: vaultClient,
+      request: {
+        auth: {
+          accessToken: managementAccessToken,
+        },
+        options: {
+          page: 0,
+          // @ts-expect-error - SDK expects snake_case for pagination arguments
+          page_size: 25,
+        },
+      },
+    });
+
+    if (!response.success || !response.data) {
+      return undefined;
+    }
+
+    const items = response.data.items as VaultWalletListItem[] | undefined;
+
+    if (!items?.length) {
+      return undefined;
+    }
+
+    const expectedLabel = getProjectWalletLabel(project.name);
+
+    const serverWallets = items.filter(
+      (item) => item.metadata?.projectId === project.id,
+    );
+
+    const defaultWallet =
+      serverWallets.find((item) => item.metadata?.label === expectedLabel) ||
+      serverWallets.find((item) => item.metadata?.type === "server-wallet") ||
+      serverWallets[0];
+
+    if (!defaultWallet) {
+      return undefined;
+    }
+
+    return {
+      id: defaultWallet.id,
+      address: defaultWallet.address,
+      label: defaultWallet.metadata?.label,
+    };
+  } catch (error) {
+    console.error("Failed to load project wallet", error);
+    return undefined;
+  }
+}
+
 // Integrate API key section ------------------------------------------------------------
 
 function IntegrateAPIKeySection({
diff --git a/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client.ts b/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/lib/vault.client.ts
diff --git a/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/server-wallets/components/create-server-wallet.client.tsx b/apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/transactions/server-wallets/components/create-server-wallet.client.tsx
