@zoralabs/coins-sdk 0.6.0 → 0.7.1

package/src/actions/tradeCoin.ts

@@ -2,14 +2,22 @@ import { permit2ABI, permit2Address } from "@zoralabs/protocol-deployments";
 import {
   Account,
   Address,
+  encodeFunctionData,
   erc20Abi,
-  WalletClient,
-  maxUint256,
   Hex,
+  maxUint256,
+  TransactionReceipt,
+  WalletClient,
 } from "viem";
+import { BundlerClient, SmartAccount } from "viem/account-abstraction";
 import { base } from "viem/chains";
 import { postQuote, PostQuoteResponse } from "../client";
+import { GenericCall, toUserOperationCalls } from "../utils/calls";
 import { GenericPublicClient } from "../utils/genericPublicClient";
+import {
+  prepareUserOperation,
+  submitUserOperation,
+} from "../utils/userOperation";
 
 type TradeERC20 = {
   type: "erc20";
@@ -92,6 +100,110 @@ export type TradeParameters = {
   permitActiveSeconds?: number;
 };
 
+type SignPermitTypedData = (params: {
+  domain: { name: string; chainId: number; verifyingContract: Address };
+  types: typeof PERMIT_SINGLE_TYPES;
+  primaryType: "PermitSingle";
+  message: Permit;
+}) => Promise<Hex>;
+
+/**
+ * Resolves the permit2 requirements for a trade quote.
+ *
+ * For each permit the quote requires, reads the on-chain permit2 nonce and the
+ * token's permit2 allowance, signs the permit2 `PermitSingle` typed data with the
+ * provided signer, and — when the token's permit2 allowance is insufficient —
+ * collects the ERC20 `approve(permit2, max)` call needed before the trade.
+ *
+ * The approval is returned as a {@link GenericCall} rather than executed, so the
+ * caller decides how to run it: `tradeCoin` (EOA) sends it as a prior
+ * transaction; `tradeCoinSmartWallet` batches it into the trade's user operation.
+ */
+async function resolveTradePermits({
+  quote,
+  owner,
+  publicClient,
+  signTypedData,
+}: {
+  quote: PostQuoteResponse;
+  owner: Address;
+  publicClient: GenericPublicClient;
+  signTypedData: SignPermitTypedData;
+}): Promise<{
+  signatures: SignatureWithPermit<PermitStringAmounts>[];
+  approvalCalls: GenericCall[];
+}> {
+  const signatures: SignatureWithPermit<PermitStringAmounts>[] = [];
+  const approvalCalls: GenericCall[] = [];
+
+  if (!quote.permits) {
+    return { signatures, approvalCalls };
+  }
+
+  for (const permit of quote.permits) {
+    // permit2 allowance returns [amount, expiration, nonce]
+    const [, , nonce] = await publicClient.readContract({
+      abi: permit2ABI,
+      address: permit2Address[base.id],
+      functionName: "allowance",
+      args: [
+        owner,
+        permit.permit.details.token as Address,
+        permit.permit.spender as Address,
+      ],
+    });
+
+    const permitToken = permit.permit.details.token as Address;
+    const allowance = await publicClient.readContract({
+      abi: erc20Abi,
+      address: permitToken,
+      functionName: "allowance",
+      args: [owner, permit2Address[base.id]],
+    });
+
+    if (allowance < BigInt(permit.permit.details.amount)) {
+      approvalCalls.push({
+        to: permitToken,
+        data: encodeFunctionData({
+          abi: erc20Abi,
+          functionName: "approve",
+          args: [permit2Address[base.id], maxUint256],
+        }),
+        value: 0n,
+      });
+    }
+
+    const message: Permit = {
+      details: {
+        token: permit.permit.details.token as Address,
+        amount: BigInt(permit.permit.details.amount!),
+        expiration: Number(permit.permit.details.expiration!),
+        nonce,
+      },
+      spender: permit.permit.spender as Address,
+      sigDeadline: BigInt(permit.permit.sigDeadline!),
+    };
+
+    const signature = await signTypedData({
+      domain: {
+        name: "Permit2",
+        chainId: base.id,
+        verifyingContract: permit2Address[base.id],
+      },
+      primaryType: "PermitSingle",
+      types: PERMIT_SINGLE_TYPES,
+      message,
+    });
+
+    signatures.push({
+      signature,
+      permit: convertBigIntToString(message),
+    });
+  }
+
+  return { signatures, approvalCalls };
+}
+
 export async function tradeCoin({
   tradeParameters,
   walletClient,
@@ -104,7 +216,7 @@ export async function tradeCoin({
   account?: Account | Address;
   publicClient: GenericPublicClient;
   validateTransaction?: boolean;
-}) {
+}): Promise<TransactionReceipt> {
   const quote = await createTradeCall(tradeParameters);
 
   if (!account) {
@@ -113,77 +225,33 @@ export async function tradeCoin({
   if (!account) {
     throw new Error("Account is required");
   }
+  const resolvedAccount = account;
+  const owner =
+    typeof resolvedAccount === "string"
+      ? resolvedAccount
+      : resolvedAccount.address;
 
   // Set default recipient to wallet sender address if not provided
   if (!tradeParameters.recipient) {
-    tradeParameters.recipient =
-      typeof account === "string" ? account : account.address;
+    tradeParameters.recipient = owner;
   }
 
-  // todo replace any
-  const signatures: { signature: Hex; permit: any }[] = [];
-  if (quote.permits) {
-    for (const permit of quote.permits) {
-      // return values: amount, expiration, nonce
-      const [, , nonce] = await publicClient.readContract({
-        abi: permit2ABI,
-        address: permit2Address[base.id],
-        functionName: "allowance",
-        args: [
-          typeof account === "string" ? account : account.address,
-          permit.permit.details.token as Address,
-          permit.permit.spender as Address,
-        ],
-      });
-      const permitToken = permit.permit.details.token as Address;
-      const allowance = await publicClient.readContract({
-        abi: erc20Abi,
-        address: permitToken,
-        functionName: "allowance",
-        args: [
-          typeof account === "string" ? account : account.address,
-          permit2Address[base.id],
-        ],
-      });
-      if (allowance < BigInt(permit.permit.details.amount)) {
-        const approvalTx = await walletClient.writeContract({
-          abi: erc20Abi,
-          address: permitToken,
-          functionName: "approve",
-          chain: base,
-          args: [permit2Address[base.id], maxUint256],
-          account,
-        });
-        await publicClient.waitForTransactionReceipt({
-          hash: approvalTx,
-        });
-      }
-      const message = {
-        details: {
-          token: permit.permit.details.token as Address,
-          amount: BigInt(permit.permit.details.amount!),
-          expiration: Number(permit.permit.details.expiration!),
-          nonce: nonce,
-        },
-        spender: permit.permit.spender as Address,
-        sigDeadline: BigInt(permit.permit.sigDeadline!),
-      };
-      const signature = await walletClient.signTypedData({
-        domain: {
-          name: "Permit2",
-          chainId: base.id,
-          verifyingContract: permit2Address[base.id],
-        },
-        primaryType: "PermitSingle",
-        types: PERMIT_SINGLE_TYPES,
-        message,
-        account,
-      });
-      signatures.push({
-        signature,
-        permit: convertBigIntToString(message),
-      });
-    }
+  const { signatures, approvalCalls } = await resolveTradePermits({
+    quote,
+    owner,
+    publicClient,
+    signTypedData: (typedData) =>
+      walletClient.signTypedData({ ...typedData, account: resolvedAccount }),
+  });
+
+  // EOA path: execute each required permit2 approval as its own transaction
+  for (const approvalCall of approvalCalls) {
+    const approvalTx = await walletClient.sendTransaction({
+      ...approvalCall,
+      account: resolvedAccount,
+      chain: base,
+    });
+    await publicClient.waitForTransactionReceipt({ hash: approvalTx });
   }
 
   const newQuote = await createTradeCall({
@@ -196,7 +264,7 @@ export async function tradeCoin({
     data: newQuote.call.data as Hex,
     value: BigInt(newQuote.call.value),
     chain: base,
-    account,
+    account: resolvedAccount,
   };
 
   // simulate call
@@ -222,15 +290,112 @@ export async function tradeCoin({
   return receipt;
 }
 
-export async function createTradeCall(
+/**
+ * Executes a trade from the caller's smart wallet via a user operation.
+ *
+ * Mirrors {@link tradeCoin} but routes through a bundler client: the smart
+ * account is both the token holder and the permit2 signer (ERC-1271), and any
+ * required permit2 approval is batched into the same user operation as the trade
+ * (rather than sent as a prior transaction). Returns the settled transaction
+ * receipt.
+ */
+export async function tradeCoinSmartWallet({
+  tradeParameters,
+  bundlerClient,
+  account,
+  publicClient,
+}: {
+  tradeParameters: TradeParameters;
+  bundlerClient: BundlerClient;
+  account?: SmartAccount;
+  publicClient: GenericPublicClient;
+}) {
+  const resolvedAccount = account ?? bundlerClient.account;
+  if (!resolvedAccount) {
+    throw new Error("Account is required");
+  }
+
+  const owner = resolvedAccount.address;
+
+  // The smart wallet is both the sender (token holder) and the permit signer.
+  const params: TradeParameters = {
+    ...tradeParameters,
+    sender: owner,
+    recipient: tradeParameters.recipient ?? owner,
+  };
+
+  const quote = await createTradeCall(params);
+
+  const { signatures, approvalCalls } = await resolveTradePermits({
+    quote,
+    owner,
+    publicClient,
+    signTypedData: (typedData) => resolvedAccount.signTypedData(typedData),
+  });
+
+  const newQuote = await createTradeCall({
+    ...params,
+    signatures,
+  });
+
+  const tradeCall: GenericCall = {
+    to: newQuote.call.target as Address,
+    data: newQuote.call.data as Hex,
+    value: BigInt(newQuote.call.value),
+  };
+
+  // Batch any required permit2 approvals + the trade into one user operation
+  const calls = toUserOperationCalls([...approvalCalls, tradeCall]);
+
+  const userOp = await prepareUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    calls,
+  });
+
+  const userOpReceipt = await submitUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    userOperation: userOp,
+  });
+
+  if (!userOpReceipt.success) {
+    throw new Error(
+      `User operation reverted${userOpReceipt.reason ? `: ${userOpReceipt.reason}` : ""}`,
+    );
+  }
+
+  return userOpReceipt.receipt;
+}
+
+/**
+ * Validates the parameters for a trade.
+ *
+ * Asserts slippage is within bounds and a non-zero input amount is provided.
+ * Shared by the quote builder (`createTradeCall`) and the user-operation path so
+ * both validate identically before any network request is made.
+ */
+export function validateTradeParameters(
   tradeParameters: TradeParameters,
-): Promise<PostQuoteResponse> {
+): void {
   if (tradeParameters.slippage && tradeParameters.slippage > 1) {
     throw new Error("Slippage must be less than 1, max 0.99");
   }
   if (tradeParameters.amountIn === BigInt(0)) {
     throw new Error("Amount in must be greater than 0");
   }
+}
+
+export async function createTradeCall(
+  tradeParameters: TradeParameters,
+): Promise<PostQuoteResponse> {
+  return createQuote(tradeParameters);
+}
+
+export async function createQuote(
+  tradeParameters: TradeParameters,
+): Promise<PostQuoteResponse> {
+  validateTradeParameters(tradeParameters);
 
   const quote = await postQuote({
     body: {

package/src/actions/updateCoinURI.ts

@@ -1,5 +1,4 @@
 import { coinABI } from "@zoralabs/protocol-deployments";
-import { validateClientNetwork } from "../utils/validateClientNetwork";
 import {
   Account,
   Address,
@@ -7,21 +6,39 @@ import {
   SimulateContractParameters,
   WalletClient,
 } from "viem";
-import { GenericPublicClient } from "../utils/genericPublicClient";
+import { BundlerClient, SmartAccount } from "viem/account-abstraction";
 import { getAttribution } from "../utils/attribution";
+import { toGenericCall, toUserOperationCalls } from "../utils/calls";
+import { GenericPublicClient } from "../utils/genericPublicClient";
+import {
+  prepareUserOperation,
+  submitUserOperation,
+} from "../utils/userOperation";
+import { validateClientNetwork } from "../utils/validateClientNetwork";
 
 export type UpdateCoinURIArgs = {
   coin: Address;
   newURI: string;
 };
 
-export function updateCoinURICall({
-  newURI,
-  coin,
-}: UpdateCoinURIArgs): SimulateContractParameters {
+/**
+ * Validates the arguments for updating a coin's URI.
+ *
+ * Asserts the new URI is an `ipfs://` URI. Shared by the contract-call builder
+ * (`updateCoinURICall`) and the user-operation path so both validate identically.
+ */
+export function validateUpdateCoinURI({ newURI }: UpdateCoinURIArgs): void {
   if (!newURI.startsWith("ipfs://")) {
     throw new Error("URI needs to be an ipfs:// prefix uri");
   }
+}
+
+export function updateCoinURICall(
+  args: UpdateCoinURIArgs,
+): SimulateContractParameters {
+  validateUpdateCoinURI(args);
+
+  const { coin, newURI } = args;
 
   return {
     abi: coinABI,
@@ -39,13 +56,18 @@ export async function updateCoinURI(
   account?: Account | Address,
 ) {
   validateClientNetwork(publicClient);
+
   const call = updateCoinURICall(args);
+
   const { request } = await publicClient.simulateContract({
     ...call,
     account: account ?? walletClient.account,
   });
+
   const hash = await walletClient.writeContract(request);
+
   const receipt = await publicClient.waitForTransactionReceipt({ hash });
+
   const eventLogs = parseEventLogs({ abi: coinABI, logs: receipt.logs });
   const uriUpdated = eventLogs.find(
     (log) => log.eventName === "ContractURIUpdated",
@@ -53,3 +75,59 @@ export async function updateCoinURI(
 
   return { hash, receipt, uriUpdated };
 }
+
+/**
+ * Updates a coin's URI from the caller's smart wallet via a user operation.
+ *
+ * Builds the `setContractURI` call, submits it through the bundler client (which
+ * wraps it in the smart wallet's `execute`), and parses the result. Mirrors
+ * {@link updateCoinURI}'s return shape (`hash` is the settled transaction hash,
+ * `receipt` the underlying transaction receipt).
+ */
+export async function updateCoinURISmartWallet(
+  args: UpdateCoinURIArgs,
+  bundlerClient: BundlerClient,
+  publicClient: GenericPublicClient,
+  account?: SmartAccount,
+) {
+  const resolvedAccount = account ?? bundlerClient.account;
+  if (!resolvedAccount) {
+    throw new Error("Account is required");
+  }
+
+  validateClientNetwork(publicClient);
+
+  // updateCoinURICall validates the args and assembles the contract call
+  const call = updateCoinURICall(args);
+
+  const calls = toUserOperationCalls([toGenericCall(call)]);
+
+  const userOp = await prepareUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    calls,
+  });
+
+  const userOpReceipt = await submitUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    userOperation: userOp,
+  });
+
+  if (!userOpReceipt.success) {
+    throw new Error(
+      `User operation reverted${userOpReceipt.reason ? `: ${userOpReceipt.reason}` : ""}`,
+    );
+  }
+
+  const eventLogs = parseEventLogs({ abi: coinABI, logs: userOpReceipt.logs });
+  const uriUpdated = eventLogs.find(
+    (log) => log.eventName === "ContractURIUpdated",
+  );
+
+  return {
+    hash: userOpReceipt.receipt.transactionHash,
+    receipt: userOpReceipt.receipt,
+    uriUpdated,
+  };
+}

package/src/actions/updatePayoutRecipient.ts

@@ -1,24 +1,49 @@
 import { coinABI } from "@zoralabs/protocol-deployments";
-import { validateClientNetwork } from "../utils/validateClientNetwork";
 import {
   Account,
   Address,
+  isAddress,
   parseEventLogs,
   SimulateContractParameters,
   WalletClient,
 } from "viem";
-import { GenericPublicClient } from "../utils/genericPublicClient";
+import { BundlerClient, SmartAccount } from "viem/account-abstraction";
 import { getAttribution } from "../utils/attribution";
+import { toGenericCall, toUserOperationCalls } from "../utils/calls";
+import { GenericPublicClient } from "../utils/genericPublicClient";
+import {
+  prepareUserOperation,
+  submitUserOperation,
+} from "../utils/userOperation";
+import { validateClientNetwork } from "../utils/validateClientNetwork";
 
 export type UpdatePayoutRecipientArgs = {
   coin: Address;
   newPayoutRecipient: string;
 };
 
-export function updatePayoutRecipientCall({
+/**
+ * Validates the arguments for updating a coin's payout recipient.
+ *
+ * Asserts the new payout recipient is a valid address. Shared by the
+ * contract-call builder (`updatePayoutRecipientCall`) and the user-operation path
+ * so both validate identically.
+ */
+export function validateUpdatePayoutRecipient({
   newPayoutRecipient,
-  coin,
-}: UpdatePayoutRecipientArgs): SimulateContractParameters {
+}: UpdatePayoutRecipientArgs): void {
+  if (!isAddress(newPayoutRecipient)) {
+    throw new Error("Payout recipient must be a valid address");
+  }
+}
+
+export function updatePayoutRecipientCall(
+  args: UpdatePayoutRecipientArgs,
+): SimulateContractParameters {
+  validateUpdatePayoutRecipient(args);
+
+  const { coin, newPayoutRecipient } = args;
+
   return {
     abi: coinABI,
     address: coin,
@@ -35,13 +60,18 @@ export async function updatePayoutRecipient(
   account?: Account | Address,
 ) {
   validateClientNetwork(publicClient);
+
   const call = updatePayoutRecipientCall(args);
+
   const { request } = await publicClient.simulateContract({
     ...call,
     account: account ?? walletClient.account!,
   });
+
   const hash = await walletClient.writeContract(request);
+
   const receipt = await publicClient.waitForTransactionReceipt({ hash });
+
   const eventLogs = parseEventLogs({ abi: coinABI, logs: receipt.logs });
   const payoutRecipientUpdated = eventLogs.find(
     (log) => log.eventName === "CoinPayoutRecipientUpdated",
@@ -49,3 +79,60 @@ export async function updatePayoutRecipient(
 
   return { hash, receipt, payoutRecipientUpdated };
 }
+
+/**
+ * Updates a coin's payout recipient from the caller's smart wallet via a user
+ * operation.
+ *
+ * Builds the `setPayoutRecipient` call, submits it through the bundler client
+ * (which wraps it in the smart wallet's `execute`), and parses the result.
+ * Mirrors {@link updatePayoutRecipient}'s return shape (`hash` is the settled
+ * transaction hash, `receipt` the underlying transaction receipt).
+ */
+export async function updatePayoutRecipientSmartWallet(
+  args: UpdatePayoutRecipientArgs,
+  bundlerClient: BundlerClient,
+  publicClient: GenericPublicClient,
+  account?: SmartAccount,
+) {
+  const resolvedAccount = account ?? bundlerClient.account;
+  if (!resolvedAccount) {
+    throw new Error("Account is required");
+  }
+
+  validateClientNetwork(publicClient);
+
+  // updatePayoutRecipientCall validates the args and assembles the contract call
+  const call = updatePayoutRecipientCall(args);
+
+  const calls = toUserOperationCalls([toGenericCall(call)]);
+
+  const userOp = await prepareUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    calls,
+  });
+
+  const userOpReceipt = await submitUserOperation({
+    bundlerClient,
+    account: resolvedAccount,
+    userOperation: userOp,
+  });
+
+  if (!userOpReceipt.success) {
+    throw new Error(
+      `User operation reverted${userOpReceipt.reason ? `: ${userOpReceipt.reason}` : ""}`,
+    );
+  }
+
+  const eventLogs = parseEventLogs({ abi: coinABI, logs: userOpReceipt.logs });
+  const payoutRecipientUpdated = eventLogs.find(
+    (log) => log.eventName === "CoinPayoutRecipientUpdated",
+  );
+
+  return {
+    hash: userOpReceipt.receipt.transactionHash,
+    receipt: userOpReceipt.receipt,
+    payoutRecipientUpdated,
+  };
+}

package/src/api/api-raw.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { client } from "../client/client.gen";
+import { apiUrl } from "./api-raw";
+
+const mockBaseUrl = (baseUrl: string | undefined) =>
+  vi
+    .spyOn(client, "getConfig")
+    .mockReturnValue({ baseUrl } as ReturnType<typeof client.getConfig>);
+
+describe("apiUrl", () => {
+  const expected = "https://api.example.com/some/path";
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("joins base without trailing slash and path with leading slash", () => {
+    mockBaseUrl("https://api.example.com");
+    expect(apiUrl("/some/path")).toBe(expected);
+  });
+
+  it("joins base without trailing slash and path without leading slash", () => {
+    mockBaseUrl("https://api.example.com");
+    expect(apiUrl("some/path")).toBe(expected);
+  });
+
+  it("joins base with trailing slash and path with leading slash", () => {
+    mockBaseUrl("https://api.example.com/");
+    expect(apiUrl("/some/path")).toBe(expected);
+  });
+
+  it("joins base with trailing slash and path without leading slash", () => {
+    mockBaseUrl("https://api.example.com/");
+    expect(apiUrl("some/path")).toBe(expected);
+  });
+
+  it("collapses multiple trailing slashes on the base", () => {
+    mockBaseUrl("https://api.example.com///");
+    expect(apiUrl("some/path")).toBe(expected);
+  });
+
+  it("collapses multiple leading slashes on the path", () => {
+    mockBaseUrl("https://api.example.com");
+    expect(apiUrl("///some/path")).toBe(expected);
+  });
+
+  it("preserves the protocol's double slashes", () => {
+    mockBaseUrl("https://api.example.com/");
+    expect(apiUrl("/some/path")).toContain("https://");
+  });
+
+  it("handles an undefined base url", () => {
+    mockBaseUrl(undefined);
+    expect(apiUrl("/some/path")).toBe("/some/path");
+  });
+
+  it("handles an empty path", () => {
+    mockBaseUrl("https://api.example.com");
+    expect(apiUrl("")).toBe("https://api.example.com/");
+  });
+});