@alchemy/wallet-apis 0.0.0-alpha.19 → 0.0.0-alpha.21

package/src/actions/requestAccount.ts

@@ -5,8 +5,12 @@ import deepEqual from "deep-equal";
 import type { DistributiveOmit, InnerWalletApiClient } from "../types";
 import { LOGGER } from "../logger.js";
 import { isLocalAccount } from "../utils/assertions.js";
-import { Value } from "typebox/value";
-import { methodSchema, type MethodParams } from "../utils/schema.js";
+import {
+  methodSchema,
+  encode,
+  decode,
+  type MethodParams,
+} from "../utils/schema.js";
 
 const schema = methodSchema(MethodSchema);
 type BaseRequestAccountParams = MethodParams<typeof MethodSchema>;
@@ -90,17 +94,14 @@ export async function requestAccount(
     };
   }
 
-  const rpcParams = Value.Encode(
-    schema.request,
-    args satisfies BaseRequestAccountParams,
-  );
+  const rpcParams = encode(schema.request, args);
 
   const rpcResp = await client.request({
     method: "wallet_requestAccount",
     params: [rpcParams],
   });
 
-  const resp = Value.Decode(schema.response, rpcResp);
+  const resp = decode(schema.response, rpcResp);
 
   client.internal?.setAccount({
     address: resp.accountAddress,

package/src/actions/sendCalls.ts

@@ -8,10 +8,7 @@ import {
 } from "./sendPreparedCalls.js";
 import { LOGGER } from "../logger.js";
 import { signSignatureRequest } from "./signSignatureRequest.js";
-import {
-  extractCapabilitiesForSending,
-  fromRpcCapabilities,
-} from "../utils/capabilities.js";
+import { extractCapabilitiesForSending } from "../utils/capabilities.js";
 
 export type SendCallsParams = Prettify<
   DistributiveOmit<PrepareCallsParams, "chainId"> & {
@@ -77,10 +74,7 @@ export async function sendCalls(
     );
 
     const secondCallParams = {
-      account: calls.modifiedRequest.from,
-      calls: calls.modifiedRequest.calls,
-      chainId: calls.modifiedRequest.chainId,
-      capabilities: fromRpcCapabilities(calls.modifiedRequest.capabilities),
+      ...calls.modifiedRequest,
       // WebAuthn signatures are not supported for paymaster permits (throws above).
       paymasterPermitSignature: signature as Exclude<
         typeof signature,

package/src/actions/sendPreparedCalls.ts

@@ -7,9 +7,10 @@ import {
   type WithCapabilities,
 } from "../utils/capabilities.js";
 import { wallet_sendPreparedCalls as MethodSchema } from "@alchemy/wallet-api-types/rpc";
-import { Value } from "typebox/value";
 import {
   methodSchema,
+  encode,
+  decode,
   type MethodParams,
   type MethodResponse,
 } from "../utils/schema.js";
@@ -79,10 +80,7 @@ export async function sendPreparedCalls(
           capabilities: toRpcCapabilities(capabilities),
         };
 
-  const rpcParams = Value.Encode(
-    schema.request,
-    fullParams satisfies BaseSendPreparedCallsParams,
-  );
+  const rpcParams = encode(schema.request, fullParams);
 
   const rpcResp = await client.request({
     method: "wallet_sendPreparedCalls",
@@ -90,5 +88,5 @@ export async function sendPreparedCalls(
   });
 
   LOGGER.debug("sendPreparedCalls:done");
-  return Value.Decode(schema.response, rpcResp);
+  return decode(schema.response, rpcResp);
 }

package/src/experimental/actions/requestQuoteV0.ts

@@ -7,9 +7,10 @@ import {
 } from "../../utils/capabilities.js";
 import { resolveAddress, type AccountParam } from "../../utils/resolve.js";
 import { wallet_requestQuote_v0 as MethodSchema } from "@alchemy/wallet-api-types/rpc";
-import { Value } from "typebox/value";
 import {
   methodSchema,
+  encode,
+  decode,
   type MethodParams,
   type MethodResponse,
 } from "../../utils/schema.js";
@@ -84,17 +85,17 @@ export async function requestQuoteV0(
         );
 
   const { account: _, chainId: __, ...rest } = params;
-  const rpcParams = Value.Encode(schema.request, {
+  const rpcParams = encode(schema.request, {
     ...rest,
     chainId: params.chainId ?? client.chain.id,
     from,
     ...(capabilities && { capabilities: toRpcCapabilities(capabilities) }),
-  } satisfies BaseRequestQuoteV0Params);
+  });
 
   const rpcResp = await client.request({
     method: "wallet_requestQuote_v0",
     params: [rpcParams],
   });
 
-  return Value.Decode(schema.response, rpcResp);
+  return decode(schema.response, rpcResp);
 }

package/src/utils/capabilities.ts

@@ -1,9 +1,21 @@
-import type {
-  PrepareCallsCapabilities as RpcPrepareCallsCapabilities,
-  SendPreparedCallsCapabilities as RpcSendPreparedCallsCapabilities,
+import {
+  PrepareCallsCapabilities as PrepareCallsCapabilitiesSchema,
+  SendPreparedCallsCapabilities as SendPreparedCallsCapabilitiesSchema,
 } from "@alchemy/wallet-api-types/capabilities";
+import type { StaticDecode } from "typebox";
 import type { InnerWalletApiClient } from "../types.js";
 
+/**
+ * Decoded capabilities matching the schema shape (uses `paymasterService` key).
+ * `ResolveCapabilities` renames this to `paymaster` for client-facing types.
+ */
+type DecodedPrepareCallsCaps = StaticDecode<
+  typeof PrepareCallsCapabilitiesSchema
+>;
+type DecodedSendPreparedCallsCaps = StaticDecode<
+  typeof SendPreparedCallsCapabilitiesSchema
+>;
+
 /**
  * Renames `paymasterService` (RPC) to `paymaster` in a capabilities type. This
  * is because our RPC schema's paymasterService capability does not exactly match
@@ -17,10 +29,10 @@ type ResolveCapabilities<T> = T extends {
   : T;
 
 export type PrepareCallsCapabilities =
-  ResolveCapabilities<RpcPrepareCallsCapabilities>;
+  ResolveCapabilities<DecodedPrepareCallsCaps>;
 
 export type SendPreparedCallsCapabilities =
-  ResolveCapabilities<RpcSendPreparedCallsCapabilities>;
+  ResolveCapabilities<DecodedSendPreparedCallsCaps>;
 
 /**
  * Transforms a type so that any `capabilities` field uses `paymaster`
@@ -36,7 +48,7 @@ export type WithCapabilities<T> = T extends {
 
 function hasNoPaymasterField(
   value: object,
-): value is RpcPrepareCallsCapabilities | RpcSendPreparedCallsCapabilities {
+): value is DecodedPrepareCallsCaps | DecodedSendPreparedCallsCaps {
   return !("paymaster" in value);
 }
 
@@ -51,14 +63,14 @@ function hasNoPaymasterServiceField(
  * for use with Value.Encode before sending to the RPC.
  *
  * @param {PrepareCallsCapabilities | SendPreparedCallsCapabilities | undefined} capabilities - Capabilities object containing a `paymaster` field
- * @returns {RpcPrepareCallsCapabilities | RpcSendPreparedCallsCapabilities | undefined} RPC capabilities with `paymasterService`, or undefined if input is undefined
+ * @returns {DecodedPrepareCallsCaps | DecodedSendPreparedCallsCaps | undefined} RPC capabilities with `paymasterService`, or undefined if input is undefined
  */
 export function toRpcCapabilities(
   capabilities:
     | PrepareCallsCapabilities
     | SendPreparedCallsCapabilities
     | undefined,
-): RpcPrepareCallsCapabilities | RpcSendPreparedCallsCapabilities | undefined {
+): DecodedPrepareCallsCaps | DecodedSendPreparedCallsCaps | undefined {
   if (!capabilities) return undefined;
   const { paymaster, ...rest } = capabilities;
   const result =
@@ -73,13 +85,13 @@ export function toRpcCapabilities(
  * Converts RPC capabilities (with `paymasterService`) from Value.Decode
  * to capabilities (with `paymaster`).
  *
- * @param {RpcPrepareCallsCapabilities | RpcSendPreparedCallsCapabilities | undefined} capabilities - RPC capabilities object containing a `paymasterService` field
+ * @param {DecodedPrepareCallsCaps | DecodedSendPreparedCallsCaps | undefined} capabilities - RPC capabilities object containing a `paymasterService` field
  * @returns {PrepareCallsCapabilities | SendPreparedCallsCapabilities | undefined} Capabilities with `paymaster`, or undefined if input is undefined
  */
 export function fromRpcCapabilities(
   capabilities:
-    | RpcPrepareCallsCapabilities
-    | RpcSendPreparedCallsCapabilities
+    | DecodedPrepareCallsCaps
+    | DecodedSendPreparedCallsCaps
     | undefined,
 ): PrepareCallsCapabilities | SendPreparedCallsCapabilities | undefined {
   if (!capabilities) return undefined;

package/src/utils/schema.ts

@@ -1,4 +1,12 @@
-import type { TObject, TSchema, TTuple, StaticDecode } from "typebox";
+import type {
+  TObject,
+  TSchema,
+  TTuple,
+  StaticDecode,
+  StaticEncode,
+} from "typebox";
+import { Value, EncodeError, DecodeError, Pointer } from "typebox/value";
+import { BaseError } from "@alchemy/common";
 
 /** Constraint for RPC method schemas from `@alchemy/wallet-api-types/rpc`. */
 type RpcMethodSchema = TObject<{
@@ -30,3 +38,73 @@ export type MethodParams<T extends RpcMethodSchema> = StaticDecode<
 export type MethodResponse<T extends RpcMethodSchema> = StaticDecode<
   T["properties"]["ReturnType"]
 >;
+
+/**
+ * Formats an {@link EncodeError} or {@link DecodeError} into a human-readable
+ * string describing what went wrong, including the JSON path and the schema's
+ * custom error message (if any).
+ *
+ * @param {TSchema} schema - The TypeBox schema that validation was run against.
+ * @param {EncodeError | DecodeError} error - The error thrown by {@link Value.Encode} or {@link Value.Decode}.
+ * @returns {string} A formatted error string prefixed with `"Invalid params"`.
+ */
+function formatCodecError(
+  schema: TSchema,
+  error: EncodeError | DecodeError,
+): string {
+  // Use only the first error — it's the most specific. Subsequent errors are
+  // typically cascade noise from union/anyOf branches.
+  const causeError = error.cause.errors[0];
+  // errors is typed as an open array — guard against the (practically
+  // impossible) empty case.
+  if (!causeError) return "Invalid params";
+
+  const path = causeError.instancePath || "(root)";
+
+  // Prefer the schema's custom errorMessage annotation over the generic locale message.
+  let message = causeError.message;
+  const schemaPointer = causeError.schemaPath.replace(/^#/, "");
+  if (schemaPointer) {
+    const schemaNode = Pointer.Get(schema, schemaPointer);
+    if (
+      schemaNode &&
+      typeof schemaNode === "object" &&
+      "errorMessage" in schemaNode &&
+      typeof (schemaNode as Record<string, unknown>).errorMessage === "string"
+    ) {
+      message = (schemaNode as Record<string, unknown>).errorMessage as string;
+    }
+  }
+
+  return `Invalid params: ${path}: ${message}`;
+}
+
+// Type-safe wrapper around `Value.Encode` with human-readable errors.
+export function encode<const T extends TSchema>(
+  schema: T,
+  value: StaticDecode<T>,
+): StaticEncode<T> {
+  try {
+    return Value.Encode(schema, value);
+  } catch (error) {
+    if (error instanceof EncodeError) {
+      throw new BaseError(formatCodecError(schema, error), { cause: error });
+    }
+    throw error;
+  }
+}
+
+// Type-safe wrapper around `Value.Decode` with human-readable errors.
+export function decode<const T extends TSchema>(
+  schema: T,
+  value: StaticEncode<T>,
+): StaticDecode<T> {
+  try {
+    return Value.Decode(schema, value);
+  } catch (error) {
+    if (error instanceof DecodeError) {
+      throw new BaseError(formatCodecError(schema, error), { cause: error });
+    }
+    throw error;
+  }
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is autogenerated by inject-version.ts. Any changes will be
 // overwritten on commit!
-export const VERSION = "0.0.0-alpha.19";
+export const VERSION = "0.0.0-alpha.21";