@wonderland/interop 0.2.0 → 0.3.1

package/README.md

@@ -10,15 +10,15 @@ This package combines two powerful functionalities:
 
 ```mermaid
 graph LR
-    A[humanReadable]
+    A[interoperableName]
     C[binaryRepresentation]
     D[chainId]
     E[address]
     F[Cross-Chain Operations]
     G[Token Transfers]
 
-    A -->|humanReadableToBinary| C
-    C -->|binaryToHumanReadable| A
+    A -->|nameToBinary| C
+    C -->|binaryToName| A
     C -->|getChainId| D
     C -->|getAddress| E
     F -->|Transfer| G
@@ -49,38 +49,74 @@ Available scripts that can be run using `pnpm`:
 ### Interoperable Addresses
 
 ```typescript
-// Using the Provider
-import { InteropAddressProvider } from '@wonderland/interop';
+import { InteropAddressProvider, nameToBinary } from "@wonderland/interop";
 
-const humanReadableAddress = "alice.eth@eip155:1#ABCD1234"
-const binaryAddress = InteropAddressProvider.humanReadableToBinary(humanReadableAddress)
+// Using the Provider
+const interoperableName = "alice.eth@eip155:1#ABCD1234";
+const binaryAddress = await InteropAddressProvider.nameToBinary(interoperableName);
 
-// Or just importing the method
-import { humanReadableToBinary } from '@wonderland/interop';
-const binaryAddress = humanReadableToBinary(humanReadableAddress)
+// Or just importing the method directly
+const binaryAddress2 = await nameToBinary("alice.eth@eip155:1#ABCD1234");
 ```
 
 ### Cross-Chain Operations
 
 ```typescript
 import { createCrossChainProvider } from "@wonderland/interop";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { mainnet } from "viem/chains";
 
-// Create a provider for a specific protocol (e.g., Across)
+// Create a provider - Across works with no config (defaults to mainnet)
+// Mainnet: https://app.across.to/api
+// Testnet: https://testnet.across.to/api
 const provider = createCrossChainProvider("across");
 
-// Get a quote for a cross-chain transfer
-const quote = await provider.getQuote("crossChainTransfer", {
-    inputTokenAddress: "0x...",
-    outputTokenAddress: "0x...",
-    inputAmount: "1000000000000000000",
-    inputChainId: 1,
-    outputChainId: 137,
-    sender: "0x...",
-    recipient: "0x...",
+// Or with testnet config
+const testnetProvider = createCrossChainProvider("across", { isTestnet: true });
+
+// Get quotes using OIF format (addresses must be EIP-7930 binary format: 0x0001...)
+// Use nameToBinary() from @wonderland/interop-addresses to convert human-readable addresses
+const quotes = await provider.getQuotes({
+    user: "0x0001000aa36a7114...", // binary format address
+    intent: {
+        intentType: "oif-swap",
+        inputs: [
+            {
+                user: "0x0001000aa36a7114...",
+                asset: "0x0001000aa36a7114...",
+                amount: "1000000000000000000",
+            },
+        ],
+        outputs: [
+            {
+                receiver: "0x0001000149d4114...",
+                asset: "0x0001000149d4114...",
+            },
+        ],
+        swapType: "exact-input",
+    },
+    supportedTypes: ["oif-escrow-v0"],
 });
 
-// Simulate the transaction
-const transactions = await provider.simulateOpen(quote.openParams);
+// Execute the quote
+const quote = quotes[0];
+const walletClient = createWalletClient({
+    chain: mainnet,
+    transport: http("https://..."),
+    account: "0x...",
+});
+
+// Option 1 - User Mode: send transaction directly (Across, OIF user-open)
+if (quote?.preparedTransaction) {
+    const hash = await walletClient.sendTransaction(quote.preparedTransaction);
+}
+
+// Option 2 - Protocol Mode: sign and submit order (OIF escrow - gasless for user)
+if (quote?.order.type === "oif-escrow-v0") {
+    const { domain, primaryType, message, types } = quote.order.payload;
+    const signature = await walletClient.signTypedData({ domain, primaryType, message, types });
+    await provider.submitSignedOrder(quote, signature);
+}
 ```
 
 ## API
@@ -91,41 +127,70 @@ const transactions = await provider.simulateOpen(quote.openParams);
 
 Available methods:
 
--   `humanReadableToBinary(humanReadableAddress: string)`
--   `binaryToHumanReadable(binaryAddress: Hex)`
--   `getChainId(binaryAddress: Hex)`
--   `getAddress(binaryAddress: Hex)`
--   `buildFromPayload(payload: InteropAddressFields)`
--   `computeChecksum(humanReadableAddress: string)`
+-   `nameToBinary(interoperableName: string)` – Convert human-readable address to binary format
+-   `binaryToName(binaryAddress: Hex)` – Convert binary address to human-readable format
+-   `getChainId(address: string)` – Extract chain ID from an address
+-   `getAddress(address: string)` – Extract the underlying address
+-   `encodeAddress(payload: InteroperableAddress, opts?: { format: "hex" | "bytes" })` – Create binary address from components
+-   `computeChecksum(interoperableName: string)` – Compute checksum for an address
 
 ### Cross-Chain Operations
 
-#### [CrossChainProviderFactory](./src/services/crossChainProviderFactory.ts)
+#### [createCrossChainProvider](./src/services/crossChainProviderFactory.ts)
 
-The factory provides a standardized way to create and manage cross-chain providers for different protocols.
+Creates a provider for the specified protocol:
 
-Available methods:
+```typescript
+// Across - config optional (defaults to mainnet)
+const acrossProvider = createCrossChainProvider("across");
+const testnetProvider = createCrossChainProvider("across", { isTestnet: true });
+
+// OIF - config required
+const oifProvider = createCrossChainProvider("oif", {
+    solverId: "my-solver",
+    url: "https://solver.example.com",
+});
+```
 
--   `build<Protocol>(protocolName: Protocol, config?: Config, dependencies?: Dependencies)`: Creates a new provider instance for the specified protocol
--   `createCrossChainProvider<Protocol>(protocolName: Protocol, config?: Config, dependencies?: Dependencies)`: Helper function to create a provider instance
+#### CrossChainProvider
 
-#### [CrossChainExecutor](./src/services/crossChainExecutor.ts)
+All providers implement these methods:
 
-The executor handles the execution of cross-chain operations, providing a unified interface for different protocols.
+-   `.getQuotes(params)` – Returns `ExecutableQuote[]`. Fetch quotes for a cross-chain request (OIF GetQuoteRequest format).
+-   `.submitSignedOrder(quote, signature)` – Submit a signed order (OIF escrow mode). Throws for Across.
+-   `.getProtocolName()` – Returns the protocol name.
+-   `.getProviderId()` – Returns the provider identifier.
+-   `.getTrackingConfig()` – Get configuration for intent tracking.
 
-Available methods:
+#### [ProviderExecutor](./src/services/providerExecutor.ts)
 
--   `execute(params: ExecutionParams)`: Executes a cross-chain operation
--   `getQuotes(params: QuoteParams)`: Gets a quote for a cross-chain operation
+For comparing quotes across multiple providers:
+
+```typescript
+import { createProviderExecutor } from "@wonderland/interop";
+
+const executor = createProviderExecutor({
+    providers: [acrossProvider, oifProvider],
+});
+
+// Returns { quotes: ExecutableQuote[], errors: GetQuotesError[] }
+const response = await executor.getQuotes({
+    /* ... */
+});
+
+const bestQuote = response.quotes[0]; // Sorted by best output
+```
 
 Supported protocols:
 
 -   Across Protocol
+-   OIF (Open Intents Framework)
 -   More protocols coming soon...
 
 ## References
 
 -   [ERC 7930: Interoperable Addresses](https://ethereum-magicians.org/t/erc-7930-interoperable-addresses/23365)
+-   [Open Intents Framework](https://docs.openintents.xyz/) - OIF API specification
 -   [Viem Documentation](https://viem.sh/) - Low-level Ethereum interface used for transaction handling
 -   [Zod Documentation](https://zod.dev/) - TypeScript-first schema validation used for input validation
 -   [Cross-Chain Interoperability Standards](https://ethereum.org/en/developers/docs/bridges/) - Overview of cross-chain bridge concepts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wonderland/interop",
-    "version": "0.2.0",
+    "version": "0.3.1",
     "description": "Complete SDK for blockchain interoperability with cross-chain operations and address utilities",
     "repository": {
         "type": "git",
@@ -32,7 +32,7 @@
         "test:cov": "vitest run --config vitest.config.ts --coverage"
     },
     "dependencies": {
-        "@wonderland/interop-addresses": "0.2.0",
-        "@wonderland/interop-cross-chain": "0.2.0"
+        "@wonderland/interop-addresses": "0.4.0",
+        "@wonderland/interop-cross-chain": "0.3.0"
     }
 }