accounts 0.12.2 → 0.13.0

package/src/core/internal/AccessKeyTransaction.ts

@@ -0,0 +1,243 @@
+import { Address, Hex } from 'ox'
+import { KeyAuthorization } from 'ox/tempo'
+import type { Client, Transport } from 'viem'
+import { prepareTransactionRequest } from 'viem/actions'
+import type { PrepareTransactionRequestReturnType } from 'viem/actions'
+import type { Transaction as TempoTransaction } from 'viem/tempo'
+
+import * as AccessKey from '../AccessKey.js'
+import * as ExecutionError from '../ExecutionError.js'
+import type * as Store from '../Store.js'
+import type * as Rpc from '../zod/rpc.js'
+
+type Call = {
+  to?: Address.Address | undefined
+  data?: Hex.Hex | undefined
+}
+
+type Selection = NonNullable<Awaited<ReturnType<typeof AccessKey.select>>>
+
+const removalErrorNames = new Set([
+  'InvalidSignature',
+  'InvalidSignatureFormat',
+  'InvalidSignatureType',
+  'KeyAlreadyRevoked',
+  'KeyExpired',
+  'KeyNotFound',
+  'SignatureTypeMismatch',
+])
+
+/** Creates a lifecycle-aware access-key transaction when a matching key is available. */
+export async function create(options: create.Options): Promise<create.ReturnType> {
+  const { address, calls, chainId, client, store } = options
+  const selection = await AccessKey.select({
+    account: address,
+    calls,
+    chainId,
+    client,
+    store,
+  })
+  if (!selection) return undefined
+  return createTransaction({ client, selection, store })
+}
+
+export declare namespace create {
+  /** Options for {@link create}. */
+  type Options = {
+    /** Root account address. */
+    address: Address.Address
+    /** Calls to match against access key scopes. */
+    calls?: readonly Call[] | undefined
+    /** Chain ID the access key must be authorized on. */
+    chainId: number
+    /** Client used to prepare, submit, and check access-key transactions. */
+    client: Client<Transport>
+    /** Reactive state store. */
+    store: Store.Store
+  }
+
+  /** Parameters accepted when preparing an access-key transaction. */
+  type PrepareParameters = Omit<
+    TempoTransaction.TransactionRequestTempo,
+    'account' | 'keyAuthorization' | 'type'
+  >
+
+  /** Prepared transaction request returned by viem. */
+  type PreparedRequest = PrepareTransactionRequestReturnType
+
+  /** Parameters accepted by `eth_fillTransaction`. */
+  type FillParameters = Rpc.eth_fillTransaction.Decoded['params'][0]
+
+  /** Result returned by `eth_fillTransaction`. */
+  type FillReturnType = Rpc.eth_fillTransaction.Encoded['returns']
+
+  /** Result returned by `eth_sendTransactionSync`. */
+  type SendSyncReturnType = Rpc.eth_sendTransactionSync.Encoded['returns']
+
+  /** Prepared access-key transaction with lifecycle-aware execution methods. */
+  type Prepared = {
+    /** Prepared request that will be signed by the selected access key. */
+    request: PreparedRequest
+    /** Signs the prepared transaction and marks an attached authorization as pending. */
+    sign(): Promise<Hex.Hex>
+    /** Signs and submits the transaction asynchronously. */
+    send(): Promise<Hex.Hex>
+    /** Signs, submits, and waits for the transaction to be accepted. */
+    sendSync(): Promise<SendSyncReturnType>
+  }
+
+  /** Lifecycle-aware access-key transaction. */
+  type Transaction = {
+    /** Fills a transaction, attaching a pending key authorization when needed. */
+    fill(parameters: FillParameters): Promise<FillReturnType>
+    /** Prepares a transaction, attaching a pending key authorization when needed. */
+    prepare(parameters: PrepareParameters): Promise<Prepared>
+  }
+
+  /** Lifecycle-aware access-key transaction, if one is available. */
+  type ReturnType = Transaction | undefined
+}
+
+function createTransaction(options: {
+  client: Client<Transport>
+  selection: Selection
+  store: Store.Store
+}): create.Transaction {
+  const { client, selection, store } = options
+  return {
+    async fill(parameters) {
+      try {
+        return await fillTransaction(client, {
+          ...parameters,
+          ...(!parameters.keyAuthorization && selection.authorization
+            ? {
+                keyAuthorization: {
+                  address: selection.authorization.address,
+                  ...KeyAuthorization.toRpc(selection.authorization),
+                } as never,
+              }
+            : {}),
+        } as never)
+      } catch (error) {
+        removeForError(error, selection, { store })
+        throw error
+      }
+    },
+    async prepare(parameters) {
+      try {
+        const request = await prepareTransactionRequest(client, {
+          account: selection.account,
+          ...parameters,
+          ...(selection.authorization ? { keyAuthorization: selection.authorization } : {}),
+          type: 'tempo',
+        } as never)
+        return createPreparedTransaction({
+          client,
+          request: request as never,
+          selection,
+          store,
+        })
+      } catch (error) {
+        removeForError(error, selection, { store })
+        throw error
+      }
+    },
+  }
+}
+
+function createPreparedTransaction(options: {
+  client: Client<Transport>
+  request: create.PreparedRequest
+  selection: Selection
+  store: Store.Store
+}): create.Prepared {
+  const { client, request, selection, store } = options
+
+  async function sign() {
+    try {
+      const signed = await selection.account.signTransaction(request as never)
+      if (selection.authorization)
+        AccessKey.markPending({
+          accessKey: selection.accessKey,
+          account: selection.record.access,
+          chainId: selection.record.chainId,
+          store,
+        })
+      return signed
+    } catch (error) {
+      removeForError(error, selection, { store })
+      throw error
+    }
+  }
+
+  return {
+    request,
+    sign,
+    async send() {
+      try {
+        const signed = await sign()
+        return (await client.request({
+          method: 'eth_sendRawTransaction' as never,
+          params: [signed],
+        })) as Hex.Hex
+      } catch (error) {
+        removeForError(error, selection, { store })
+        throw error
+      }
+    },
+    async sendSync() {
+      try {
+        const signed = await sign()
+        const result = await client.request({
+          method: 'eth_sendRawTransactionSync' as never,
+          params: [signed],
+        })
+        AccessKey.markPublished({
+          accessKey: selection.accessKey,
+          account: selection.record.access,
+          chainId: selection.record.chainId,
+          store,
+        })
+        return result as create.SendSyncReturnType
+      } catch (error) {
+        removeForError(error, selection, { store })
+        throw error
+      }
+    },
+  }
+}
+
+async function fillTransaction(
+  client: Client<Transport>,
+  parameters: create.FillParameters,
+): Promise<create.FillReturnType> {
+  const { keyAuthorization, ...rest } = parameters as create.FillParameters & {
+    keyAuthorization?: unknown
+  }
+  const formatter = client.chain?.formatters?.transactionRequest
+  const formatted = formatter ? formatter.format({ ...rest } as never, 'fillTransaction') : rest
+  return (await client.request({
+    method: 'eth_fillTransaction' as never,
+    params: [{ ...formatted, ...(keyAuthorization ? { keyAuthorization } : {}) } as never],
+  })) as create.FillReturnType
+}
+
+function removeForError(
+  error: unknown,
+  selection: Selection,
+  options: { store: Store.Store },
+): void {
+  if (!shouldRemoveForError(error)) return
+  AccessKey.remove({
+    accessKey: selection.accessKey,
+    account: selection.record.access,
+    chainId: selection.record.chainId,
+    store: options.store,
+  })
+}
+
+function shouldRemoveForError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  const parsed = ExecutionError.parse(error)
+  return removalErrorNames.has(parsed.errorName)
+}

package/src/core/{mppx.test.ts → mppx.localnet.test.ts}

@@ -66,7 +66,7 @@ describe('mppx integration', () => {
     `)
   })
 
-  test('pull mode publishes a pending access key on first charge', async () => {
+  test('pull mode publishes a pending access key authorization', async () => {
     const provider = Provider.create({
       adapter: headlessWebAuthn(),
       chains: [chain],
@@ -85,6 +85,9 @@ describe('mppx integration', () => {
 
     const res = await fetch(`${server.url}/fortune`)
     expect(res.status).toBe(200)
+
+    const status = await provider.getAccessKeyStatus({ accessKey: key.address })
+    expect(status).toMatchInlineSnapshot(`"published"`)
     expect(provider.store.getState().accessKeys[0]!.keyAuthorization).toBeUndefined()
 
     const metadata = await Actions.accessKey.getMetadata(client, {
@@ -94,7 +97,7 @@ describe('mppx integration', () => {
     expect(metadata.isRevoked).toMatchInlineSnapshot(`false`)
   })
 
-  test('pull mode keeps pending access key after failed verification', async () => {
+  test('pull mode keeps access key authorization pending after failed verification', async () => {
     const failingServer = await createServer(async (req, res) => {
       if (req.headers.authorization) {
         res.writeHead(402, { 'Content-Type': 'application/json' })
@@ -122,14 +125,41 @@ describe('mppx integration', () => {
         method: 'wallet_authorizeAccessKey',
         params: [{ expiry: Expiry.days(1) }],
       })
+      const key = provider.store.getState().accessKeys[0]!
 
       const res = await fetch(`${failingServer.url}/fortune`)
       expect(res.status).toMatchInlineSnapshot(`402`)
       expect(provider.store.getState().accessKeys[0]!.keyAuthorization).toBeDefined()
+
+      const status = await provider.getAccessKeyStatus({ accessKey: key.address })
+      expect(status).toMatchInlineSnapshot(`"pending"`)
     } finally {
       await failingServer.closeAsync()
     }
   })
+
+  test('push mode publishes pending access key authorization', async () => {
+    const provider = Provider.create({
+      adapter: headlessWebAuthn(),
+      chains: [chain],
+      mpp: { mode: 'push' },
+    })
+    const address = await connect(provider)
+    await fund(address)
+
+    await provider.request({
+      method: 'wallet_authorizeAccessKey',
+      params: [{ expiry: Expiry.days(1) }],
+    })
+    const key = provider.store.getState().accessKeys[0]!
+
+    const res = await fetch(`${server.url}/fortune`)
+    expect(res.status).toMatchInlineSnapshot(`200`)
+
+    const status = await provider.getAccessKeyStatus({ accessKey: key.address })
+    expect(status).toMatchInlineSnapshot(`"published"`)
+    expect(provider.store.getState().accessKeys[0]!.keyAuthorization).toBeUndefined()
+  })
 })
 
 async function connect(provider: ReturnType<typeof Provider.create>) {

package/src/core/zod/request.test.ts

@@ -115,6 +115,42 @@ describe('validate', () => {
     `)
   })
 
+  test('default: validates wallet_deposit with amount and token symbol', () => {
+    const result = RpcRequest.validate(Schema.Request, {
+      method: 'wallet_deposit',
+      params: [
+        {
+          amount: '50',
+          displayName: 'DoorDash',
+          token: 'USDC',
+        },
+      ],
+    })
+    expect(result._decoded).toMatchInlineSnapshot(`
+      {
+        "method": "wallet_deposit",
+        "params": [
+          {
+            "amount": "50",
+            "displayName": "DoorDash",
+            "token": "USDC",
+          },
+        ],
+      }
+    `)
+  })
+
+  test('default: validates wallet_deposit without params', () => {
+    const result = RpcRequest.validate(Schema.Request, {
+      method: 'wallet_deposit',
+    })
+    expect(result._decoded).toMatchInlineSnapshot(`
+      {
+        "method": "wallet_deposit",
+      }
+    `)
+  })
+
   test('behavior: preserves original request properties', () => {
     const result = RpcRequest.validate(Schema.Request, {
       method: 'eth_accounts',

package/src/core/zod/rpc.ts

@@ -746,16 +746,23 @@ export namespace wallet_switchEthereumChain {
 export namespace wallet_deposit {
   export const schema = Schema.defineItem({
     method: z.literal('wallet_deposit'),
-    params: z.readonly(
-      z.tuple([
-        z.object({
-          address: z.optional(u.address()),
-          chainId: z.optional(u.number()),
-          displayName: z.optional(z.string()),
-          token: z.optional(u.address()),
-          value: z.optional(z.string()),
-        }),
-      ]),
+    params: z.optional(
+      z.readonly(
+        z.tuple([
+          z.object({
+            address: z.optional(u.address()),
+            /** Human-readable amount to pre-fill (e.g. `"50"`). */
+            amount: z.optional(z.string()),
+            chainId: z.optional(u.number()),
+            displayName: z.optional(z.string()),
+            /**
+             * Token to pre-fill, accepted as either a contract address or a
+             * supported deposit token symbol (case-insensitive, e.g. `"USDC"`).
+             */
+            token: z.optional(z.union([u.address(), z.string()])),
+          }),
+        ]),
+      ),
     ),
     returns: z.optional(
       z.object({

package/src/index.ts

@@ -1,4 +1,3 @@
-export * as AccessKey from './core/AccessKey.js'
 export * as Adapter from './core/Adapter.js'
 export * as IntersectionObserver from './core/IntersectionObserver.js'
 export * as Dialog from './core/Dialog.js'
@@ -15,6 +14,7 @@ export * as TrustedHosts from './core/TrustedHosts.js'
 export * as WebAuthnCeremony from './core/WebAuthnCeremony.js'
 export { dialog, dialog as tempoWallet } from './core/adapters/dialog.js'
 export { local } from './core/adapters/local.js'
+export { privy } from './core/adapters/privy.js'
 export { turnkey } from './core/adapters/turnkey.js'
 export { webAuthn } from './core/adapters/webAuthn.js'
 export {

package/src/react-native/adapter.ts

@@ -8,11 +8,11 @@ import {
   RpcResponse,
 } from 'ox'
 import { KeyAuthorization } from 'ox/tempo'
-import { prepareTransactionRequest } from 'viem/actions'
 import { Actions, Account as TempoAccount, Secp256k1 } from 'viem/tempo'
 
 import * as AccessKey from '../core/AccessKey.js'
 import * as Adapter from '../core/Adapter.js'
+import * as AccessKeyTransaction from '../core/internal/AccessKeyTransaction.js'
 import type * as Storage from '../core/Storage.js'
 
 /**
@@ -58,19 +58,19 @@ export function reactNative(options: reactNative.Options): Adapter.Adapter {
       const keyAuthorization = deserialized as KeyAuthorization.Signed
 
       if (keyAuthorization.address.toLowerCase() === keyAddress.toLowerCase())
-        AccessKey.save({
-          address,
-          keyAuthorization,
+        AccessKey.add({
+          account: address,
+          authorization: keyAuthorization,
           privateKey: entry.key,
           store,
         })
       else
-        store.setState((state) => ({
-          accessKeys: state.accessKeys.filter(
-            (accessKey) =>
-              accessKey.address.toLowerCase() !== keyAuthorization.address.toLowerCase(),
-          ),
-        }))
+        AccessKey.remove({
+          account: address,
+          accessKey: keyAuthorization.address,
+          chainId: Number(keyAuthorization.chainId),
+          store,
+        })
 
       return {
         account,
@@ -127,9 +127,9 @@ export function reactNative(options: reactNative.Options): Adapter.Adapter {
     ) {
       if (!managedKey) return
 
-      AccessKey.save({
-        address,
-        keyAuthorization,
+      AccessKey.add({
+        account: address,
+        authorization: keyAuthorization,
         privateKey: managedKey.key,
         store,
       })
@@ -189,27 +189,37 @@ export function reactNative(options: reactNative.Options): Adapter.Adapter {
       return result.keyAuthorization
     }
 
-    async function withManagedAccessKey<result>(
-      fn: (
-        account: TempoAccount.Account,
-        keyAuthorization?: KeyAuthorization.Signed | undefined,
-      ) => Promise<result>,
+    async function prepareManagedTransaction(
+      client: ReturnType<typeof getClient>,
+      parameters: AccessKeyTransaction.create.PrepareParameters,
+      options: {
+        calls?: AccessKeyTransaction.create.Options['calls'] | undefined
+        chainId?: number | undefined
+      } = {},
     ) {
-      const rootAddress = store.getState().accounts[store.getState().activeAccount]?.address
-      const managedKey = rootAddress ? await loadManagedKey(rootAddress) : undefined
-
-      const account = managedKey?.account ?? getAccount({ signable: true })
-      let keyAuthorization = AccessKey.getPending(account, { store })
-      if (rootAddress && managedKey && !keyAuthorization)
-        if (!(await isManagedKeyAuthorized(rootAddress, managedKey)))
-          keyAuthorization = await reauthorizeManagedKey(rootAddress, managedKey)
+      const state = store.getState()
+      const address = parameters.from ?? state.accounts[state.activeAccount]?.address
+      if (!address) throw new core_Provider.DisconnectedError({ message: 'No active account.' })
+      const managedKey = await loadManagedKey(address)
+      if (managedKey && !(await isManagedKeyAuthorized(address, managedKey)))
+        await reauthorizeManagedKey(address, managedKey)
+      const transaction = await AccessKeyTransaction.create({
+        address,
+        calls: options.calls,
+        chainId: options.chainId ?? state.chainId,
+        client,
+        store,
+      })
+      if (!transaction)
+        throw new core_Provider.UnauthorizedError({
+          message: `Account "${address}" cannot sign with an access key.`,
+        })
+      return await transaction.prepare(parameters)
+    }
 
-      try {
-        return await fn(account, keyAuthorization ?? undefined)
-      } catch (error) {
-        AccessKey.remove(account, { store })
-        throw error
-      }
+    async function loadManagedAccount(address: Adapter.signPersonalMessage.Parameters['address']) {
+      await loadManagedKey(address)
+      return getAccount({ address, signable: true })
     }
 
     async function authorize(request: {
@@ -333,74 +343,57 @@ export function reactNative(options: reactNative.Options): Adapter.Adapter {
         async sendTransaction(parameters) {
           const { feePayer, ...rest } = parameters
           const client = getClient(typeof feePayer === 'string' ? { feePayer } : {})
-          const { account, prepared } = await withManagedAccessKey(
-            async (account, keyAuthorization) => ({
-              account,
-              prepared: await prepareTransactionRequest(client, {
-                account,
-                ...rest,
-                ...(feePayer ? { feePayer: true } : {}),
-                ...(keyAuthorization ? { keyAuthorization } : {}),
-                type: 'tempo',
-              } as never),
-            }),
+          const prepared = await prepareManagedTransaction(
+            client,
+            {
+              ...rest,
+              ...(feePayer ? { feePayer: true } : {}),
+            },
+            {
+              calls: parameters.calls as AccessKeyTransaction.create.Options['calls'],
+              chainId: parameters.chainId,
+            },
           )
-          const signed = await account.signTransaction(prepared as never)
-          const result = await client.request({
-            method: 'eth_sendRawTransaction' as never,
-            params: [signed],
-          })
-          AccessKey.removePending(account, { store })
-          return result
+          return await prepared.send()
         },
         async sendTransactionSync(parameters) {
           const { feePayer, ...rest } = parameters
           const client = getClient(typeof feePayer === 'string' ? { feePayer } : {})
-          const { account, prepared } = await withManagedAccessKey(
-            async (account, keyAuthorization) => ({
-              account,
-              prepared: await prepareTransactionRequest(client, {
-                account,
-                ...rest,
-                ...(feePayer ? { feePayer: true } : {}),
-                ...(keyAuthorization ? { keyAuthorization } : {}),
-                type: 'tempo',
-              } as never),
-            }),
+          const prepared = await prepareManagedTransaction(
+            client,
+            {
+              ...rest,
+              ...(feePayer ? { feePayer: true } : {}),
+            },
+            {
+              calls: parameters.calls as AccessKeyTransaction.create.Options['calls'],
+              chainId: parameters.chainId,
+            },
           )
-          const signed = await account.signTransaction(prepared as never)
-          const result = await client.request({
-            method: 'eth_sendRawTransactionSync' as never,
-            params: [signed],
-          })
-          AccessKey.removePending(account, { store })
-          return result
+          return await prepared.sendSync()
         },
         async signPersonalMessage({ address, data }) {
-          await loadManagedKey(address)
-          const account = getAccount({ address, signable: true })
+          const account = await loadManagedAccount(address)
           return await account.signMessage({ message: { raw: data } })
         },
         async signTransaction(parameters) {
           const { feePayer, ...rest } = parameters
           const client = getClient(typeof feePayer === 'string' ? { feePayer } : {})
-          const { account, prepared } = await withManagedAccessKey(
-            async (account, keyAuthorization) => ({
-              account,
-              prepared: await prepareTransactionRequest(client, {
-                account,
-                ...rest,
-                ...(feePayer ? { feePayer: true } : {}),
-                ...(keyAuthorization ? { keyAuthorization } : {}),
-                type: 'tempo',
-              } as never),
-            }),
+          const prepared = await prepareManagedTransaction(
+            client,
+            {
+              ...rest,
+              ...(feePayer ? { feePayer: true } : {}),
+            },
+            {
+              calls: parameters.calls as AccessKeyTransaction.create.Options['calls'],
+              chainId: parameters.chainId,
+            },
           )
-          return await account.signTransaction(prepared as never)
+          return await prepared.sign()
         },
         async signTypedData({ address, data }) {
-          await loadManagedKey(address)
-          const account = getAccount({ address, signable: true })
+          const account = await loadManagedAccount(address)
           return await account.signTypedData(JSON.parse(data) as never)
         },
       },