token salt guard

Author: jakeloo

packages/thirdweb/src/exports/tokens.ts

@@ -13,6 +13,11 @@ export { createToken } from "../tokens/create-token.js";
 export { distributeToken } from "../tokens/distribute-token.js";
 export { getDeployedEntrypointERC20 } from "../tokens/get-entrypoint-erc20.js";
 export { isRouterEnabled } from "../tokens/is-router-enabled.js";
+export {
+  generateSalt,
+  SaltFlag,
+  type SaltFlagType,
+} from "../tokens/token-utils.js";
 export type {
   CreateTokenByImplementationConfigOptions,
   CreateTokenOptions,

packages/thirdweb/src/tokens/create-token.ts

@@ -1,13 +1,16 @@
+import { bytesToHex, randomBytes } from "@noble/hashes/utils";
 import type { Hex } from "viem";
 import { parseEventLogs } from "../event/actions/parse-logs.js";
 import { createdEvent } from "../extensions/tokens/__generated__/ERC20Entrypoint/events/Created.js";
 import { create } from "../extensions/tokens/__generated__/ERC20Entrypoint/write/create.js";
 import { sendAndConfirmTransaction } from "../transaction/actions/send-and-confirm-transaction.js";
-import { keccakId } from "../utils/any-evm/keccak-id.js";
-import { toHex } from "../utils/encoding/hex.js";
 import { DEFAULT_REFERRER_ADDRESS } from "./constants.js";
 import { getOrDeployEntrypointERC20 } from "./get-entrypoint-erc20.js";
-import { encodeInitParams, encodePoolConfig } from "./token-utils.js";
+import {
+  encodeInitParams,
+  encodePoolConfig,
+  generateSalt,
+} from "./token-utils.js";
 import type { CreateTokenOptions } from "./types.js";
 
 export async function createToken(options: CreateTokenOptions) {
@@ -20,18 +23,7 @@ export async function createToken(options: CreateTokenOptions) {
     params,
   });
 
-  let salt: Hex = "0x";
-  if (!options.salt) {
-    salt = `0x1f${toHex(creator, {
-      size: 32,
-    }).substring(4)}`;
-  } else {
-    if (options.salt.startsWith("0x") && options.salt.length === 66) {
-      salt = options.salt;
-    } else {
-      salt = `0x1f${keccakId(options.salt).substring(4)}`;
-    }
-  }
+  const salt: Hex = generateSalt(options.salt || bytesToHex(randomBytes(31)));
 
   const entrypoint = await getOrDeployEntrypointERC20(options);
 

packages/thirdweb/src/tokens/token-utils.test.ts

@@ -0,0 +1,46 @@
+import { isHex } from "viem/utils";
+import { describe, expect, it } from "vitest";
+
+import { generateSalt, SaltFlag } from "./token-utils.js";
+
+// Helper to validate the generated salt meets core guarantees
+function assertValidSalt(out: string, expectedFlagHex: string) {
+  // should be valid hex
+  console.log("out", out);
+  expect(isHex(out)).toBe(true);
+  // 0x prefix + 64 hex chars → 32 bytes
+  expect(out.length).toBe(66);
+  // first byte must match the expected flag
+  expect(out.slice(0, 4).toLowerCase()).toBe(expectedFlagHex.toLowerCase());
+}
+
+describe("generateSalt", () => {
+  it("handles hex shorter than 32 bytes (padding)", () => {
+    const shortHex = "0x123456"; // 3 bytes < 32 bytes
+    const out = generateSalt(shortHex);
+    assertValidSalt(out, "0x01"); // default flag is MIX_SENDER (0x01)
+  });
+
+  it("handles exactly 32-byte hex and overrides explicit flag with salt's flag", () => {
+    const hex32 = `0x20${"aa".repeat(31)}`; // first byte 0x20, total 32 bytes
+    const out = generateSalt(hex32, SaltFlag.BYPASS); // pass a different flag intentionally
+    // even though we requested BYPASS (0x80), the salt's first byte (0x20) wins
+    assertValidSalt(out, "0x20");
+  });
+
+  it("handles hex longer than 32 bytes (hashing)", () => {
+    const longHex = `0x${"ff".repeat(80)}`; // 80 bytes > 32 bytes
+    const out = generateSalt(longHex);
+    assertValidSalt(out, "0x01"); // default flag retained
+  });
+
+  it("handles arbitrary non-hex string (hashed)", () => {
+    const out = generateSalt("hello world");
+    assertValidSalt(out, "0x01");
+  });
+
+  it("respects explicit flag parameter when provided", () => {
+    const out = generateSalt("foobar", SaltFlag.BYPASS);
+    assertValidSalt(out, "0x80");
+  });
+});

packages/thirdweb/src/tokens/token-utils.ts

@@ -1,4 +1,5 @@
-import type { Hex } from "viem";
+import { type Hex, keccak256 } from "viem";
+import { isHex, toBytes } from "viem/utils";
 import type { ThirdwebClient } from "../client/client.js";
 import { NATIVE_TOKEN_ADDRESS } from "../constants/addresses.js";
 import { encodeInitialize } from "../extensions/tokens/__generated__/ERC20Asset/write/initialize.js";
@@ -12,6 +13,25 @@ import {
 } from "./constants.js";
 import type { PoolConfig, TokenParams } from "./types.js";
 
+export const SaltFlag = {
+  /** Mix in msg.sender */
+  MIX_SENDER: 0x01,
+  /** Mix in block.chainid */
+  MIX_CHAIN_ID: 0x02,
+  /** Mix in block.number */
+  MIX_BLOCK_NUMBER: 0x04,
+  /** Mix in contractInitData */
+  MIX_CONTRACT_INIT_DATA: 0x08,
+  /** Mix in hookInitData */
+  MIX_HOOK_INIT_DATA: 0x10,
+  /** Mix in creator address */
+  MIX_CREATOR: 0x20,
+  /** Bypass mode – disable all transformations */
+  BYPASS: 0x80,
+} as const;
+
+export type SaltFlagType = (typeof SaltFlag)[keyof typeof SaltFlag];
+
 export async function encodeInitParams(options: {
   client: ThirdwebClient;
   params: TokenParams;
@@ -75,3 +95,63 @@ export function encodePoolConfig(poolConfig: PoolConfig): Hex {
     poolConfig.referrerRewardBps || DEFAULT_REFERRER_REWARD_BPS,
   ]);
 }
+
+export function generateSalt(
+  salt: Hex | string,
+  flags: SaltFlagType = SaltFlag.MIX_SENDER,
+): Hex {
+  /*
+   * The salt layout follows the on-chain convention documented in the `guardSalt` Solidity helper.
+   *   [0x00] – 1 byte  : flags (bits 0-7)
+   *   [0x01-0x1F] – 31 bytes : user-provided entropy
+   *
+   * This helper makes it easy to prepare a salt off-chain that can be passed to
+   * the contract. It guarantees the returned value is always 32 bytes (66 hex
+   * chars including the `0x` prefix) and allows callers to optionally pass a
+   * custom salt and/or explicit flag byte.
+   */
+
+  let flagByte: number = flags;
+
+  // If the salt is already a valid 32-byte hex string, we can use it as is and extract the flag byte
+  if (salt && isHex(salt)) {
+    const hex = salt.replace(/^0x/i, "");
+    if (hex.length === 64) {
+      flagByte = parseInt(hex.slice(0, 2), 16) as SaltFlagType;
+      salt = `0x${hex.slice(2)}` as Hex;
+    } else if (hex.length < 64) {
+      // If the salt is less than 31 bytes, we need to pad it with zeros (first 2 bytes are the flag byte)
+      salt = `0x${hex.padStart(62, "0")}` as Hex;
+    } else if (hex.length > 64) {
+      // If the salt is greater than 32 bytes, we need to keccak256 it.
+      // first 2 bytes are the flag byte, and truncate to 31 bytes
+      salt = `0x${keccak256(toBytes(hex)).slice(4)}` as Hex;
+    }
+  } else if (salt && !isHex(salt)) {
+    // 31 bytes of salt data
+    salt = `0x${keccak256(toBytes(salt)).slice(4)}` as Hex;
+  }
+
+  // If the flag byte is not a valid 8-bit unsigned integer, throw an error
+  if (flagByte < 0 || flagByte > 0xff) {
+    throw new Error("flags must be an 8-bit unsigned integer (0-255)");
+  }
+
+  const saltData = salt.replace(/^0x/i, "");
+  if (saltData.length !== 62) {
+    // 31 bytes * 2 hex chars
+    throw new Error(
+      "salt data (excluding flag byte) cannot exceed 31 bytes (62 hex characters)",
+    );
+  }
+
+  const result =
+    `0x${flagByte.toString(16).padStart(2, "0")}${saltData}` as Hex;
+
+  // Final sanity check – should always be 32 bytes / 66 hex chars (including 0x)
+  if (result.length !== 66) {
+    throw new Error("generated salt must be 32 bytes");
+  }
+
+  return result;
+}