Merge branch 'main' into gi/portal-knowledge-base

Author: GiselleNessi

.changeset/open-readers-do.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Faster useSendTransaction execution

.changeset/shiny-olives-pay.md

@@ -0,0 +1,154 @@
+---
+"thirdweb": minor
+---
+
+Adds Bridge.Transfer module for direct token transfers:
+
+```typescript
+import { Bridge, NATIVE_TOKEN_ADDRESS } from "thirdweb";
+
+const quote = await Bridge.Transfer.prepare({
+  chainId: 1,
+  tokenAddress: NATIVE_TOKEN_ADDRESS,
+  amount: toWei("0.01"),
+  sender: "0x...",
+  receiver: "0x...",
+  client: thirdwebClient,
+});
+```
+
+This will return a quote that might look like:
+```typescript
+{
+  originAmount: 10000026098875381n,
+  destinationAmount: 10000000000000000n,
+  blockNumber: 22026509n,
+  timestamp: 1741730936680,
+  estimatedExecutionTimeMs: 1000
+  steps: [
+    {
+      originToken: {
+        chainId: 1,
+        address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        symbol: "ETH",
+        name: "Ethereum",
+        decimals: 18,
+        priceUsd: 2000,
+        iconUri: "https://..."
+      },
+      destinationToken: {
+        chainId: 1,
+        address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        symbol: "ETH",
+        name: "Ethereum",
+        decimals: 18,
+        priceUsd: 2000,
+        iconUri: "https://..."
+      },
+      originAmount: 10000026098875381n,
+      destinationAmount: 10000000000000000n,
+      estimatedExecutionTimeMs: 1000
+      transactions: [
+        {
+          action: "approval",
+          id: "0x",
+          to: "0x...",
+          data: "0x...",
+          chainId: 1,
+          type: "eip1559"
+        },
+        {
+          action: "transfer",
+          to: "0x...",
+          value: 10000026098875381n,
+          data: "0x...",
+          chainId: 1,
+          type: "eip1559"
+        }
+      ]
+    }
+  ],
+  expiration: 1741730936680,
+  intent: {
+    chainId: 1,
+    tokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+    amount: 10000000000000000n,
+    sender: "0x...",
+    receiver: "0x..."
+  }
+}
+```
+
+## Sending the transactions
+The `transactions` array is a series of [ox](https://oxlib.sh) EIP-1559 transactions that must be executed one after the other in order to fulfill the complete route. There are a few things to keep in mind when executing these transactions:
+ - Approvals will have the `approval` action specified. You can perform approvals with `sendAndConfirmTransaction`, then proceed to the next transaction.
+ - All transactions are assumed to be executed by the `sender` address, regardless of which chain they are on. The final transaction will use the `receiver` as the recipient address.
+ - If an `expiration` timestamp is provided, all transactions must be executed before that time to guarantee successful execution at the specified price.
+
+NOTE: To get the status of each non-approval transaction, use `Bridge.status` rather than checking for transaction inclusion. This function will ensure full completion of the transfer.
+
+You can include arbitrary data to be included on any webhooks and status responses with the `purchaseData` option:
+
+```ts
+const quote = await Bridge.Transfer.prepare({
+  chainId: 1,
+  tokenAddress: NATIVE_TOKEN_ADDRESS,
+  amount: toWei("0.01"),
+  sender: "0x...",
+  receiver: "0x...",
+  purchaseData: {
+    reference: "payment-123",
+    metadata: {
+      note: "Transfer to Alice"
+    }
+  },
+  client: thirdwebClient,
+});
+```
+
+## Fees
+There may be fees associated with the transfer. These fees are paid by the `feePayer` address, which defaults to the `sender` address. You can specify a different address with the `feePayer` option. If you do not specify an option or explicitly specify `sender`, the fees will be added to the input amount. If you specify the `receiver` as the fee payer the fees will be subtracted from the destination amount.
+
+For example, if you were to request a transfer with `feePayer` set to `receiver`:
+```typescript
+const quote = await Bridge.Transfer.prepare({
+  chainId: 1,
+  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+  amount: 100_000_000n, // 100 USDC
+  sender: "0x...",
+  receiver: "0x...",
+  feePayer: "receiver",
+  client: thirdwebClient,
+});
+```
+
+The returned quote might look like:
+```typescript
+{
+  originAmount: 100_000_000n, // 100 USDC
+  destinationAmount: 99_970_000n, // 99.97 USDC
+  ...
+}
+```
+
+If you were to request a transfer with `feePayer` set to `sender`:
+```typescript
+const quote = await Bridge.Transfer.prepare({
+  chainId: 1,
+  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+  amount: 100_000_000n, // 100 USDC
+  sender: "0x...",
+  receiver: "0x...",
+  feePayer: "sender",
+  client: thirdwebClient,
+});
+```
+
+The returned quote might look like:
+```typescript
+{
+  originAmount: 100_030_000n, // 100.03 USDC
+  destinationAmount: 100_000_000n, // 100 USDC
+  ...
+}
+```

.changeset/six-dryers-sing.md

@@ -0,0 +1,79 @@
+---
+"thirdweb": patch
+---
+
+Added Bridge.Onramp.prepare and Bridge.Onramp.status functions
+
+## Bridge.Onramp.prepare
+
+Prepares an onramp transaction, returning a link from the specified provider to onramp to the specified token.
+
+```typescript
+import { Bridge } from "thirdweb";
+import { ethereum } from "thirdweb/chains";
+import { NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb/utils";
+
+const preparedOnramp = await Bridge.Onramp.prepare({
+  client: thirdwebClient,
+  onramp: "stripe",
+  chainId: ethereum.id,
+  tokenAddress: NATIVE_TOKEN_ADDRESS,
+  receiver: "0x...", // receiver's address
+  amount: toWei("10"), // 10 of the destination token
+  // Optional params:
+  // sender: "0x...", // sender's address
+  // onrampTokenAddress: NATIVE_TOKEN_ADDRESS, // token to initially onramp to
+  // onrampChainId: 1, // chain to initially onramp to
+  // currency: "USD",
+  // maxSteps: 2,
+  // purchaseData: { customId: "123" }
+});
+
+console.log(preparedOnramp.link); // URL to redirect the user to
+console.log(preparedOnramp.currencyAmount); // Price in fiat currency
+```
+
+## Bridge.Onramp.status
+
+Retrieves the status of an Onramp session created via Bridge.Onramp.prepare.
+
+```typescript
+import { Bridge } from "thirdweb";
+
+const onrampStatus = await Bridge.Onramp.status({
+  id: "022218cc-96af-4291-b90c-dadcb47571ec",
+  client: thirdwebClient,
+});
+
+// Possible results:
+// {
+//   status: "CREATED",
+//   transactions: [],
+//   purchaseData: {
+//     orderId: "abc-123",
+//   },
+// }
+//
+// or
+// {
+//   status: "PENDING",
+//   transactions: [],
+//   purchaseData: {
+//     orderId: "abc-123",
+//   },
+// }
+//
+// or
+// {
+//   status: "COMPLETED",
+//   transactions: [
+//     {
+//       chainId: 1,
+//       transactionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+//     },
+//   ],
+//   purchaseData: {
+//     orderId: "abc-123",
+//   },
+// }
+```

.changeset/stale-yaks-bathe.md

@@ -14,7 +14,7 @@ We use [Turborepo](https://turbo.build/repo/docs) to manage the repository, and
 
 We use [pnpm](https://pnpm.io) for package management across the repo. `pnpm` is similar to `npm` or `yarn` but with more efficient disk space usage.
 
-**With the v5 SDK, we've consolidated everything into a single project at [/packages/thirdweb](./packages/thirdweb). You can still find the legacy packages at [/legacy_packages](./legacy_packages).**
+**With the v5 SDK, we've consolidated everything into a single project at [/packages/thirdweb](../packages/thirdweb). You can still find the legacy packages at [/legacy_packages](../legacy_packages).**
 
 This single package provides a performant & lightweight SDK to interact with any EVM chain across Node, React, and React Native. Learn more about how to use the thirdweb SDK in our [documentation](https://portal.thirdweb.com/typescript/v5).
 

.changeset/tidy-seas-sing.md

@@ -0,0 +1,123 @@
+🤖 Codex Agent Guidelines for thirdweb-dev/js
+
+Welcome, AI copilots! This guide captures the coding standards, architectural decisions, and workflow conventions that every automated agent (and human contributor!) must follow. Unless a rule explicitly targets a sub‑project, it applies repo‑wide.
+
+⸻
+
+1. GitHub Workflow & Etiquette
+
+- Pull‑request titles must start with the affected workspace in brackets (e.g. [SDK], [Dashboard], [Portal], [Playground]).
+- Begin the PR description with a one‑sentence summary, then add a checklist of changes and reference issues with Fixes #123.
+- Keep commits small and topical – one logical change per commit.
+- Branch names should follow area/brief-topic (e.g. sdk/fix-gas-estimate). Avoid personal names.
+- Request at least one core maintainer review. Do not self‑merge unless you are the sole owner of that package.
+- All CI checks (type‑check, Biome, tests) must pass before merging.
+
+⸻
+
+2. Formatting & Linting
+
+- Biome governs formatting and linting; its rules live in biome.json.
+- Run pnpm biome check --apply before committing.
+- Avoid editor‑specific configs; rely on the shared settings.
+
+⸻
+
+3. TypeScript Style Guide
+
+- Write idiomatic TypeScript: explicit function declarations and return types.
+- Limit each file to one stateless, single‑responsibility function for clarity and testability.
+- Re‑use shared types from @/types or local types.ts barrels.
+- Prefer type aliases over interface except for nominal shapes.
+- Avoid any and unknown unless unavoidable; narrow generics whenever possible.
+- Choose composition over inheritance; leverage utility types (Partial, Pick, etc.).
+
+⸻
+
+4. Testing Strategy
+
+- Co‑locate tests: foo.ts ↔ foo.test.ts.
+- Use real function invocations with stub data; avoid brittle mocks.
+- For network interactions, use Mock Service Worker (MSW) to intercept fetch/HTTP calls, mocking only scenarios that are hard to reproduce.
+- Keep tests deterministic and side‑effect free; Jest is pre‑configured.
+
+⸻
+
+5. packages/thirdweb
+
+5.1 Public API Surface
+
+- Export everything via the exports/ directory, grouped by feature.
+- Every public symbol must have comprehensive TSDoc:
+- Include at least one @example block that compiles.
+- Tag with one custom annotation (@beta, @internal, @experimental, etc.).
+- Comment only ambiguous logic; avoid restating TypeScript in prose.
+
+  5.2 Performance
+
+- Lazy‑load heavy dependencies inside async paths to keep the initial bundle lean:
+
+`const { jsPDF } = await import("jspdf");`
+
+⸻
+
+6. apps/dashboard & apps/playground
+
+6.1 Core UI Toolkit
+
+- Import primitives from @/components/ui/\_ (e.g. Button, Input, Select, Tabs, Card, Sidebar, Badge, Separator).
+- Use NavLink for internal navigation so active states are handled automatically.
+- Group feature‑specific components under feature/components/\_ and expose a barrel index.ts when necessary.
+
+  6.2 Styling Conventions
+
+- Tailwind CSS is the styling system – no inline styles or CSS modules.
+- Merge class names with cn() from @/lib/utils to keep conditional logic readable.
+- Stick to design tokens: backgrounds (bg-card), borders (border-border), muted text (text-muted-foreground), etc.
+- Expose a className prop on the root element of every component for overrides.
+
+  6.3 Component Patterns
+
+- Server Components (run on the Node edge):
+  -- Read cookies/headers with next/headers.
+  -- Access server‑only environment variables or secrets.
+  -- Perform heavy data fetching that should not ship to the client.
+  -- Implement redirect logic with redirect() from next/navigation.
+  -- Start files with import "server-only"; to prevent client bundling.
+- Client Components (run in the browser):
+  -- Begin files with 'use client'; before imports.
+  -- Handle interactive UI relying on React hooks (useState, useEffect, React Query, wallet hooks).
+  -- Access browser APIs (localStorage, window, IntersectionObserver, etc.).
+  -- Support fast transitions where data is prefetched on the client.
+
+  6.4 Data Fetching Guidelines
+
+- Server Side
+  -- Always call getAuthToken() to retrieve the JWT from cookies.
+  -- Inject the token as an Authorization: Bearer header – never embed it in the URL.
+  -- Return typed results (Project[], User[], …) – avoid any.
+- Client Side
+  -- Wrap calls in React Query (@tanstack/react-query).
+  -- Use descriptive, stable queryKeys for cache hits.
+  -- Configure staleTime / cacheTime based on freshness requirements (default ≥ 60 s).
+  -- Keep tokens secret by calling internal API routes or server actions.
+
+⸻
+
+7. Performance & Bundle Size
+
+- Track bundle budgets via package.json#size-limit.
+- Lazy‑import optional features; avoid top‑level side‑effects.
+- De‑duplicate dependencies across packages through pnpm workspace hoisting.
+
+⸻
+
+8. Documentation & Developer Experience
+
+- Each change in packages/\* should contain a changeset for the appropriate package, with the appropriate version bump
+
+  - patch for changes that don't impact the public API
+  - minor for any new/modified public API
+
+- Surface breaking changes prominently in PR descriptions.
+- For new UI components, add Storybook stories (\*.stories.tsx) alongside the code.