@zoralabs/coins-sdk 0.6.0 → 0.7.0

package/src/api/api-raw.ts

@@ -8,6 +8,15 @@ export const apiGet = (path: string, data?: Record<string, unknown>) =>
 export const apiPost = (path: string, data?: Record<string, unknown>) =>
   client.post({ url: path, body: data, ...getApiKeyMeta() });
 
+export const apiUrl = (path: string) => {
+  const baseUrl = client.getConfig().baseUrl ?? "";
+  // normalize the join boundary so we never end up with double slashes
+  // (or a missing slash) between the base URL and the path
+  const normalizedBase = baseUrl.replace(/\/+$/, "");
+  const normalizedPath = path.replace(/^\/+/, "");
+  return `${normalizedBase}/${normalizedPath}`;
+};
+
 export const setApiBaseUrl = (baseUrl: string) => {
   client.setConfig(createConfig({ baseUrl }));
 };

package/src/index.ts

@@ -1,6 +1,9 @@
 export {
   createCoin,
+  createCoinSmartWallet,
   createCoinCall,
+  validateCreateCoinCalls,
+  validateCreateCoinSmartWalletCalls,
   getCoinCreateFromLogs,
   CreateConstants,
 } from "./actions/createCoin";
@@ -12,18 +15,53 @@ export type {
   ContentCoinCurrency,
 } from "./actions/createCoin";
 
-export { updateCoinURI, updateCoinURICall } from "./actions/updateCoinURI";
+export {
+  updateCoinURI,
+  updateCoinURISmartWallet,
+  updateCoinURICall,
+  validateUpdateCoinURI,
+} from "./actions/updateCoinURI";
 export type { UpdateCoinURIArgs } from "./actions/updateCoinURI";
 
 export {
   updatePayoutRecipient,
+  updatePayoutRecipientSmartWallet,
   updatePayoutRecipientCall,
+  validateUpdatePayoutRecipient,
 } from "./actions/updatePayoutRecipient";
 export type { UpdatePayoutRecipientArgs } from "./actions/updatePayoutRecipient";
 
-export { tradeCoin, createTradeCall } from "./actions/tradeCoin";
+export {
+  tradeCoin,
+  tradeCoinSmartWallet,
+  createTradeCall,
+  createQuote,
+  validateTradeParameters,
+} from "./actions/tradeCoin";
 export type { TradeParameters } from "./actions/tradeCoin";
 
+// Normalized call types + user-operation adapter
+export {
+  toGenericCall,
+  toUserOperationCalls,
+  isContractCall,
+  isSendCall,
+} from "./utils/calls";
+export type {
+  GenericCall,
+  UserOperationCall,
+  ContractCall,
+  SendCall,
+} from "./utils/calls";
+
+// User Operation Utils
+export {
+  prepareUserOperation,
+  submitUserOperation,
+  CoinbaseGasError,
+} from "./utils/userOperation";
+export type { PreparedUserOperation } from "./utils/userOperation";
+
 // API Read Actions
 export * from "./api/queries";
 export type * from "./api/queries";
@@ -40,7 +78,7 @@ export type * from "./api/social";
 export { setApiKey } from "./api/api-key";
 
 // Raw API helpers
-export { apiGet, apiPost, setApiBaseUrl } from "./api/api-raw";
+export { apiGet, apiPost, apiUrl, setApiBaseUrl } from "./api/api-raw";
 
 // Metadata Validation Utils
 export * from "./metadata";

package/src/metadata/validateMetadataURIContent.ts

@@ -10,11 +10,25 @@ import { validateMetadataJSON } from "./validateMetadataJSON";
 export async function validateMetadataURIContent(
   metadataURI: ValidMetadataURI,
 ) {
+  let response: Response;
   const cleanedURI = cleanAndValidateMetadataURI(metadataURI);
-  const response = await fetch(cleanedURI);
+
+  try {
+    response = await fetch(cleanedURI);
+  } catch (error) {
+    // handle actual fetch failures (i.e. network errors)
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Metadata fetch failed for URL '${cleanedURI}': ${errorMessage}`,
+    );
+  }
+
   if (!response.ok) {
-    throw new Error("Metadata fetch failed");
+    throw new Error(
+      `Metadata fetch failed for URL '${cleanedURI}': ${response.statusText ? `${response.statusText} (HTTP ${response.status})` : `HTTP ${response.status}`}`,
+    );
   }
+
   if (
     !["application/json", "text/plain"].includes(
       response.headers.get("content-type") ?? "",
@@ -22,6 +36,7 @@ export async function validateMetadataURIContent(
   ) {
     throw new Error("Metadata is not a valid JSON or plain text response type");
   }
+
   const metadataJson = await response.json();
   return validateMetadataJSON(metadataJson);
 }

package/src/utils/calls.ts

@@ -0,0 +1,129 @@
+import {
+  type Abi,
+  type Address,
+  concatHex,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type ContractFunctionParameters,
+  encodeFunctionData,
+  type Hex,
+} from "viem";
+
+const EMPTY_HEX: Hex = "0x";
+
+type WritableMutability = "payable" | "nonpayable";
+
+type WritableFunction<abi extends Abi | readonly unknown[]> =
+  ContractFunctionName<abi, WritableMutability>;
+
+type WritableArgs<
+  abi extends Abi | readonly unknown[],
+  functionName extends WritableFunction<abi>,
+> = ContractFunctionArgs<abi, WritableMutability, functionName>;
+
+export type ContractCall<
+  abi extends Abi | readonly unknown[] = readonly unknown[],
+  fn extends WritableFunction<abi> = WritableFunction<abi>,
+  args extends WritableArgs<abi, fn> = WritableArgs<abi, fn>,
+> = ContractFunctionParameters<abi, WritableMutability, fn, args> & {
+  /** Optional ETH value to send with the call. */
+  value?: bigint;
+  /**
+   * Optional calldata appended after the encoded function data, e.g. for
+   * attribution. Mirrors viem's `dataSuffix`; concatenated by {@link toGenericCall}.
+   */
+  dataSuffix?: Hex;
+};
+
+export const isContractCall = (
+  call: ContractCall | SendCall,
+): call is ContractCall => {
+  return (
+    (call as ContractCall).address !== undefined &&
+    (call as ContractCall).abi !== undefined &&
+    (call as ContractCall).functionName !== undefined
+  );
+};
+
+export type SendCall = {
+  to: Address;
+  value?: bigint;
+};
+
+export const isSendCall = (call: ContractCall | SendCall): call is SendCall => {
+  return !isContractCall(call) && (call as SendCall).to !== undefined;
+};
+
+/**
+ * A normalized, fully-encoded contract call.
+ *
+ * This is the canonical call shape emitted by the action `createAndValidate*Calls`
+ * builders. It intentionally matches the encoded-call form accepted by both
+ * `walletClient.sendTransaction` (EOA execution) and viem's bundler client
+ * `prepareUserOperation` / `sendUserOperation` (smart wallet / user operation
+ * execution), so a single call list can drive either flow.
+ */
+export type GenericCall = {
+  to: Address;
+  data: Hex;
+  value: bigint;
+};
+
+/**
+ * The encoded-call shape accepted by viem's bundler client `calls` parameter
+ * (`prepareUserOperation` / `sendUserOperation`).
+ *
+ * `data` and `value` are optional on viem's side; we always populate them from a
+ * {@link GenericCall}.
+ */
+export type UserOperationCall = {
+  to: Address;
+  data?: Hex;
+  value?: bigint;
+};
+
+/**
+ * Converts a contract call or send call to a generic call.
+ */
+export function toGenericCall(call: ContractCall | SendCall): GenericCall {
+  // convert a simple send call to a user operation call
+  if (isSendCall(call)) {
+    return {
+      to: call.to,
+      value: call.value ?? 0n,
+      data: EMPTY_HEX,
+    };
+  }
+
+  // convert a contract call to a user operation call
+  // if the call has a data suffix, we need to manually concatenate it with the call data
+  // it is used to add the attribution to the call data
+  const { dataSuffix } = call;
+  const callData = encodeFunctionData(call);
+  const data = dataSuffix ? concatHex([callData, dataSuffix]) : callData;
+
+  return {
+    to: call.address,
+    value: call.value ?? 0n,
+    data,
+  };
+}
+
+/**
+ * Adapts a list of {@link GenericCall} into the call shape expected by viem's
+ * bundler client.
+ *
+ * A {@link GenericCall} is already fully encoded calldata, so this is a thin
+ * adapter rather than an encoder. It exists as an explicit seam: it owns any
+ * future divergence between our `GenericCall` shape and viem's user-operation
+ * call type, and keeps the conversion point obvious at call sites.
+ */
+export function toUserOperationCalls(
+  calls: GenericCall[],
+): UserOperationCall[] {
+  return calls.map((call) => ({
+    to: call.to,
+    data: call.data,
+    value: call.value,
+  }));
+}

package/src/utils/userOperation.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { CoinbaseGasError } from "./userOperation";
+
+// The constructor only reads `details`, `cause`, and `message`, but the param
+// is typed with the full viem bundler-error shape, so fill the rest with stubs.
+const makeBundlerError = (
+  overrides: Partial<{ details: string; cause: unknown; message: string }> = {},
+) => ({
+  stack: "stack",
+  message: overrides.message ?? "bundler error message",
+  cause: "cause" in overrides ? overrides.cause : { code: -32000 },
+  details: overrides.details ?? "",
+  docsPath: "",
+  shortMessage: "",
+  version: "viem@2.x",
+  name: "UserOperationExecutionError",
+});
+
+const precheck = (balance: string, required: string) =>
+  `precheck failed: sender balance and deposit together is ${balance} but must be at least ${required} to pay for this operation`;
+
+describe("CoinbaseGasError", () => {
+  it("formats both balance and required when present", () => {
+    // 1001597376034823 wei = 0.001001597376034823 ETH
+    // 10704882000000000 wei = 0.010704882 ETH
+    const error = new CoinbaseGasError(
+      makeBundlerError({
+        details: precheck("1001597376034823", "10704882000000000"),
+      }),
+    );
+
+    expect(error.message).toBe(
+      "Insufficient balance. You need at least 0.010704882 ETH to pay for this operation, but you only have 0.001001597376034823 ETH.",
+    );
+  });
+
+  it("falls back to required-only when balance is missing", () => {
+    const error = new CoinbaseGasError(
+      makeBundlerError({ details: precheck("", "10704882000000000") }),
+    );
+
+    expect(error.message).toBe(
+      "Insufficient balance. Make sure you have at least 0.010704882 ETH in your wallet.",
+    );
+  });
+
+  it("falls back to generic message when only balance is present", () => {
+    const error = new CoinbaseGasError(
+      makeBundlerError({ details: precheck("1001597376034823", "") }),
+    );
+
+    expect(error.message).toBe(
+      "Insufficient balance. Make sure you have enough ETH to pay for this operation.",
+    );
+  });
+
+  it("falls back to generic message when both amounts are missing", () => {
+    const error = new CoinbaseGasError(
+      makeBundlerError({ details: precheck("", "") }),
+    );
+
+    expect(error.message).toBe(
+      "Insufficient balance. Make sure you have enough ETH to pay for this operation.",
+    );
+  });
+
+  it("uses the raw details when the precheck pattern does not match", () => {
+    const details = "AA13 initCode failed or OOG";
+    const error = new CoinbaseGasError(makeBundlerError({ details }));
+
+    expect(error.message).toBe(details);
+  });
+
+  it("propagates cause and details onto the instance", () => {
+    const cause = { code: -32000 };
+    const details = precheck("1001597376034823", "10704882000000000");
+    const error = new CoinbaseGasError(makeBundlerError({ details, cause }));
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(CoinbaseGasError);
+    expect(error.cause).toBe(cause);
+    expect(error.details).toBe(details);
+  });
+});

package/src/utils/userOperation.ts

@@ -0,0 +1,124 @@
+import { formatEther, Hex } from "viem";
+import type {
+  BundlerClient,
+  SmartAccount,
+  UserOperation,
+  UserOperationReceipt,
+} from "viem/account-abstraction";
+import { UserOperationCall } from "./calls";
+
+// Coinbase Smart Wallet uses ERC-4337 entry point 0.6.
+export type PreparedUserOperation = UserOperation<"0.6">;
+
+/**
+ * Prepares a user operation from a list of contract calls.
+ * Returns a fully-populated UserOperation (gas estimated, nonce filled) with a
+ * stub signature from gas estimation. Must be re-signed before submitting.
+ */
+export const prepareUserOperation = async ({
+  bundlerClient,
+  account,
+  calls,
+}: {
+  bundlerClient: BundlerClient;
+  account: SmartAccount;
+  calls: readonly UserOperationCall[];
+}): Promise<PreparedUserOperation> => {
+  const prepared = await bundlerClient.prepareUserOperation({
+    account,
+    calls,
+  });
+  return prepared as PreparedUserOperation;
+};
+
+/**
+ * Signs and submits a prepared user operation, then waits for the receipt.
+ *
+ * The prepared op carries a stub signature from gas estimation, so we re-sign
+ * here before sending. Otherwise viem's sendUserOperation would forward the
+ * stub and the bundler would reject it as invalid.
+ */
+export const submitUserOperation = async ({
+  bundlerClient,
+  account,
+  userOperation,
+}: {
+  bundlerClient: BundlerClient;
+  account: SmartAccount;
+  userOperation: PreparedUserOperation;
+}): Promise<UserOperationReceipt> => {
+  let hash: Hex;
+  const signature = await account.signUserOperation(userOperation);
+
+  try {
+    hash = await bundlerClient.sendUserOperation({
+      account,
+      ...userOperation,
+      signature,
+    });
+  } catch (error) {
+    // handle gas errors to provide better user feedback
+    if (isGasError(error)) {
+      throw new CoinbaseGasError(error);
+    }
+    throw error;
+  }
+
+  return bundlerClient.waitForUserOperationReceipt({ hash });
+};
+
+type CoinbaseBundlerError = {
+  stack: string;
+  message: string;
+  cause: unknown;
+  details: string;
+  docsPath: string;
+  shortMessage: string;
+  version: string;
+  name: string;
+};
+
+export class CoinbaseGasError extends Error {
+  cause: unknown;
+  details: string;
+  required?: bigint;
+  available?: bigint;
+  constructor(error: CoinbaseBundlerError) {
+    let message: string;
+    let available: bigint | undefined;
+    let required: bigint | undefined;
+
+    const match = error.details.match(
+      /precheck failed: sender balance and deposit together is (\d+)? but must be at least (\d+)? to pay for this operation/,
+    );
+
+    if (match) {
+      available = match[1] ? BigInt(match[1]) : undefined;
+      required = match[2] ? BigInt(match[2]) : undefined;
+
+      if (available !== undefined && required !== undefined) {
+        message = `Insufficient balance. You need at least ${formatEther(required)} ETH to pay for this operation, but you only have ${formatEther(available)} ETH.`;
+      } else if (required !== undefined) {
+        message = `Insufficient balance. Make sure you have at least ${formatEther(required)} ETH in your wallet.`;
+      } else {
+        message = `Insufficient balance. Make sure you have enough ETH to pay for this operation.`;
+      }
+    } else {
+      message = error.details ?? error.message;
+    }
+
+    super(message);
+    this.cause = error.cause;
+    this.details = error.details;
+    this.available = available;
+    this.required = required;
+  }
+}
+
+function isGasError(error: unknown): error is CoinbaseBundlerError {
+  return (
+    (error as CoinbaseBundlerError).details?.startsWith(
+      "precheck failed: sender balance and deposit together is",
+    ) ?? false
+  );
+}