alchemy 0.69.1 → 0.70.0

package/src/cloudflare/worker.ts

@@ -179,6 +179,17 @@ export interface BaseWorkerProps<
     enabled?: boolean;
   };
 
+  /**
+   * Enable Workers Logpush to export trace events (request/response metadata,
+   * console logs, and exceptions) to external destinations.
+   *
+   * Requires a separate Logpush job configuration via the Cloudflare API.
+   *
+   * @see https://developers.cloudflare.com/workers/observability/logging/logpush
+   * @default false
+   */
+  logpush?: boolean;
+
   /**
    * Whether to adopt the Worker if it already exists when creating
    */
@@ -324,7 +335,7 @@ export interface BaseWorkerProps<
   dev?:
     | {
         /**
-         * Port to use for local development
+         * Port to use for local development.
          */
         port?: number;
         /**

package/src/cloudflare/wrangler.json.ts

@@ -4,6 +4,7 @@ import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { Scope } from "../scope.ts";
 import { isSecret } from "../secret.ts";
+import { unencryptSecrets } from "./util/filter-env-bindings.ts";
 import { assertNever } from "../util/assert-never.ts";
 import type { Bindings, WorkerBindingRateLimit } from "./bindings.ts";
 import type { R2BucketJurisdiction } from "./bucket.ts";
@@ -162,6 +163,7 @@ export async function WranglerJson(
       : undefined,
     placement: worker.placement,
     limits: worker.limits,
+    logpush: worker.logpush,
   };
 
   // Process bindings if they exist
@@ -210,14 +212,7 @@ export async function WranglerJson(
     // but do not modify `finalSpec` so that way secrets aren't written to state unencrypted.
     const withSecretsUnwrapped = {
       ...finalSpec,
-      vars: {
-        ...finalSpec.vars,
-        ...Object.fromEntries(
-          Object.entries(finalSpec.vars ?? {}).map(([key, value]) =>
-            isSecret(value) ? [key, value.unencrypted] : [key, value],
-          ),
-        ),
-      },
+      vars: unencryptSecrets(finalSpec.vars ?? {}),
     };
     await writeJSON(filePath, withSecretsUnwrapped);
   } else {
@@ -275,6 +270,15 @@ export interface WranglerJsonSpec {
     cpu_ms?: number;
   };
 
+  /**
+   * Send Trace Events from this Worker to Workers Logpush.
+   *
+   * This will not configure a corresponding Logpush job automatically.
+   *
+   * @default false
+   */
+  logpush?: boolean;
+
   /**
    * Whether to enable a workers.dev URL for this worker
    */

package/src/coinbase/client.ts

@@ -0,0 +1,146 @@
+import type { CdpClient } from "@coinbase/cdp-sdk";
+import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
+import { importPeer } from "../util/peer.ts";
+
+export interface CoinbaseClientOptions {
+  /**
+   * CDP API Key ID. If not provided, falls back to CDP_API_KEY_ID environment variable.
+   */
+  apiKeyId?: Secret<string> | string;
+  /**
+   * CDP API Key Secret. If not provided, falls back to CDP_API_KEY_SECRET environment variable.
+   * Must be wrapped in alchemy.secret() for security.
+   */
+  apiKeySecret?: Secret<string>;
+  /**
+   * CDP Wallet Secret. If not provided, falls back to CDP_WALLET_SECRET environment variable.
+   * Must be wrapped in alchemy.secret() for security.
+   */
+  walletSecret?: Secret<string>;
+}
+
+/**
+ * Create an authenticated CDP client
+ *
+ * The CDP SDK automatically looks for these environment variables:
+ * - CDP_API_KEY_ID
+ * - CDP_API_KEY_SECRET
+ * - CDP_WALLET_SECRET
+ *
+ * You can override them by passing values in the options.
+ *
+ * @param options Options for creating the client
+ * @returns An authenticated CDP client
+ */
+export async function createCdpClient(
+  options: CoinbaseClientOptions = {},
+): Promise<CdpClient> {
+  const { CdpClient } = await importPeer(
+    import("@coinbase/cdp-sdk"),
+    "Coinbase resources",
+  );
+
+  // Build options object for CdpClient constructor
+  const clientOptions: {
+    apiKeyId?: string;
+    apiKeySecret?: string;
+    walletSecret?: string;
+  } = {};
+
+  // Only set values if explicitly provided, otherwise let CDP SDK use its defaults
+  if (options.apiKeyId) {
+    clientOptions.apiKeyId =
+      typeof options.apiKeyId === "string"
+        ? options.apiKeyId
+        : options.apiKeyId.unencrypted;
+  }
+
+  if (options.apiKeySecret) {
+    clientOptions.apiKeySecret = options.apiKeySecret.unencrypted;
+  }
+
+  if (options.walletSecret) {
+    clientOptions.walletSecret = options.walletSecret.unencrypted;
+  }
+
+  // CDP SDK will automatically use environment variables if not provided:
+  // CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET
+  return new CdpClient(clientOptions);
+}
+
+/**
+ * Handle CDP SDK deletion errors gracefully
+ *
+ * @param error The error from CDP SDK
+ * @param resourceType The type of resource being deleted
+ * @param resourceId The ID or name of the resource
+ */
+export function handleCdpDeleteError(
+  _error: any,
+  resourceType: string,
+  resourceId?: string,
+): void {
+  // CDP SDK doesn't support deleting accounts, so we just log
+  logger.log(
+    `${resourceType} ${resourceId || "unknown"} cannot be deleted from CDP (CDP limitation)`,
+  );
+}
+
+/**
+ * Check if an error indicates the resource already exists
+ *
+ * @param error The error from CDP SDK
+ * @returns True if the error indicates a conflict/already exists
+ */
+export function isCdpConflictError(error: any): boolean {
+  return (
+    error?.message?.toLowerCase()?.includes("already exists") ||
+    error?.message?.toLowerCase()?.includes("duplicate") ||
+    error?.code === "ALREADY_EXISTS" ||
+    error?.code === "CONFLICT"
+  );
+}
+
+/**
+ * Verifies CDP authentication and provides helpful error messages
+ *
+ * @param client CDP client
+ */
+export async function verifyCdpAuth(client: CdpClient): Promise<void> {
+  try {
+    // Make a test request to check authentication
+    // List accounts is a good test as it requires valid credentials
+    await client.evm.listAccounts();
+  } catch (error: any) {
+    if (error.errorType === "unauthorized") {
+      logger.error(
+        "\n⚠️ Coinbase CDP authentication failed. Please check your credentials:",
+      );
+      logger.error("1. Ensure CDP_API_KEY_ID is set with your API Key ID");
+      logger.error(
+        "2. Ensure CDP_API_KEY_SECRET is set with your API Key Secret",
+      );
+      logger.error(
+        "3. Ensure CDP_WALLET_SECRET is set with your Wallet Secret",
+      );
+      logger.error(
+        "\nTo create API credentials, visit: https://portal.cdp.coinbase.com/",
+      );
+      logger.error(
+        "Required permissions: Account management and transaction signing\n",
+      );
+      throw new Error("CDP authentication failed");
+    }
+    if (error.errorType === "unauthorized") {
+      logger.error(
+        "\n⚠️ Insufficient permissions. Your API key needs account management permissions.",
+      );
+      logger.error(
+        "Make sure your API key has the required scopes for creating and managing accounts\n",
+      );
+      throw new Error("Insufficient CDP permissions");
+    }
+    throw error;
+  }
+}

package/src/coinbase/evm-account.ts

@@ -0,0 +1,317 @@
+import type { Context } from "../context.ts";
+import type { Secret } from "../index.ts";
+import { Resource } from "../resource.ts";
+import { createCdpClient, type CoinbaseClientOptions } from "./client.ts";
+import type {
+  Address,
+  FaucetConfig,
+  FaucetNetwork,
+  FaucetToken,
+  PrivateKey,
+} from "./types.ts";
+import { validateAccountName } from "./utils.ts";
+
+// Re-export types for backward compatibility
+export type { FaucetConfig, FaucetNetwork, FaucetToken } from "./types.ts";
+
+export interface EvmAccountProps extends CoinbaseClientOptions {
+  /**
+   * Name for the account.
+   * Used for identification in CDP.
+   * Must contain only letters, numbers, and hyphens.
+   */
+  name: string;
+  /**
+   * Optional private key to import an existing account.
+   * Must be a hex string (starting with 0x) encrypted using alchemy.secret().
+   * If not provided, a new account will be created or existing one will be used.
+   *
+   * @example
+   * ```ts
+   * privateKey: alchemy.secret(process.env.PRIVATE_KEY)
+   * ```
+   */
+  privateKey?: Secret<PrivateKey>;
+  /**
+   * Whether to adopt an existing account with the same name if it already exists.
+   * Without adoption, creation will fail if an account with the same name exists.
+   * With adoption, the existing account will be used.
+   * @default false
+   */
+  adopt?: boolean;
+  /**
+   * Faucet configuration for development funding.
+   * Declares which tokens this account should have.
+   * Used by external funding scripts - not processed by the resource.
+   *
+   * @example
+   * ```ts
+   * faucet: {
+   *   "base-sepolia": ["eth", "usdc"],
+   *   "ethereum-sepolia": ["eth"]
+   * }
+   * ```
+   */
+  faucet?: FaucetConfig;
+}
+
+export interface EvmAccount extends Resource<"coinbase::evm-account"> {
+  /**
+   * The account name in CDP
+   */
+  name: string;
+  /**
+   * The EVM address (same across all EVM networks)
+   */
+  address: Address;
+  /**
+   * Faucet configuration (passed through from props)
+   */
+  faucet?: FaucetConfig;
+}
+
+/**
+ * Manages EVM EOA (Externally Owned Accounts) on Coinbase Developer Platform.
+ *
+ * @example
+ * ## Create a new EVM account
+ *
+ * ```ts
+ * const account = await EvmAccount("my-account", {
+ *   name: "my-account"
+ * });
+ *
+ * console.log("Account address:", account.address);
+ * ```
+ *
+ * @example
+ * ## Create account with funding metadata
+ *
+ * Declare what tokens this account needs for development
+ *
+ * ```ts
+ * const account = await EvmAccount("test-account", {
+ *   name: "test-account",
+ *   faucet: {
+ *     "base-sepolia": ["eth", "usdc"],
+ *     "ethereum-sepolia": ["eth"]
+ *   }
+ * });
+ *
+ * // Account automatically requests tokens on creation
+ * // The faucet script can be used for bulk funding operations
+ * ```
+ *
+ * @example
+ * ## Import an existing account
+ *
+ * Import an existing EVM account using a private key
+ *
+ * ```ts
+ * const account = await EvmAccount("imported-account", {
+ *   name: "imported-account",
+ *   privateKey: alchemy.secret(process.env.COINBASE_PRIVATE_KEY)
+ * });
+ * ```
+ *
+ * @example
+ * ## Adopt an existing account
+ *
+ * Use an existing account with the same name if it exists
+ *
+ * ```ts
+ * const account = await EvmAccount("my-account", {
+ *   name: "existing-account",
+ *   adopt: true // Uses existing account if it exists
+ * });
+ * ```
+ */
+export const EvmAccount = Resource(
+  "coinbase::evm-account",
+  async function (
+    this: Context<EvmAccount>,
+    _id: string,
+    props: EvmAccountProps,
+  ): Promise<EvmAccount> {
+    // Validate account name format
+    validateAccountName(props.name);
+
+    // Initialize CDP client with credentials from props or environment
+    const cdp = await createCdpClient({
+      apiKeyId: props.apiKeyId,
+      apiKeySecret: props.apiKeySecret,
+      walletSecret: props.walletSecret,
+    });
+
+    // Handle update phase
+    if (this.phase === "update" && this.output) {
+      // Only name can be updated
+      if (props.name !== this.output.name) {
+        // CDP SDK supports updating account names via updateAccount
+        await cdp.evm.updateAccount({
+          address: this.output.address,
+          update: {
+            name: props.name,
+          },
+        });
+        return {
+          ...this.output,
+          name: props.name, // Use the requested name
+          faucet: props.faucet,
+        };
+      }
+
+      // Update faucet configuration if changed
+      if (JSON.stringify(props.faucet) !== JSON.stringify(this.output.faucet)) {
+        // Only fund NEW combinations that weren't in the previous config
+        try {
+          // Get all old combinations
+          const oldCombinations = new Set(
+            Object.entries(this.output.faucet ?? {}).flatMap(
+              ([network, tokens]) =>
+                tokens.map((token) => `${network}:${token}`),
+            ),
+          );
+
+          // Get all new combinations
+          const newCombinations = Object.entries(props.faucet ?? {}).flatMap(
+            ([network, tokens]) =>
+              tokens.map((token) => ({
+                network: network as FaucetNetwork,
+                token: token as FaucetToken,
+                key: `${network}:${token}`,
+              })),
+          );
+
+          // Filter to only combinations that are actually new
+          const toFund = newCombinations.filter(
+            ({ key }) => !oldCombinations.has(key),
+          );
+
+          if (toFund.length > 0) {
+            await Promise.all(
+              toFund.map(({ network, token }) =>
+                cdp.evm
+                  .requestFaucet({
+                    address: this.output.address,
+                    network,
+                    token,
+                  })
+                  .catch((err) => {
+                    console.warn(
+                      `⚠️ Failed to request ${token} on ${network} for ${this.output.address}: ${err.message}`,
+                    );
+                    return null;
+                  }),
+              ),
+            );
+
+            console.log(
+              `💧 Requested ${toFund.length} new faucet fund${toFund.length === 1 ? "" : "s"} for ${this.output.address}`,
+            );
+          }
+        } catch (error: any) {
+          console.warn(
+            `⚠️ Failed to request additional faucet funds for ${this.output.address}: ${error.message}`,
+          );
+          // Continue - don't break the update
+        }
+
+        return {
+          ...this.output,
+          faucet: props.faucet,
+        };
+      }
+
+      return this.output;
+    }
+
+    // Handle delete phase
+    if (this.phase === "delete") {
+      // CDP SDK doesn't support deleting accounts
+      // Accounts remain in CDP but are no longer tracked by Alchemy
+      console.log(`🗑️ Untracking EVM Account: ${this.output.address}`);
+      return this.destroy();
+    }
+
+    let account;
+
+    // Handle account creation/retrieval
+    if (props.privateKey) {
+      // Import account with private key
+      // This is idempotent in CDP
+      account = await cdp.evm.importAccount({
+        privateKey: props.privateKey.unencrypted,
+        name: props.name,
+      });
+    } else {
+      // Check for adoption or use getOrCreate pattern
+      const adopt = props.adopt ?? this.scope.adopt;
+      if (adopt) {
+        // With adoption, use getOrCreate which returns existing if it exists
+        account = await cdp.evm.getOrCreateAccount({
+          name: props.name,
+        });
+      } else {
+        // Without adoption, we can attempt to create it.
+        // It will throw if already exist
+        try {
+          account = await cdp.evm.createAccount({ name: props.name });
+        } catch (error: any) {
+          // Provide helpful error message if account already exists
+          if (error.errorType === "already_exists") {
+            throw new Error(
+              `Account with name '${props.name}' already exists. Use adopt: true to use the existing account.`,
+            );
+          }
+          // Rethrow other errors unchanged
+          throw error;
+        }
+      }
+    }
+
+    // Fund the account if faucet configuration is provided
+    if (props.faucet) {
+      try {
+        const combinations = Object.entries(props.faucet).flatMap(
+          ([network, tokens]) =>
+            tokens.map((token) => ({
+              network: network as FaucetNetwork,
+              token: token as FaucetToken,
+            })),
+        );
+
+        await Promise.all(
+          combinations.map(({ network, token }) =>
+            cdp.evm
+              .requestFaucet({
+                address: account.address,
+                network,
+                token,
+              })
+              .catch((err) => {
+                console.warn(
+                  `⚠️ Failed to request ${token} on ${network} for ${account.address}: ${err.message}`,
+                );
+                return null;
+              }),
+          ),
+        );
+
+        console.log(`💧 Requested faucet funds for ${account.address}`);
+      } catch (error: any) {
+        console.warn(
+          `⚠️ Failed to request faucet funds for ${account.address}: ${error.message}`,
+        );
+        // Continue - don't break account creation
+      }
+    }
+
+    // Return account details
+    return {
+      name: props.name, // Always use the name from props for consistency
+      address: account.address,
+      faucet: props.faucet,
+    } as EvmAccount;
+  },
+);