changeset and lint

Author: gregfromstl

.changeset/clear-olives-know.md

@@ -0,0 +1,177 @@
+---
+"thirdweb": minor
+---
+
+Adds a new `Bridge` module to the thirdweb SDK to access the Universal Bridge.
+
+## Features
+
+### Buy & Sell Operations
+
+The Bridge module makes it easy to buy and sell tokens across chains:
+
+- `Bridge.Buy` - For specifying the destination amount you want to receive
+- `Bridge.Sell` - For specifying the origin amount you want to send
+
+Each operation provides two functions:
+1. `quote` - Get an estimate without connecting a wallet
+2. `prepare` - Get a finalized quote with transaction data
+
+#### Buy Example
+
+```typescript
+import { Bridge, toWei } from "thirdweb";
+
+// First, get a quote to see approximately how much you'll pay
+const buyQuote = await Bridge.Buy.quote({
+  originChainId: 1, // Ethereum
+  originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+  destinationChainId: 10, // Optimism
+  destinationTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+  buyAmountWei: toWei("0.01"), // I want to receive 0.01 ETH on Optimism
+  client: thirdwebClient,
+});
+
+console.log(`To get ${buyQuote.destinationAmount} wei on destination chain, you need to pay ${buyQuote.originAmount} wei`);
+
+// When ready to execute, prepare the transaction
+const preparedBuy = await Bridge.Buy.prepare({
+  originChainId: 1,
+  originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+  destinationChainId: 10,
+  destinationTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+  buyAmountWei: toWei("0.01"),
+  sender: "0x...", // Your wallet address
+  receiver: "0x...", // Recipient address (can be the same as sender)
+  client: thirdwebClient,
+});
+
+// The prepared quote contains the transactions you need to execute
+console.log(`Transactions to execute: ${preparedBuy.transactions.length}`);
+```
+
+#### Sell Example
+
+```typescript
+import { Bridge, toWei } from "thirdweb";
+
+// First, get a quote to see approximately how much you'll receive
+const sellQuote = await Bridge.Sell.quote({
+  originChainId: 1, // Ethereum
+  originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+  destinationChainId: 10, // Optimism
+  destinationTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+  sellAmountWei: toWei("0.01"), // I want to sell 0.01 ETH from Ethereum
+  client: thirdwebClient,
+});
+
+console.log(`If you send ${sellQuote.originAmount} wei, you'll receive approximately ${sellQuote.destinationAmount} wei`);
+
+// When ready to execute, prepare the transaction
+const preparedSell = await Bridge.Sell.prepare({
+  originChainId: 1,
+  originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+  destinationChainId: 10,
+  destinationTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+  sellAmountWei: toWei("0.01"),
+  sender: "0x...", // Your wallet address
+  receiver: "0x...", // Recipient address (can be the same as sender)
+  client: thirdwebClient,
+});
+
+// Execute the transactions in sequence
+for (const tx of preparedSell.transactions) {
+  // Send the transaction using your wallet
+  // Wait for it to be mined
+}
+```
+
+### Bridge Routes
+
+You can discover available bridge routes using the `routes` function:
+
+```typescript
+import { Bridge } from "thirdweb";
+
+// Get all available routes
+const allRoutes = await Bridge.routes({
+  client: thirdwebClient,
+});
+
+// Filter routes for a specific token or chain
+const filteredRoutes = await Bridge.routes({
+  originChainId: 1, // From Ethereum
+  originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+  destinationChainId: 10, // To Optimism
+  client: thirdwebClient,
+});
+
+// Paginate through routes
+const paginatedRoutes = await Bridge.routes({
+  limit: 10,
+  offset: 0,
+  client: thirdwebClient,
+});
+```
+
+### Bridge Transaction Status
+
+After executing bridge transactions, you can check their status:
+
+```typescript
+import { Bridge } from "thirdweb";
+
+// Check the status of a bridge transaction
+const bridgeStatus = await Bridge.status({
+  transactionHash: "0xe199ef82a0b6215221536e18ec512813c1aa10b4f5ed0d4dfdfcd703578da56d",
+  chainId: 8453, // The chain ID where the transaction was initiated
+  client: thirdwebClient,
+});
+
+// The status will be one of: "completed", "pending", or "failed"
+if (bridgeStatus.status === "completed") {
+  console.log(`
+    Bridge completed!
+    Sent: ${bridgeStatus.originAmount} wei on chain ${bridgeStatus.originChainId}
+    Received: ${bridgeStatus.destinationAmount} wei on chain ${bridgeStatus.destinationChainId}
+  `);
+} else if (bridgeStatus.status === "pending") {
+  console.log("Bridge transaction is still pending...");
+} else {
+  console.log("Bridge transaction failed");
+}
+```
+
+## Error Handling
+
+The Bridge module provides consistent error handling with descriptive error messages:
+
+```typescript
+try {
+  await Bridge.Buy.quote({
+    // ...params
+  });
+} catch (error) {
+  // Errors will have the format: "ErrorCode | Error message details"
+  console.error(error.message); // e.g. "AmountTooHigh | The provided amount is too high for the requested route."
+}
+```
+
+## Types
+
+The Bridge module exports the following TypeScript types:
+
+- `Route` - Describes a bridge route between chains and tokens
+- `Status` - Represents the status of a bridge transaction
+- `Quote` - Contains quote information for a bridge transaction
+- `PreparedQuote` - Extends Quote with transaction data
+
+## Integration
+
+The Bridge module is accessible as a top-level export:
+
+```typescript
+import { Bridge } from "thirdweb";
+```
+
+Use `Bridge.Buy`, `Bridge.Sell`, `Bridge.routes`, and `Bridge.status` to access the corresponding functionality.

packages/thirdweb/src/bridge/Routes.test.ts

@@ -1,8 +1,8 @@
-import { afterAll, beforeAll, afterEach, describe, expect, it } from "vitest";
-import { TEST_CLIENT } from "~test/test-clients.js";
-import { routes } from "./Routes.js";
 import { http, passthrough } from "msw";
 import { setupServer } from "msw/node";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { routes } from "./Routes.js";
 
 const server = setupServer(
   http.get("https://bridge.thirdweb.com/v1/routes", () => {
@@ -102,9 +102,9 @@ describe("Bridge.routes", () => {
           route.originToken.chainId === 1 &&
           route.destinationToken.chainId === 10 &&
           route.originToken.address ===
-          "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" &&
+            "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" &&
           route.destinationToken.address ===
-          "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+            "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
       ),
     ).toBe(true);
   });
@@ -154,6 +154,8 @@ describe("Bridge.routes", () => {
         limit: 1000,
         offset: 1000,
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Error: InvalidRoutesRequest | The provided request is invalid.]`);
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: InvalidRoutesRequest | The provided request is invalid.]`,
+    );
   });
 });

packages/thirdweb/src/bridge/Status.test.ts

@@ -5,7 +5,8 @@ import { status } from "./Status.js";
 describe("Bridge.status", () => {
   it("should handle invalid transaction hash without throwing", async () => {
     const result = await status({
-      transactionHash: "0xe199ef82a0b6215221536e18ec512813c1aa10b4f5ed0d4dfdfcd703578da56d",
+      transactionHash:
+        "0xe199ef82a0b6215221536e18ec512813c1aa10b4f5ed0d4dfdfcd703578da56d",
       chainId: 1,
       client: TEST_CLIENT,
     });
@@ -14,4 +15,4 @@ describe("Bridge.status", () => {
     expect(result.status).toBe("failed");
     expect(result.transactions).toBeDefined();
   });
-});
+});

packages/thirdweb/src/bridge/Status.ts

@@ -143,4 +143,4 @@ export declare namespace status {
   };
 
   type Result = Status;
-}
+}

packages/thirdweb/src/bridge/constants.ts

@@ -1 +1 @@
-export const UNIVERSAL_BRIDGE_URL = "https://bridge.thirdweb.com/v1";
+export const UNIVERSAL_BRIDGE_URL = "https://bridge.thirdweb.com/v1";

packages/thirdweb/src/bridge/index.ts

@@ -5,4 +5,4 @@ export { routes } from "./Routes.js";
 
 export type { Status } from "./types/Status.js";
 export type { Route } from "./types/Route.js";
-export type { Quote, PreparedQuote } from "./types/Quote.js";
+export type { Quote, PreparedQuote } from "./types/Quote.js";

packages/thirdweb/src/bridge/types/Quote.ts

@@ -39,4 +39,4 @@ export type PreparedQuote = Quote & {
       "eip1559"
     >
   >;
-};
+};

packages/thirdweb/src/bridge/types/Route.ts

@@ -17,4 +17,4 @@ export type Route = {
     name: string;
     iconUri?: string;
   };
-};
+};

packages/thirdweb/src/bridge/types/Status.ts

@@ -32,4 +32,4 @@ export type Status =
         chainId: number;
         transactionHash: ox__Hex.Hex;
       }>;
-    };
+    };

packages/thirdweb/src/exports/bridge.ts

@@ -1 +1 @@
-export * from "../bridge/index.js";
+export * from "../bridge/index.js";