@zerodev/wallet-core 0.0.1-alpha.3

package/src/actions/wallet/signTransaction.ts

@@ -0,0 +1,60 @@
+import type { Hex } from 'viem'
+import type { Client } from '../../client/types.js'
+
+export type SignTransactionParameters = {
+  /** The organization ID */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+  /** The address to sign with */
+  address: Hex
+  /** The unsigned transaction to sign */
+  unsignedTransaction: string
+}
+
+export type SignTransactionReturnType = Hex
+
+/**
+ * Signs a raw transaction with the user's wallet
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for signing
+ * @returns The signature
+ *
+ * @example
+ * ```ts
+ * const result = await signTransaction(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456',
+ *   address: '0x123...',
+ *   unsignedTransaction: 'abc123...',
+ * });
+ * console.log(result.signature); // '0x...'
+ * ```
+ */
+export async function signTransaction(
+  client: Client,
+  params: SignTransactionParameters,
+): Promise<SignTransactionReturnType> {
+  const { organizationId, projectId, address, unsignedTransaction } = params
+
+  const { signature } = await client.request({
+    path: `${projectId}/sign/transaction`,
+    body: {
+      body: {
+        type: 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2',
+        timestampMs: Date.now().toString(),
+        organizationId,
+        parameters: {
+          signWith: address,
+          type: 'TRANSACTION_TYPE_ETHEREUM',
+          unsignedTransaction,
+        },
+      },
+      apiUrl: 'https://api.turnkey.com/public/v1/submit/sign_transaction',
+    },
+    stamp: true,
+  })
+
+  return `0x${signature}` as Hex
+}

package/src/adapters/viem.ts

@@ -0,0 +1,158 @@
+import {
+  type Hex,
+  hashMessage,
+  type LocalAccount,
+  parseSignature,
+  parseTransaction,
+  type SerializeTransactionFn,
+  type SignableMessage,
+  serializeTransaction,
+  serializeTypedData,
+  type TransactionSerializable,
+  zeroAddress,
+} from 'viem'
+import type {
+  SignAuthorizationParameters,
+  SignAuthorizationReturnType,
+} from 'viem/accounts'
+import { toAccount } from 'viem/accounts'
+import { hashAuthorization } from 'viem/utils'
+import type { signRawPayload } from '../actions/index.js'
+import type { ZeroDevWalletClient } from '../client/index.js'
+
+export interface ToViemAccountParams {
+  client: ZeroDevWalletClient
+  organizationId: string
+  projectId: string
+}
+
+export async function toViemAccount(
+  params: ToViemAccountParams,
+): Promise<LocalAccount> {
+  const { client, organizationId, projectId } = params
+
+  let address: Hex = zeroAddress
+
+  try {
+    const walletResponse = await client.getUserWallet({
+      organizationId,
+      projectId,
+    })
+    address = walletResponse.walletAddress
+  } catch {
+    address = zeroAddress
+  }
+  const signRawPayloadInternal = async (
+    payload: string,
+    encoding: Parameters<
+      typeof signRawPayload
+    >[1]['encoding'] = 'PAYLOAD_ENCODING_HEXADECIMAL',
+  ) => {
+    return await client.signRawPayload({
+      organizationId,
+      projectId,
+      address,
+      payload,
+      encoding,
+    })
+  }
+
+  // Modified from: https://github.com/tkhq/sdk/blob/4e439bf2973ea13b51d981d7c24a4841d4e5fd5f/packages/viem/src/index.ts#L419-L461
+  const signTransactionInternal = async <
+    TTransactionSerializable extends TransactionSerializable,
+  >(
+    transaction: TTransactionSerializable,
+    serializer: SerializeTransactionFn<TTransactionSerializable>,
+  ): Promise<Hex> => {
+    // Note: for Type 3 transactions, we are specifically handling parsing for payloads containing only the transaction payload body, without any wrappers around blobs, commitments, or proofs.
+    // See more: https://github.com/wevm/viem/blob/3ef19eac4963014fb20124d1e46d1715bed5509f/src/accounts/utils/signTransaction.ts#L54-L55
+    const signableTransaction =
+      transaction.type === 'eip4844'
+        ? { ...transaction, sidecars: false }
+        : transaction
+
+    const serializedTx = serializer(signableTransaction)
+    const nonHexPrefixedSerializedTx = serializedTx.replace(/^0x/, '')
+    const signature = await client.signTransaction({
+      organizationId,
+      projectId,
+      address,
+      unsignedTransaction: nonHexPrefixedSerializedTx,
+    })
+
+    if (transaction.type === 'eip4844') {
+      // Grab components of the signature
+      const { r, s, v } = parseTransaction(signature)
+
+      // Recombine with the original transaction
+      return serializeTransaction(transaction, {
+        r: r!,
+        s: s!,
+        v: v!,
+      })
+    }
+
+    return signature
+  }
+
+  return toAccount({
+    address,
+
+    async signMessage({ message }: { message: SignableMessage }): Promise<Hex> {
+      const hashedMessage = hashMessage(message)
+      return signRawPayloadInternal(hashedMessage)
+    },
+
+    signTransaction: async <
+      TTransactionSerializable extends TransactionSerializable,
+    >(
+      transaction: TTransactionSerializable,
+      options?: {
+        serializer?:
+          | SerializeTransactionFn<TTransactionSerializable>
+          | undefined
+      },
+    ) => {
+      const serializer: SerializeTransactionFn<TTransactionSerializable> =
+        options?.serializer ??
+        (serializeTransaction as SerializeTransactionFn<TTransactionSerializable>)
+      return signTransactionInternal(transaction, serializer)
+    },
+    signTypedData: async (typedData) => {
+      const serializedTypedData = serializeTypedData(typedData)
+      return signRawPayloadInternal(
+        serializedTypedData,
+        'PAYLOAD_ENCODING_EIP712',
+      )
+    },
+
+    async signAuthorization(
+      parameters: Omit<SignAuthorizationParameters, 'privateKey'>,
+    ): Promise<SignAuthorizationReturnType> {
+      const { chainId, nonce } = parameters
+      const authAddress = parameters.contractAddress ?? parameters.address
+
+      if (!authAddress) {
+        throw new Error('Unable to sign authorization: address is undefined')
+      }
+
+      const hashedAuthorization = hashAuthorization({
+        address: authAddress,
+        chainId,
+        nonce,
+      })
+
+      const signature = await signRawPayloadInternal(hashedAuthorization)
+
+      const parsedSignature = parseSignature(signature)
+
+      return {
+        address: authAddress,
+        chainId,
+        nonce,
+        ...parsedSignature,
+        yParity: parsedSignature.v === BigInt(27) ? 0 : 1,
+      } as SignAuthorizationReturnType
+    },
+  })
+}

package/src/client/createClient.ts

@@ -0,0 +1,95 @@
+import type { Stamper } from '../stampers/types.js'
+import {
+  type ZeroDevWalletActions,
+  zeroDevWalletActions,
+} from './decorators/client.js'
+import type { Client, ClientConfig } from './types.js'
+
+let clientId = 0
+
+/**
+ * Creates a base ZeroDev Wallet client.
+ * This is the foundation client without any pre-loaded actions.
+ * Use createClient() for a client with ZeroDev Wallet actions pre-loaded.
+ */
+export function createBaseClient<
+  extended extends Record<string, unknown> | undefined = undefined,
+  TStamper extends Stamper = Stamper,
+>(config: ClientConfig): Client<extended, TStamper> {
+  const {
+    transport,
+    stamper,
+    organizationId,
+    key = 'zeroDevWallet',
+    name = 'ZeroDev Wallet Client',
+  } = config
+
+  // Initialize the transport with stamper
+  const {
+    config: transportConfig,
+    request,
+    value,
+  } = transport({
+    stamper,
+  })
+  const transportInstance = { ...transportConfig, ...value }
+
+  const uid = `${key}-${++clientId}`
+
+  const client = {
+    transport: transportInstance,
+    request,
+    stamper,
+    organizationId,
+    key,
+    name,
+    type: 'zeroDevWallet',
+    uid,
+  } as const
+
+  function extend(base: typeof client) {
+    type ExtendFn = (base: typeof client) => Record<string, unknown>
+    return (extendFn: ExtendFn) => {
+      const extended = extendFn(base) as Record<string, unknown>
+
+      // Remove base properties from extended to avoid conflicts
+      for (const key in client) {
+        delete extended[key]
+      }
+
+      // Combine base client with extensions
+      const combined = { ...base, ...extended }
+
+      // Return new client with updated extend function
+      return Object.assign(combined, { extend: extend(combined as any) })
+    }
+  }
+
+  return Object.assign(client, { extend: extend(client) as any }) as Client<
+    extended,
+    TStamper
+  >
+}
+
+export type ZeroDevWalletClient<TStamper extends Stamper = Stamper> = Client<
+  ZeroDevWalletActions,
+  TStamper
+>
+
+/**
+ * Creates a ZeroDev Wallet client with ZeroDev Wallet actions pre-loaded.
+ * This is equivalent to calling createBaseClient(config).extend(zeroDevWalletActions).
+ *
+ * For a client without pre-loaded actions, use createBaseClient().
+ */
+export function createClient<TStamper extends Stamper = Stamper>(
+  config: ClientConfig<TStamper>,
+): ZeroDevWalletClient<TStamper> {
+  const { key = 'zeroDevWallet', name = 'ZeroDev Wallet Client' } = config
+  const client = createBaseClient({
+    ...config,
+    key,
+    name,
+  })
+  return client.extend(zeroDevWalletActions) as ZeroDevWalletClient<TStamper>
+}

package/src/client/decorators/client.ts

@@ -0,0 +1,152 @@
+import {
+  type LoginWithStampParameters,
+  type LoginWithStampReturnType,
+  loginWithStamp,
+} from '../../actions/auth/loginWithStamp.js'
+import {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithEmail,
+  authenticateWithOAuth,
+  type GetUserWalletParameters,
+  type GetUserWalletReturnType,
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getUserWallet,
+  getWhoami,
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithOTP,
+  registerWithPasskey,
+  type SignRawPayloadParameters,
+  type SignRawPayloadReturnType,
+  signRawPayload,
+} from '../../actions/index.js'
+import {
+  type SignTransactionParameters,
+  type SignTransactionReturnType,
+  signTransaction,
+} from '../../actions/wallet/signTransaction.js'
+import type { Client } from '../types.js'
+
+/**
+ * ZeroDev Wallet client actions that can be performed with a client
+ */
+export type ZeroDevWalletActions = {
+  // Auth actions
+  /**
+   * Authenticates a user with their email address
+   */
+  authenticateWithEmail: (
+    params: AuthenticateWithEmailParameters,
+  ) => Promise<AuthenticateWithEmailReturnType>
+
+  /**
+   * Authenticates a user with OAuth credentials
+   */
+  authenticateWithOAuth: (
+    params: AuthenticateWithOAuthParameters,
+  ) => Promise<AuthenticateWithOAuthReturnType>
+
+  /**
+   * Gets the current user information
+   */
+  getWhoami: (params: GetWhoamiParameters) => Promise<GetWhoamiReturnType>
+
+  // Wallet actions
+  /**
+   * Gets the user's wallet information
+   */
+  getUserWallet: (
+    params: GetUserWalletParameters,
+  ) => Promise<GetUserWalletReturnType>
+
+  /**
+   * Signs a raw payload with the user's wallet
+   */
+  signRawPayload: (
+    params: SignRawPayloadParameters,
+  ) => Promise<SignRawPayloadReturnType>
+
+  /**
+   * Signs a transaction with the user's wallet
+   */
+  signTransaction: (
+    params: SignTransactionParameters,
+  ) => Promise<SignTransactionReturnType>
+
+  /**
+   * Registers a passkey with the user's wallet
+   */
+  registerWithPasskey: (
+    params: RegisterWithPasskeyParameters,
+  ) => Promise<RegisterWithPasskeyReturnType>
+
+  /**
+   * Logs in a user with a stamp
+   */
+  loginWithStamp: (
+    params: LoginWithStampParameters,
+  ) => Promise<LoginWithStampReturnType>
+
+  /**
+   * Registers a user with OTP (One-Time Password) authentication
+   */
+  registerWithOTP: (
+    params: RegisterWithOTPParameters,
+  ) => Promise<RegisterWithOTPReturnType>
+
+  /**
+   * Logs in a user with OTP (One-Time Password) authentication
+   */
+  loginWithOTP: (
+    params: LoginWithOTPParameters,
+  ) => Promise<LoginWithOTPReturnType>
+}
+
+/**
+ * Decorator function that adds ZeroDev Wallet client actions to a client
+ *
+ * @param client - The base client to extend
+ * @returns An object containing all ZeroDev Wallet client actions bound to the client
+ *
+ * @example
+ * ```ts
+ * import { createClient, zeroDevWalletTransport, zeroDevWalletActions } from '@zerodev/wallet-core';
+ *
+ * const client = createClient({
+ *   transport: zeroDevWalletTransport({ baseUrl: 'https://api.example.com' }),
+ *   stamper: myStamper,
+ * }).extend(zeroDevWalletActions);
+ *
+ * // Now you can use actions directly on the client
+ * const userInfo = await client.getWhoami({
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456'
+ * });
+ * ```
+ */
+export function zeroDevWalletActions(client: Client): ZeroDevWalletActions {
+  return {
+    // Auth actions
+    authenticateWithEmail: (params) => authenticateWithEmail(client, params),
+    authenticateWithOAuth: (params) => authenticateWithOAuth(client, params),
+    getWhoami: (params) => getWhoami(client, params),
+
+    // Wallet actions
+    getUserWallet: (params) => getUserWallet(client, params),
+    signRawPayload: (params) => signRawPayload(client, params),
+    signTransaction: (params) => signTransaction(client, params),
+    registerWithPasskey: (params) => registerWithPasskey(client, params),
+    loginWithStamp: (params) => loginWithStamp(client, params),
+    registerWithOTP: (params) => registerWithOTP(client, params),
+    loginWithOTP: (params) => loginWithOTP(client, params),
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,12 @@
+export {
+  createBaseClient,
+  createClient,
+  type ZeroDevWalletClient,
+} from './createClient.js'
+export { zeroDevWalletTransport } from './transports/createTransport.js'
+export type {
+  Client,
+  ClientConfig,
+  Transport,
+  TransportConfig,
+} from './types.js'

package/src/client/transports/createTransport.ts

@@ -0,0 +1,52 @@
+import type { Transport } from '../types.js'
+import { rest } from './rest.js'
+
+export type CreateTransportOptions = {
+  /** Base URL for the API */
+  baseUrl: string
+  /** Request timeout in milliseconds */
+  timeoutMs?: number
+  /** Transport key identifier */
+  key?: string
+  /** Transport name */
+  name?: string
+}
+
+/**
+ * Creates a transport for the ZeroDev Wallet client.
+ * Requires a stamper for authenticated requests.
+ */
+export function zeroDevWalletTransport(
+  options: CreateTransportOptions,
+): Transport {
+  const {
+    baseUrl,
+    timeoutMs = 10_000,
+    key = 'zeroDevWallet',
+    name = 'ZeroDev Wallet Transport',
+  } = options
+
+  return ({ stamper }) => {
+    // Create REST transport with stamper
+    const transport = rest(baseUrl, {
+      timeoutMs,
+      key,
+      name,
+      stamper,
+    })
+
+    return {
+      config: {
+        name,
+        key,
+        url: baseUrl,
+        timeoutMs,
+        type: 'zeroDevWallet',
+      },
+      request: transport.request,
+      value: {
+        stamper,
+      },
+    }
+  }
+}

package/src/client/transports/rest.ts

@@ -0,0 +1,121 @@
+import { RestRequestError, RestTimeoutError } from '../../errors/request.js'
+import type { Stamper } from '../../stampers/types.js'
+
+export type RestRequestArgs = {
+  path: string
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
+  body?: any
+  headers?: Record<string, string>
+  stamp?: boolean // When true, will stamp the request body
+}
+
+export type RestRequestFn = <T = any>(args: RestRequestArgs) => Promise<T>
+
+export type RestTransport = {
+  config: { key: string; name: string; url: string; timeoutMs: number }
+  request: RestRequestFn
+  value: Record<string, unknown>
+}
+
+export type RestTransportConfig = {
+  fetchOptions?: Omit<RequestInit, 'body' | 'method' | 'signal'>
+  onRequest?: (
+    url: string,
+    init: RequestInit,
+  ) => Promise<RequestInit | undefined> | RequestInit | undefined
+  onResponse?: (res: Response) => Promise<void> | void
+  timeoutMs?: number
+  key?: string
+  name?: string
+  stamper?: Stamper
+}
+
+export function rest(
+  url: string,
+  cfg: RestTransportConfig = {},
+): RestTransport {
+  const timeoutMs = cfg.timeoutMs ?? 10_000
+  const key = cfg.key ?? 'rest'
+  const name = cfg.name ?? 'HTTP REST'
+
+  const request: RestRequestFn = async (args) => {
+    const fullUrl = `${url}/${args.path}`
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+      let requestBody = args.body
+      const requestHeaders = {
+        'content-type': 'application/json',
+        ...(args.headers ?? {}),
+        ...(cfg.fetchOptions?.headers ?? {}),
+      }
+
+      // Handle stamping if requested
+      if (args.stamp && cfg.stamper) {
+        const { body, apiUrl } = args.body
+        const bodyString = `${JSON.stringify(body ?? args.body)}\n`
+        const stamp = await cfg.stamper.stamp(bodyString)
+
+        // Restructure request body to match backend expectation
+        if (body) {
+          requestBody = {
+            body: bodyString,
+            stamp: {
+              stampHeaderName: stamp.stampHeaderName,
+              stampHeaderValue: stamp.stampHeaderValue,
+            },
+            apiUrl: apiUrl,
+          }
+        } else {
+          requestBody = {
+            ...args.body,
+            stamp: {
+              stampHeaderName: stamp.stampHeaderName,
+              stampHeaderValue: stamp.stampHeaderValue,
+            },
+          }
+        }
+      }
+
+      const init: RequestInit = {
+        ...cfg.fetchOptions,
+        method: args.method ?? 'POST',
+        headers: requestHeaders,
+        body: requestBody != null ? JSON.stringify(requestBody) : null,
+        signal: controller.signal,
+      }
+
+      const finalInit = (await cfg.onRequest?.(fullUrl, init)) ?? init
+      const res = await fetch(fullUrl, finalInit)
+
+      await cfg.onResponse?.(res)
+
+      let data: any
+      const ct = res.headers.get('content-type') ?? ''
+      if (ct.startsWith('application/json')) data = await res.json()
+      else {
+        const text = await res.text()
+        try {
+          data = text ? JSON.parse(text) : {}
+        } catch {
+          data = text
+        }
+      }
+
+      if (!res.ok) throw new RestRequestError(fullUrl, res.status, data)
+      return data as any
+    } catch (err: any) {
+      if (err.name === 'AbortError') throw new RestTimeoutError(fullUrl)
+      throw err
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return {
+    config: { key, name, url, timeoutMs },
+    request,
+    value: {},
+  }
+}